linux-kernel - Re: [PATCH] doc: flat-table directive

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: <CAF7F887-75FE-4B98-8042-71A11B53F8EB@darmarit.de>
Date:	Fri, 1 Jul 2016 16:45:57 +0200
From:	Markus Heiser <markus.heiser@...marit.de>
To:	Jonathan Corbet <corbet@....net>
Cc:	Jani Nikula <jani.nikula@...el.com>,
	Mauro Carvalho Chehab <mchehab@....samsung.com>,
	linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
	hverkuil@...all.nl, daniel.vetter@...ll.ch, airlied@...il.com,
	grant.likely@...retlab.ca, rdunlap@...radead.org, keithp@...thp.com
Subject: Re: [PATCH] doc: flat-table directive

Am 01.07.2016 um 14:58 schrieb Jonathan Corbet <corbet@....net>:

> On Fri, 01 Jul 2016 13:44:17 +0300
> Jani Nikula <jani.nikula@...el.com> wrote:
> 
>> This is also one of the reasons why I so much want to keep everything
>> behind one configuration file, and build everything in the Sphinx
>> toolchain. To keep it all more uniform, to not duplicate stuff, and not
>> deviate to some silos like we've done in the past. I think when we have
>> things working, we can add dedicated config files for the select few
>> things that have additional special needs. Media is probably one of
>> them. But that said, I think we should be able to keep including that to
>> the main documentation build too.
> 
> So this is mostly how I see things too.  But it might still be worth
> thinking about whether media, in particular, is special and should be
> buildable as a standalone document.  I can see there may be settings
> where only that is wanted.
> 

I dare hardly say it, but I come back to the sphinx-sub-project
solution ... don't hurt me ... listen, it is conceptual a bit 
different to what I have done first, but hopefully it is a solution
we can all live with:

* media is "special", so let's build it separate.

We have this Documentation/index.rst file, where we can place
all "books" in, except those which are specifically.

.. toctree::
   :maxdepth: 2

   kernel-documentation
   gpu
   ...

Folders matching Documentation/*/conf.py are build separate,
media is the one. This is exactly what my sphinx-sub-project
solution does, building books from folders with a conf.py in.
This conf.py inherits all settings from the top config in
Documentation/conf.py and overwrites only those configurations
which are different.

... could this be a solution?

... I'm a bit afraid to press the send button ... ;-)

> Some sort of "only build xxx.rst and see what explodes" makefile option
> also seems like a useful thing to have, just as a time saver for
> developers and maintainers.
> 
> jon

IMHO it is a conceptual problem:

If we assemble "books" into one project, the context of each
node in the doctree is the union. E.g. cross references from
one "book" to another will only work if the context is the union. 

No matter how we do it, but if we are building parts, the context
is reduced to this part and this will always be different to build
the union, so it could never be a entire *lint*.

-- Markus --