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

Message-ID: <87poszgr92.fsf@intel.com>
Date:	Fri, 06 May 2016 18:06:49 +0300
From:	Jani Nikula <jani.nikula@...el.com>
To:	Markus Heiser <markus.heiser@...marit.de>,
	Mauro Carvalho Chehab <mchehab@....samsung.com>,
	Jonathan Corbet <corbet@....net>
Cc:	Daniel Vetter <daniel@...ll.ch>,
	Daniel Vetter <daniel.vetter@...ll.ch>,
	Grant Likely <grant.likely@...retlab.ca>,
	Dan Allen <dan@...ndevise.io>,
	Russel Winder <russel@...der.org.uk>,
	Keith Packard <keithp@...thp.com>,
	LKML <linux-kernel@...r.kernel.org>, linux-doc@...r.kernel.org,
	Hans Verkuil <hverkuil@...all.nl>,
	LMML <linux-media@...r.kernel.org>,
	Graham Whaley <graham.whaley@...ux.intel.com>
Subject: Re: Kernel docs: muddying the waters a bit

On Fri, 06 May 2016, Markus Heiser <markus.heiser@...marit.de> wrote:
> @Jonathan: what do you think? Should I prepare a patch
> with a basic reST (sphinx) build infrastructure, including
>
> * a folder for sphinx docs:
>
>   ./Documentation/sphinx/

I'm already working on a patch series taking a different approach. I
don't think we should hide the documentation under an extra folder named
after a tool. Actually, I'm strongly opposed to that.

Instead, we should place the Sphinx stuff directly under Documentation,
and have Sphinx recursively pick up all the *.rst files. We should
promote gradually switching to lightweight markup and integration of the
documents into one system. This process should be as little disruptive
as possible.

If someone wants to convert a .txt document to .rst and get it processed
by Sphinx, it should be as simple as renaming the file, doing the
necessary edits, and adding it to a toctree. Imagine gradually
converting the files under, say, Documentation/kbuild. Why should the
.rst files be moved under another directory? They should stay alongside
the .txt files under the same directory. There's bound to be a lot of
people who'll never use Sphinx, and will expect to find the good old
plain text files (albeit with some markup) where they always were.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center