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: <20160126075204.6f6bd0e2@lwn.net>
Date:	Tue, 26 Jan 2016 07:52:04 -0700
From:	Jonathan Corbet <corbet@....net>
To:	Jani Nikula <jani.nikula@...el.com>
Cc:	linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
	Daniel Vetter <daniel.vetter@...ll.ch>
Subject: Re: [RFC] A first shot at asciidoc-based formatted docs

On Tue, 26 Jan 2016 07:48:21 -0700
Jonathan Corbet <corbet@....net> wrote:

> For HTML-page splitting, we can see if the tools can help us, consider
> splitting the template files, or do the splitting in a postprocessing
> step.  Docproc (or whatever replaces it) could also maybe do that work.
> It doesn't seem to me something that should force the inclusion of an
> entire XML-based processing step.  
> 
> 
> 
> But then, I'm here spouting ideas without any proof to back them up again,
> so who knows...:)
> 
> Thanks for doing this work.  As you said, it has been demonstrated 

So let's try this again without hitting that "send" button prematurely,
sigh.  Claws is annoying sometimes.

You'd said:

> (We could of course split the source documents, but then I believe we'd
> have lots of trouble cross-referencing between the documents. I could be
> proven wrong. I'd *like* to be proven wrong.)

I'd like to solve the cross-reference problem anyway; the documents
shouldn't be silos unto themselves.  Sphinx and ReST can do that; I *bet*
the other formats can too.  Maybe I can dig into some of that in my
upcoming airplane time (LAX->MEL, 15:45, sigh).

> I should also remind us that the original goal was to enable lightweight
> markup for documentation. This seems very much achievable now.

Agreed, nice work.

jon