linux-kernel - Re: Kernel docs: muddying the waters a bit

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-next>] [day] [month] [year] [list]

Message-ID: <87a8m9qoy8.fsf@intel.com>
Date:	Tue, 08 Mar 2016 11:49:35 +0200
From:	Jani Nikula <jani.nikula@...el.com>
To:	Dan Allen <dan@...ndevise.io>, Russel Winder <russel@...der.org.uk>
Cc:	Keith Packard <keithp@...thp.com>,
	Mauro Carvalho Chehab <mchehab@....samsung.com>,
	Jonathan Corbet <corbet@....net>,
	LKML <linux-kernel@...r.kernel.org>, linux-doc@...r.kernel.org,
	Daniel Vetter <daniel.vetter@...ll.ch>,
	Hans Verkuil <hverkuil@...all.nl>, linux-media@...r.kernel.org,
	Graham Whaley <graham.whaley@...ux.intel.com>
Subject: Re: Kernel docs: muddying the waters a bit

On Tue, 08 Mar 2016, Dan Allen <dan@...ndevise.io> wrote:
> One of the key goals of the Asciidoctor project is to be able to directly
> produce a wide variety of outputs from the same source (without DocBook).
> We've added flexibility and best practices into the syntax and matured the
> converter mechanism to bridge this (sometimes very wide) gap.

I think our conclusion so far was that the native AsciiDoc (and
Asciidoctor) outputs fell short of our needs, forcing us to use the
DocBook pipeline. I, for one, was hoping we could eventually simplify
the toolchain. For example, there was no support for chunked, or split
to chapters, HTML, and the single page result was simply way too big.

> Asciidoctor is the future of AsciiDoc. Even the AsciiDoc Python maintainers
> acknowledge that (including the original creator).

Thanks for the input. We've touched the topic of AsciiDoc
vs. Asciidoctor before [1]. So we should be using Asciidoctor instead of
AsciiDoc. That actually makes choosing asciidoc harder, because
requiring another language environment complicates, not simplifies, the
toolchain. I'd really like to lower the bar for building the
documentation, for everyone, so much so that it becomes part of the
normal checks for patch inclusion.

BR,
Jani.

[1] http://mid.gmane.org/86pow31ddj.fsf@hiro.keithp.com

-- 
Jani Nikula, Intel Open Source Technology Center