Re: [PATCH 0/4] reST-directive kernel-cmd / include contentent from scripts

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Am 07.10.2016 um 07:56 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>:

> On Thu, 06 Oct 2016, Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxx> wrote:
>> Em Thu, 06 Oct 2016 17:21:36 +0300
>> Jani Nikula <jani.nikula@xxxxxxxxx> 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
perl scripts.

Am 06.10.2016 um 16:21 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>:

> 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
also.

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 majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux