On Tue, 11 Oct 2016, Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxx> wrote:
> Em Tue, 11 Oct 2016 09:26:48 +0200
> Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu:
>
>> 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.
>
> I can write documentation for parse-headers.pl, either as a --help/--man
> option or at some ReST file (or both). I'll add this to my mental TODO
> list.
Thanks, documentation will help everyone else evaluate whether
parse-headers.pl is only useful for some corner case in media docs, or
perhaps more generally useful. Currently, it's hard to tell.
Anyway, documentation does not change my view on adding such scripts. As
I've said, I think they will make the documentation build more difficult
to maintain. They are likely to become special purpose hacks for corner
cases across documentation.
The rest of what you say is unrelated to the patches at hand.
BR,
Jani.
>
> -
>
> With regards to Sphinx x DocBook, in terms of functionality, Sphinx
> is an improvement, as we can now use the same markup for everything,
> and cross-reference all documents. Unfortunately, it has less
> functionality than DocBook, and requires more magic to work.
>
> However, there are costs to pay on using a Python script like Sphinx.
> I won't mention again the issues with Python itself and its unstable
> API, but, instead, focus on Sphinx script itself.
>
> First of all, installing packages for Sphinx script to work is a lot
> more complex, specially for the PDF output, as the LaTeX requirements are
> very distribution specific, as some distributions package each LaTeX
> extension as optional packages, and the required extensions used by
> the Sphinx script are not documented.
>
> Also, the Sphinx script and its build logic is a lot more fragile than
> the Makefile/xmlto that we use on DocBook, and this has nothing to do
> with adding extra perl/python scripts.
>
> While it is clean for html output, it is very dirty when producing
> a PDF output.
>
> It starts by generating its own Makefile for PDF builds, at the output
> directory, with we have little control on it.
>
> Also, it seems that almost all books will need hacks to produce proper PDF,
> as neither ReST or Sphinx extensions currently have proper support to adjust
> things provided on DocBook, like setting page properties, enabling
> image/table scaling, auto-numbering images/tables/examples or changing page
> orientation in the middle of a document.
>
> The biggest issue I found is related to table outputs in PDF format, as
> it does a very poor job adjusting table margins to fit inside the paper
> margins. Also, the auto-generated TOC index on PDF doesn't match the
> numeration of the HTML output. Currently, I didn't find any solution
> for the latter issue.
>
> As Sphinx markup doesn't have any way to tell how the output would be
> formatted, a lot of magic is required at Sphinx conf.py for PDF
> output to start working. Worse than that, several tables require
> extra tags for PDF output, specifying the column sizes, and forcing
> them to be handled as longtables[1]. Also, if the table is too big,
> the rst files require raw latex macros/code before/after such
> tables, in order for them to fit inside a paper page - either by
> changing their orientation or enabling auto-scale, if the table is
> not a longtable. Currently, no way to tell Sphinx to enable auto-scale
> on big tables.
>
> So, in practice, it means that Sphinx build is a house of cards,
> at least for PDF output, as every new book should be tested if
> it will produce a proper PDF output, and add extra hacks inside
> the rst files to fix them, when the defaults won't work.
>
> I'm almost sure that we end by needing similar hacks for man
> page output.
>
> Thanks,
> Mauro
>
>
> [1]
>
> Sphinx script outputs table in LaTeX format using either
> "tabularx" or "longtable". A "tabularx" table should fit into
> one page, but it can be scaled to fit into a page using the
> "adjustbox" LaTeX extension. A "longtable" can have multiple pages,
> but can't be scaled.
>
> The way the Sphinx script decides either to use tabularx or longtable
> is based *only* on the number of table rows: if bigger than 30, it
> uses "longtable" - even if the table is small enough to fit on a single
> page; if lower than 30, even if the table is very big, it will use
> "tabularx".
>
> There are several cases of tables with less than 30 rows that won't
> fit on a single page, because each row has several lines. Every such
> table requires an extra tag (".. cssclass:: longtable") for it to
> be properly displayed at the PDF output.
>
> However, the reverse is a lot worse: there are have several cases on
> media where we have tables bigger than 30 rows that would fit well on
> a single page, as there's just one line per how. Unfortunately,
> Sphinx doesn't allow forcing a table to be output using "tabularx".
> As "longtable" cannot be scaled using "adjustbox", the ones whose
> lines won't fit into a page requires a magic raw latex spell in
> order to force the LaTeX output to use a smaller font size, as ReST
> doesn't have any markup to specify the text output size.
>
> In practice, a typical "tabularx" table found on media require
> those markups:
>
> .. raw:: latex
>
> \begin{adjustbox}{width=\columnwidth}
>
> .. tabularcolumns:: |p{11.0cm}|p{10.0cm}|
>
> <some table>
>
> .. raw:: latex
>
> \end{adjustbox}
>
> And for some "longtable" (as found at Documentation/media/uapi/v4l/subdev-formats.rst):
>
> .. tabularcolumns:: <column sizes>
>
> .. _v4l2-mbus-pixelcode-rgb:
>
> .. raw:: latex
>
> \begingroup
> \tiny
> \setlength{\tabcolsep}{2pt}
>
> <table>
>
> .. raw:: latex
>
> \endgroup
>
> With is very dirty and ugly, IMHO. This is a lot uglier than any extra
> scripts added to the Sphinx script, either as via a generic kernel-cmd
> script or via some Sphinx script extension.
>
>
--
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
