Re: [PATCH RFC 0/4] Fix PDF build errors

[Markus Heiser <markus.heiser@darmarit.de>]

Am 02.11.2016 um 17:47 schrieb Mauro Carvalho Chehab <mchehab@infradead.org>:

> Em Wed, 2 Nov 2016 17:08:08 +0100
> Markus Heiser <markus.heiser@darmarit.de> escreveu:
> 
>> Am 02.11.2016 um 12:14 schrieb Jani Nikula <jani.nikula@linux.intel.com>:
>> 
>>> On Wed, 02 Nov 2016, Mauro Carvalho Chehab <mchehab@osg.samsung.com> wrote:  
>>>> This series address a series of errors during PDF generation from
>>>> media documentation.
>>>> 
>>>> Please notice that patch 2 carries on a PDF conversion from a PNG
>>>> image, because Sphinx is not smart enough to do the convertion.
>>>> 
>>>> This is a temporary solution (That's why I'm marking this series
>>>> as RFC).  
>>> 
>>> This seems to work on top of docs-next.
>>> 
>>> ...but it'll break again if we include the missing admin-guide in the
>>> build. :(
>>> Sadly, this breaks the pdf build with:
>>> 
>>> ! TeX capacity exceeded, sorry [main memory size=5000000].
>>> \FV@Space ...ionary {\copy \sphinxvisiblespacebox
>>> }{\sphinxafterbreak } {\ke...
>>> l.3711 ...\PYG{n}{be} \PYG{n}{used} \PYG{n+nb}{to}
>>> or 2  
>> 
>> 
>> This is the verbatim block of the kernel parameters with more
>> than 4300 lines in.
>> 
>> IMO, Verbatim exceeded, because in sphinx.sty is a redefinition
>> of the LaTeX Verbatim command which might be sloppy / see 
>> sphinx.sty::
>> 
>> \renewcommand{\Verbatim}[1][1]{%
>>   ....
> 
> Argh! I really hate those ugly hacks that Sphinx do for LaTeX output...
> 
> Btw, I remember I had to touch on a TeXLive style in order to workaround
> the memory size when testing LaTeX output for some book, but it ended by
> causing some other issues.
> 
>> 
>> The renew-Verbatim has been removed later:
>> 
>> https://github.com/sphinx-doc/sphinx/commit/f9880bfcc8b19a7d197badeb6ab412abfca19891
>> 
>> I my POC I use such a modified sphinx.sty
>> 
>> https://github.com/return42/sphkerneldoc/blob/master/_tex/sphinx.sty
>> 
>> with it, the PDF is build:
>> 
>> https://h2626237.stratoserver.net/kernel/books/admin-guide/pdf/linux-user.pdf
>> 
>> Using modified sphinx.sty has the drawback, that it is not
>> up- or downward compatible to the installed Sphinx version.
>> 
>> So in short, I think it is the best to come back to the reasons
>> and just split kernel parameters in several blocks and using the 
>> 'none' option to prevent rendering as C .. E.g:
>> 
>> .. code-block:: none
> 
> I'm staring to think that we should just redefine the default for ::
> to be "none", and use the "C" handling **only** when explicitly
> requested.
> 
> I remember that Jon did such suggestion sometime ago.

*shrug* ... I think about kernel-doc comments in the sources,
mostly you will have small examples and won't those verbose 
".. code-block::" markup / using "::" keeps the comment compact.

> 
> If we change it to "none", it will still spend lots of memory for
> verbatim?

Yes .. we need to split kernel parameter's into smaller verbatime
blocks.