From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752621AbcBJQNJ (ORCPT ); Wed, 10 Feb 2016 11:13:09 -0500 Received: from mga01.intel.com ([192.55.52.88]:9846 "EHLO mga01.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752442AbcBJQNF (ORCPT ); Wed, 10 Feb 2016 11:13:05 -0500 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.22,426,1449561600"; d="scan'208";a="912402669" From: Jani Nikula To: Daniel Vetter , Jonathan Corbet Cc: linux-doc@vger.kernel.org, Linux Kernel Mailing List , Keith Packard Subject: Re: [RFC] A first shot at asciidoc-based formatted docs In-Reply-To: <87ziv8zmpx.fsf@intel.com> Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo References: <1453764522-29030-1-git-send-email-corbet@lwn.net> <20160209170938.3a4b9fb1@lwn.net> <87ziv8zmpx.fsf@intel.com> User-Agent: Notmuch/0.21+33~g570c0ae (http://notmuchmail.org) Emacs/24.4.1 (x86_64-pc-linux-gnu) Date: Wed, 10 Feb 2016 18:12:49 +0200 Message-ID: <87y4asr1by.fsf@intel.com> MIME-Version: 1.0 Content-Type: text/plain Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Wed, 10 Feb 2016, Jani Nikula wrote: >> On Wed, Feb 10, 2016 at 1:09 AM, Jonathan Corbet wrote: >>> - I'm not sold on the new inclusion mechanism. Creating thousands of >>> little files and tracking them for dependencies and such doesn't seem >>> like a simplification or a path toward better performance. I would >>> like to at least consider keeping the direct-from-source inclusion. ... > Yes, my main motivation here was to get rid of the preprocessing step > (currently tmpl->xml). I wanted to have the source documents in pure > markup which could be directly processed by asciidoc. I wanted to have > the editor markup helpers and syntax highlighting just work, with no > extra non-markup cruft to confuse it. (For example, emacs tells me the > current tmpl files are invalid XML because of the docproc directives.) > This ties back to the dream above; just have .txt files with no > preprocessing step, IMO it's less confusing for actually writing the > docs. I suppose a compromise could be to put the docproc directives in asciidoc comments to keep the files pure asciidoc and to hide the preprocessing step from the document writers, i.e. call them asciidoc and name them .txt instead of .tmpl or something. While I'm not thrilled about the idea of keeping docproc around, this would be progress, would avoid the EXPORT_SYMBOL problem for now, and, most importantly, wouldn't block us from doing what I suggested as a future iteration. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center