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 for Android: free password hash cracker in your pocket

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

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

Jonathan Corbet <corbet@....net> writes:

> asciidoc->HTML on its own isn't viable, I think; we do have people wanting
> other formats.  Though one might well ask when somebody last successfully
> generated PDF...maybe it's not worth the trouble.  I would like epub
> someday...

I'm hopeful that I can hack up asciidoc to generate usable HTML
directly. Once we've got HTML, we've got epub.

If we don't want to use docbook for pdf, asciidoc has a native latex
backend. That's in about the same shape as the html backend. Would that
be better than docbook?

> There's also people who actually use the man-page output.  I don't think
> that should require the xml step; getting rid of that might make it
> possible to do "make mandocs" and have it finish before the next merge
> window opens...

Adding a troff backend to asciidoc would be simple enough; I'm not sure
what other method you'd suggest here.

> We talked about that a bit in Geelong; the short-term idea was to generate
> a TOC and use CSS to place it correctly.  Daniel, if I heard you correctly,
> you thought that would be a fine solution that would remove the need for
> chunked output.  Keith seemed interested in looking into this too.

Here's an example that takes the docbook output with some simple CSS
hacks to place the TOC alongside the document in a separate scrolling
list. With a small bit of javascript, I'm pretty sure that could have
collapsible entries.

-- 
-keith

Download attachment "signature.asc" of type "application/pgp-signature" (811 bytes)