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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <87y4asr1by.fsf@intel.com>
Date:	Wed, 10 Feb 2016 18:12:49 +0200
From:	Jani Nikula <jani.nikula@...el.com>
To:	Daniel Vetter <daniel.vetter@...ll.ch>,
	Jonathan Corbet <corbet@....net>
Cc:	linux-doc@...r.kernel.org,
	Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
	Keith Packard <keithp@...thp.com>
Subject: Re: [RFC] A first shot at asciidoc-based formatted docs

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