Re: [PATCH RFC 0/4] Fix PDF build errors
On Wed, 02 Nov 2016, Markus Heiser wrote: > Am 02.11.2016 um 17:47 schrieb Mauro Carvalho Chehab : >> 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. I sent the patch [1] to default to "none". It's never wrong, not even for code. But getting the highlighting wrong, OTOH, is pretty bad. We have that. And really, if you look at the kernel-doc comments and the rst documentation, we don't have all that many literal blocks that would benefit from syntax highlighting in the first place. BR, Jani. [1] http://lkml.kernel.org/r/1478164053-4562-1-git-send-email-jani.nik...@intel.com -- Jani Nikula, Intel Open Source Technology Center
Re: [PATCH RFC 0/4] Fix PDF build errors
On Wed, Nov 02, 2016 at 03:27:50PM +0200, Jani Nikula wrote: On Wed, 02 Nov 2016, Mauro Carvalho Chehab wrote: Em Wed, 02 Nov 2016 13:14:47 +0200 Jani Nikula escreveu: On Wed, 02 Nov 2016, Mauro Carvalho Chehab 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. Yes. ...but it'll break again if we include the missing admin-guide in the build. :( LaTeX/PDF output is ugly... for each new stuff, we need to re-validate its output :-( Once we have this working, I think the only way to keep it working is to have continuous testing of the pdf build. That won't keep the output pretty, but it'll help ensure passing build. Perhaps 0day could eventually start running 'make DOCBOOKS="" pdfdocs' after the htmldocs target? Cc: Fengguang and kbuild-all. OK. We'll add the 'pdfdocs' test right after 'htmldocs'. Thank you for the tip. Regards, Fengguang
Re: [PATCH RFC 0/4] Fix PDF build errors
Am 02.11.2016 um 17:47 schrieb Mauro Carvalho Chehab : > Em Wed, 2 Nov 2016 17:08:08 +0100 > Markus Heiser escreveu: > >> Am 02.11.2016 um 12:14 schrieb Jani Nikula : >> >>> On Wed, 02 Nov 2016, Mauro Carvalho Chehab 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=500]. >>> \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.
Re: [PATCH RFC 0/4] Fix PDF build errors
Em Wed, 2 Nov 2016 17:08:08 +0100 Markus Heiser escreveu: > Am 02.11.2016 um 12:14 schrieb Jani Nikula : > > > On Wed, 02 Nov 2016, Mauro Carvalho Chehab 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=500]. > > \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. If we change it to "none", it will still spend lots of memory for verbatim? Cheers, Mauro
Re: [PATCH RFC 0/4] Fix PDF build errors
Em Wed, 02 Nov 2016 15:27:50 +0200 Jani Nikula escreveu: > On Wed, 02 Nov 2016, Mauro Carvalho Chehab wrote: > > Em Wed, 02 Nov 2016 13:14:47 +0200 > > Jani Nikula escreveu: > > > >> On Wed, 02 Nov 2016, Mauro Carvalho Chehab > >> 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. > > > > Yes. > > > >> ...but it'll break again if we include the missing admin-guide in the > >> build. :( > > > > LaTeX/PDF output is ugly... for each new stuff, we need to re-validate its > > output :-( > > Once we have this working, I think the only way to keep it working is to > have continuous testing of the pdf build. That won't keep the output > pretty, but it'll help ensure passing build. Yes. > Perhaps 0day could eventually start running 'make DOCBOOKS="" pdfdocs' > after the htmldocs target? Cc: Fengguang and kbuild-all. Good idea! it will be really helpful if Fengguang could automate the testing process once we fix it. Regards, Mauro
Re: [PATCH RFC 0/4] Fix PDF build errors
Am 02.11.2016 um 12:14 schrieb Jani Nikula : > On Wed, 02 Nov 2016, Mauro Carvalho Chehab 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=500]. > \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]{% 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 acpi= [HW,ACPI,X86,ARM64] Advanced Configuration and Power Interface Format: { force | on | off | strict | noirq | rsdt | copy_dsdt } -- Markus --
Re: [PATCH RFC 0/4] Fix PDF build errors
On Wed, 02 Nov 2016, Mauro Carvalho Chehab wrote: > Em Wed, 02 Nov 2016 13:14:47 +0200 > Jani Nikula escreveu: > >> On Wed, 02 Nov 2016, Mauro Carvalho Chehab 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. > > Yes. > >> ...but it'll break again if we include the missing admin-guide in the >> build. :( > > LaTeX/PDF output is ugly... for each new stuff, we need to re-validate its > output :-( Once we have this working, I think the only way to keep it working is to have continuous testing of the pdf build. That won't keep the output pretty, but it'll help ensure passing build. Perhaps 0day could eventually start running 'make DOCBOOKS="" pdfdocs' after the htmldocs target? Cc: Fengguang and kbuild-all. BR, Jani. > > > >> >> BR, >> Jani. >> >> >> From c296287c65f4b6ad6272171456dcf8508c92ae2f Mon Sep 17 00:00:00 2001 >> From: Jani Nikula >> Date: Wed, 2 Nov 2016 13:05:59 +0200 >> Subject: [PATCH] Documentation/sphinx: include admin-guide in the latex/pdf >> build >> Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo >> Cc: Jani Nikula >> >> Fix the warning: >> >> WARNING: "latex_documents" config value references unknown document >> user/index >> >> Signed-off-by: Jani Nikula >> >> --- >> >> Sadly, this breaks the pdf build with: >> >> ! TeX capacity exceeded, sorry [main memory size=500]. >> \FV@Space ...ionary {\copy \sphinxvisiblespacebox >> }{\sphinxafterbreak } {\ke... >> l.3711 ...\PYG{n}{be} \PYG{n}{used} \PYG{n+nb}{to} >> >> Output written on linux-user.pdf (15 pages). >> Transcript written on linux-user.log. >> Makefile:66: recipe for target 'linux-user.pdf' failed >> make[2]: *** [linux-user.pdf] Error 1 >> Documentation/Makefile.sphinx:83: recipe for target 'pdfdocs' failed >> make[1]: *** [pdfdocs] Error 2 >> Makefile:1442: recipe for target 'pdfdocs' failed >> make: *** [pdfdocs] Error 2 >> --- >> Documentation/conf.py | 2 +- >> 1 file changed, 1 insertion(+), 1 deletion(-) >> >> diff --git a/Documentation/conf.py b/Documentation/conf.py >> index 814c336e5f5e..0c758a4f61f1 100644 >> --- a/Documentation/conf.py >> +++ b/Documentation/conf.py >> @@ -340,7 +340,7 @@ if minor > 3: >> # (source start file, target name, title, >> # author, documentclass [howto, manual, or own class]). >> latex_documents = [ >> -('user/index', 'linux-user.tex', 'Linux Kernel User Documentation', >> +('admin-guide/index', 'linux-user.tex', 'Linux Kernel User >> Documentation', > > Oh! It seems I forgot to rename the guide name here :( > > Your patch looks OK! > > Reviewed-by: Mauro Carvalho Chehab > >> 'The kernel development community', 'manual'), >> ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel >> Documentation', >> 'The kernel development community', 'manual'), > > > > > Cheers, > Mauro -- Jani Nikula, Intel Open Source Technology Center
Re: [PATCH RFC 0/4] Fix PDF build errors
Em Wed, 02 Nov 2016 13:14:47 +0200 Jani Nikula escreveu: > On Wed, 02 Nov 2016, Mauro Carvalho Chehab 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. Yes. > ...but it'll break again if we include the missing admin-guide in the > build. :( LaTeX/PDF output is ugly... for each new stuff, we need to re-validate its output :-( > > BR, > Jani. > > > From c296287c65f4b6ad6272171456dcf8508c92ae2f Mon Sep 17 00:00:00 2001 > From: Jani Nikula > Date: Wed, 2 Nov 2016 13:05:59 +0200 > Subject: [PATCH] Documentation/sphinx: include admin-guide in the latex/pdf > build > Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo > Cc: Jani Nikula > > Fix the warning: > > WARNING: "latex_documents" config value references unknown document > user/index > > Signed-off-by: Jani Nikula > > --- > > Sadly, this breaks the pdf build with: > > ! TeX capacity exceeded, sorry [main memory size=500]. > \FV@Space ...ionary {\copy \sphinxvisiblespacebox > }{\sphinxafterbreak } {\ke... > l.3711 ...\PYG{n}{be} \PYG{n}{used} \PYG{n+nb}{to} > > Output written on linux-user.pdf (15 pages). > Transcript written on linux-user.log. > Makefile:66: recipe for target 'linux-user.pdf' failed > make[2]: *** [linux-user.pdf] Error 1 > Documentation/Makefile.sphinx:83: recipe for target 'pdfdocs' failed > make[1]: *** [pdfdocs] Error 2 > Makefile:1442: recipe for target 'pdfdocs' failed > make: *** [pdfdocs] Error 2 > --- > Documentation/conf.py | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > > diff --git a/Documentation/conf.py b/Documentation/conf.py > index 814c336e5f5e..0c758a4f61f1 100644 > --- a/Documentation/conf.py > +++ b/Documentation/conf.py > @@ -340,7 +340,7 @@ if minor > 3: > # (source start file, target name, title, > # author, documentclass [howto, manual, or own class]). > latex_documents = [ > -('user/index', 'linux-user.tex', 'Linux Kernel User Documentation', > +('admin-guide/index', 'linux-user.tex', 'Linux Kernel User > Documentation', Oh! It seems I forgot to rename the guide name here :( Your patch looks OK! Reviewed-by: Mauro Carvalho Chehab > 'The kernel development community', 'manual'), > ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel > Documentation', > 'The kernel development community', 'manual'), Cheers, Mauro
Re: [PATCH RFC 0/4] Fix PDF build errors
On Wed, 02 Nov 2016, Mauro Carvalho Chehab 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. :( BR, Jani. >From c296287c65f4b6ad6272171456dcf8508c92ae2f Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Wed, 2 Nov 2016 13:05:59 +0200 Subject: [PATCH] Documentation/sphinx: include admin-guide in the latex/pdf build Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo Cc: Jani Nikula Fix the warning: WARNING: "latex_documents" config value references unknown document user/index Signed-off-by: Jani Nikula --- Sadly, this breaks the pdf build with: ! TeX capacity exceeded, sorry [main memory size=500]. \FV@Space ...ionary {\copy \sphinxvisiblespacebox }{\sphinxafterbreak } {\ke... l.3711 ...\PYG{n}{be} \PYG{n}{used} \PYG{n+nb}{to} Output written on linux-user.pdf (15 pages). Transcript written on linux-user.log. Makefile:66: recipe for target 'linux-user.pdf' failed make[2]: *** [linux-user.pdf] Error 1 Documentation/Makefile.sphinx:83: recipe for target 'pdfdocs' failed make[1]: *** [pdfdocs] Error 2 Makefile:1442: recipe for target 'pdfdocs' failed make: *** [pdfdocs] Error 2 --- Documentation/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 814c336e5f5e..0c758a4f61f1 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -340,7 +340,7 @@ if minor > 3: # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ -('user/index', 'linux-user.tex', 'Linux Kernel User Documentation', +('admin-guide/index', 'linux-user.tex', 'Linux Kernel User Documentation', 'The kernel development community', 'manual'), ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation', 'The kernel development community', 'manual'), -- 2.1.4 -- Jani Nikula, Intel Open Source Technology Center
Re: [PATCH RFC 0/4] Fix PDF build errors
Em Tue, 1 Nov 2016 16:44:09 -0600 Mauro Carvalho Chehab escreveu: > 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). > > I'm working on a more permanent access where the image format In time: "more permanent solution" > required by Sphinx for PDF output will be met. > > Mauro Carvalho Chehab (4): > docs-rst: fix PDF build errors > [media] subdev-formats.rst: we need a pdf picture for bayer > [media] subdev-formats.rst: don't use adjustbox on a longtable > [media] subdev-formats.rst: add missing columns to tabularcolumns > > Documentation/conf.py | 4 > Documentation/media/index.rst | 5 - > Documentation/media/uapi/v4l/subdev-formats.rst| 17 > +++-- > .../media/uapi/v4l/subdev-formats_files/bayer.pdf | Bin 0 -> 11131 bytes > 4 files changed, 15 insertions(+), 11 deletions(-) > create mode 100644 > Documentation/media/uapi/v4l/subdev-formats_files/bayer.pdf > Cheers, Mauro
[PATCH RFC 0/4] Fix PDF build errors
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). I'm working on a more permanent access where the image format required by Sphinx for PDF output will be met. Mauro Carvalho Chehab (4): docs-rst: fix PDF build errors [media] subdev-formats.rst: we need a pdf picture for bayer [media] subdev-formats.rst: don't use adjustbox on a longtable [media] subdev-formats.rst: add missing columns to tabularcolumns Documentation/conf.py | 4 Documentation/media/index.rst | 5 - Documentation/media/uapi/v4l/subdev-formats.rst| 17 +++-- .../media/uapi/v4l/subdev-formats_files/bayer.pdf | Bin 0 -> 11131 bytes 4 files changed, 15 insertions(+), 11 deletions(-) create mode 100644 Documentation/media/uapi/v4l/subdev-formats_files/bayer.pdf -- 2.7.4