Re: [RFC] A first shot at asciidoc-based formatted docs

[Jani Nikula <jani.nikula@intel.com>]

On Wed, 10 Feb 2016, Jani Nikula <jani.nikula@intel.com> wrote:
>> On Wed, Feb 10, 2016 at 1:09 AM, Jonathan Corbet <corbet@lwn.net> 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