Am 07.10.2016 um 07:56 schrieb Jani Nikula <jani.nik...@intel.com>:
> On Thu, 06 Oct 2016, Mauro Carvalho Chehab <mche...@infradead.org> wrote:
>> Em Thu, 06 Oct 2016 17:21:36 +0300
>> Jani Nikula <jani.nik...@intel.com> escreveu:
>>> We've seen what happens when we make it easy to add random scripts to
>>> build documentation. We've worked hard to get rid of that. In my books,
>>> one of the bigger points in favor of Sphinx over AsciiDoc(tor) was
>>> getting rid of all the hacks required in the build. Things that broke in
>>> subtle ways.
>> I really can't see what scripts it get rids.
> Really? You don't see why the DocBook build was so fragile and difficult
> to maintain? That scares me a bit, because then you will not have
> learned why we should at all costs avoid adding random scripts to
> produce documentation.
For me, disassembling the DocBok build was hard and bothersome, I don't
want this back.
IMO: old hats are productive with perl and they won't adapt another
interpreter language (like python) for scripting.
This series -- the kernel-cmd -- directive avoid that they build
fragile and difficult to maintain Makefile constructs, calling their
Am 06.10.2016 um 16:21 schrieb Jani Nikula <jani.nik...@intel.com>:
> This is connected to the above: keeping documentation buildable with
> sphinx-build directly will force you to avoid the Makefile hacks.
Thats why I think, that the kernel-cmd directive is a more *straight-
forward* solution, helps to **avoid** complexity while not everyone
has to script in python ...
> Case in point, parse-headers.pl was added for a specific need of media
> documentation, and for the life of me I can't figure out by reading the
> script what good, if any, it would be for gpu documentation. I call
> *that* unmaintainable.
If one adds a script like parse-headers.pl to the Documentation/sphinx
folder, he/she also has to add a documentation to the kernel-documentation.rst
If the kernel-cmd directive gets acked, I will add a description to
kernel-documentation.rst and I request Mauro to document the parse-headers.pl
But, let's hear what Jon says.
-- Markus --
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html