PDF documentation fails to build on LINUX.

[cjg]

Hello,

When building the documentation textlive fails with:

/usr/bin/texi2dvi: pdfetex exited with bad status, quitting.

Here is the platform.log file contents:

This is pdfTeX, Version 3.14159265-2.6-1.40.15 (TeX Live 2014) (preloaded format=pdfetex 2014.8.15)  18 AUG 2014 07:09
entering extended mode
 restricted \write18 enabled.
 file:line:error style messages enabled.
 %&-line parsing enabled.
**\nonstopmode \catcode126=12 \def\normaltilde{~}\catcode126=13 \let~\normaltil
de  \input ./platform.texi
(./platform.texi (/opt/texlive/2014/texmf-dist/tex/texinfo/texinfo.tex
Loading texinfo [version 2014-05-20.16]:
\bindingoffset=\dimen16
\normaloffset=\dimen17
\pagewidth=\dimen18
\pageheight=\dimen19
\outerhsize=\dimen20
\outervsize=\dimen21
\cornerlong=\dimen22
\cornerthick=\dimen23
\topandbottommargin=\dimen24
\headlinebox=\box16
\footlinebox=\box17
\margin=\insert252
\EMsimple=\toks13
\groupbox=\box18
\groupinvalidhelp=\toks14
\mil=\dimen25
\exdentamount=\skip18
\inmarginspacing=\skip19
\centerpenalty=\count27
 pdf,
\tempnum=\count28
\lnkcount=\count29
\filename=\toks15
\filenamelength=\count30
\pgn=\count31
\toksA=\toks16
\toksB=\toks17
\toksC=\toks18
\toksD=\toks19
\boxA=\box19
\countA=\count32
\nopdfimagehelp=\toks20
 fonts,
\sffam=\fam8
\textleading=\dimen26
 markup,
\fontdepth=\count33
 glyphs,
\errorbox=\box20

page headings,
\titlepagetopglue=\skip20
\titlepagebottomglue=\skip21
\evenheadline=\toks21
\oddheadline=\toks22
\evenfootline=\toks23
\oddfootline=\toks24
 tables,
\tableindent=\dimen27
\itemindent=\dimen28
\itemmargin=\dimen29
\itemmax=\dimen30
\itemno=\count34
\multitableparskip=\skip22
\multitableparindent=\skip23
\multitablecolspace=\dimen31
\multitablelinespace=\skip24
\colcount=\count35
\everytab=\toks25
 conditionals,
\doignorecount=\count36
 indexing,
\whatsitskip=\skip25
\whatsitpenalty=\count37
\secondaryindent=\skip26
\partialpage=\box21
\doublecolumnhsize=\dimen32
 sectioning,
\unnumberedno=\count38
\chapno=\count39
\secno=\count40
\subsecno=\count41
\subsubsecno=\count42
\appendixno=\count43
\absseclevel=\count44
\secbase=\count45
\chapheadingskip=\skip27
\secheadingskip=\skip28
\subsecheadingskip=\skip29
 toc,
\tocfile=\write0
\contentsrightmargin=\skip30
\savepageno=\count46
\lastnegativepageno=\count47
\tocindent=\dimen33
 environments,
\lispnarrowing=\skip31
\envskipamount=\skip32
\circthick=\dimen34
\cartouter=\dimen35
\cartinner=\dimen36
\normbskip=\skip33
\normpskip=\skip34
\normlskip=\skip35
\lskip=\skip36
\rskip=\skip37
\nonfillparindent=\dimen37
\tabw=\dimen38
\verbbox=\box22

defuns,
\defbodyindent=\skip38
\defargsindent=\skip39
\deflastargmargin=\skip40
\defunpenalty=\count48
\parencount=\count49
\brackcount=\count50
 macros,
\paramno=\count51
\macname=\toks26
 cross references,
\auxfile=\write1
\savesfregister=\count52
\toprefbox=\box23
\printedrefnamebox=\box24
\infofilenamebox=\box25
\printedmanualbox=\box26
 insertions,
\footnoteno=\count53
\SAVEfootins=\box27
\SAVEmargin=\box28

(/opt/texlive/2014/texmf-dist/tex/generic/epsf/epsf.tex
This is `epsf.tex' v2.7.4 <14 February 2011>
\epsffilein=\read1
\epsfframemargin=\dimen39
\epsfframethickness=\dimen40
\epsfrsize=\dimen41
\epsftmp=\dimen42
\epsftsize=\dimen43
\epsfxsize=\dimen44
\epsfysize=\dimen45
\pspoints=\dimen46
)
\noepsfhelp=\toks27
 localization,
\nolanghelp=\toks28
\countUTFx=\count54
\countUTFy=\count55
\countUTFz=\count56
 formatting,
\defaultparindent=\dimen47
 and turning on texinfo input format.) [1{/opt/texlive/2014/texmf-var/fonts/map
/pdftex/updmap/pdftex.map}] ()
\openout0 = `platform.toc'.

 [1] (./platform.toc)
[-1] (./platform.toc) (./platform.toc) Chapter 1
@xrdef{Darwin-title}{(Open)Solaris}
@xrdef{Darwin-snt}{}
Chapter 2 [2
@numchapentry{Unix-like}{1}{}{2}
@numsecentry{Advanced linking configuration}{1.1}{}{2}
@numsecentry{BSD}{1.2}{}{2}
@numsecentry{(Open)Solaris}{1.3}{}{2}
@xrdef{Darwin-pg}{2}
@numsecentry{Darwin (Mac OS X, iPhone)}{1.4}{}{2}
] Chapter 3 [3
@numchapentry{DOS}{2}{}{3}
] Chapter 4 [4
@numchapentry{OS/2}{3}{}{4}
] [5
@numchapentry{Windows}{4}{}{5}
@numsecentry{Native Windows compilation using MinGW or MinGW-w64}{4.1}{}{5}
@numsecentry{Microsoft Visual C++ or Intel C++ Compiler for Windows}{4.2}{}{5}
] [6
@numsubsecentry{Linking to FFmpeg with Microsoft Visual C++}{4.2.1}{}{6}
]
./platform.texi:248: Use of \ doesn't match its definition.
l.248 lib /machine:i386 /def:..\l
                                 ib\foo-version.def  /out:foo.lib
If you say, e.g., `\def\a1{...}', then you must always
put `1' after `\a', since control sequence names are
made up of letters only. The macro here has not been
followed by the required stuff, so I'm ignoring it.

./platform.texi:248: Use of \ doesn't match its definition.
l.248 lib /machine:i386 /def:..\lib\f
                                     oo-version.def  /out:foo.lib
If you say, e.g., `\def\a1{...}', then you must always
put `1' after `\a', since control sequence names are
made up of letters only. The macro here has not been
followed by the required stuff, so I'm ignoring it.

@xrdef{Cross compilation for Windows with Linux-title}{Linking to FFmpeg with M
icrosoft Visual C++}
@xrdef{Cross compilation for Windows with Linux-snt}{}

Overfull \hbox (78.17732pt too wide) in paragraph at lines 296--296
 []@texttt yasm, libSDL-devel, libfaac-devel, libaacplus-devel, libgsm-devel, l
ibmp3lame-devel,[] |

@hbox(6.69167+2.43333)x433.62
.@glue(@leftskip) 28.90755
.@hbox(0.0+0.0)x0.0
.@texttt y
.@texttt a
.@texttt s
.etc.


Overfull \hbox (14.94176pt too wide) in paragraph at lines 297--297
 []@texttt libschroedinger1.0-devel, speex-devel, libtheora-devel, libxvidcore-
devel[] |

@hbox(6.69167+2.43333)x433.62
.@glue(@leftskip) 28.90755
.@hbox(0.0+0.0)x0.0
.@texttt l
.@texttt i
.@texttt b
.etc.

[7
@xrdef{Cross compilation for Windows with Linux-pg}{7}
@numsecentry{Cross compilation for Windows with Linux}{4.3}{}{7}
@numsecentry{Compilation under Cygwin}{4.4}{}{7}
]
Overfull \hbox (72.42863pt too wide) in paragraph at lines 317--317
 []@texttt ./configure --target-os=mingw32 --extra-cflags=-mno-cygwin --extra-l
ibs=-mno-cygwin[] |

@hbox(7.60416+2.43333)x433.62
.@glue(@leftskip) 28.90755
.@hbox(0.0+0.0)x0.0
.@texttt .
.@texttt /
.@texttt c
.etc.


Overfull \hbox (262.13533pt too wide) in paragraph at lines 322--322
 []@texttt ./configure --target-os=mingw32 --enable-shared --disable-static --e
xtra-cflags=-mno-cygwin --extra-libs=-mno-cygwin[] |

@hbox(7.60416+2.43333)x433.62
.@glue(@leftskip) 28.90755
.@hbox(0.0+0.0)x0.0
.@texttt .
.@texttt /
.@texttt c
.etc.

Chapter 5 [8
@numsecentry{Crosscompilation for Windows under Cygwin}{4.5}{}{8}
]
Underfull \hbox (badness 10000) in paragraph at lines 356--365
 @texttt (http://ports2plan9.googlecode.com/files/gcc-apelibs-1207.tbz[])[][][]
 @textrm pack-age

@hbox(7.60416+2.43333)x433.62, glue set 8.08865
.@glue(@leftskip) 21.68121
.@texttt (
.@texttt h
.@texttt t
.@texttt t
.etc.

[9
@numchapentry{Plan 9}{5}{}{9}
] ) 
Here is how much of TeX's memory you used:
 1879 strings out of 494669
 22887 string characters out of 6151786
 66382 words of memory out of 5000000
 3395 multiletter control sequences out of 15000+600000
 32127 words of font info for 112 fonts, out of 8000000 for 9000
 1457 hyphenation exceptions out of 8191
 12i,5n,16p,373b,372s stack positions out of 5000i,500n,10000p,200000b,80000s
</opt/texlive/2014/texmf-dist/fonts/type1/public/amsfonts/cm/cmb10.pfb></opt
/texlive/2014/texmf-dist/fonts/type1/public/amsfonts/cm/cmbx12.pfb></opt/texliv
e/2014/texmf-dist/fonts/type1/public/amsfonts/cm/cmmi12.pfb></opt/texlive/2014/
texmf-dist/fonts/type1/public/amsfonts/cm/cmr10.pfb></opt/texlive/2014/texmf-di
st/fonts/type1/public/amsfonts/cm/cmsy10.pfb></opt/texlive/2014/texmf-dist/font
s/type1/public/amsfonts/cm/cmti10.pfb></opt/texlive/2014/texmf-dist/fonts/type1
/public/amsfonts/cm/cmtt10.pfb>
Output written on platform.pdf (11 pages, 119602 bytes).
PDF statistics:
 135 PDF objects out of 1000 (max. 8388607)
 110 compressed objects within 2 object streams
 12 named destinations out of 1000 (max. 500000)
 21 words of extra memory for PDF output out of 10000 (max. 10000000)

[cjg]

platform log

[Cigaes]

Does it help if you modify doc/platform.texi:

lib /machine:i386 /def:..\lib\foo-version.def  /out:foo.lib

and replace the two backslashes with ‍@backslashchar{}‍?

(I did not know we could generate PDF docs. Not that I find that useful compared to man and HTML... And why does trac suddenly put everything in bold?)

[Carl Eugen Hoyos]

How can I reproduce this?
make succeeds here without producing any pdf files.

[cjg]

Replying to cehoyos:

How can I reproduce this?
make succeeds here without producing any pdf files.

Hello,

This is what is used for generating the pdf and dvi documentation, and these commands are issued after the normal ./configure and make.

pushd doc &&
for DOCNAME in basename -s .html *.html
do

texi2pdf -b $DOCNAME.texi &&
texi2dvi -b $DOCNAME.texi &&
dvips -o $DOCNAME.ps \

$DOCNAME.dvi

done &&
popd &&
unset DOCNAME

I will try the first suggestion and see if that fixes the issue. Thank you for the replies.

Christopher.

[cjg]

Replying to Cigaes:

Does it help if you modify doc/platform.texi:

lib /machine:i386 /def:..\lib\foo-version.def  /out:foo.lib

and replace the two backslashes with ‍@backslashchar{}‍?

(I did not know we could generate PDF docs. Not that I find that useful compared to man and HTML... And why does trac suddenly put everything in bold?)

Hello,

By replacing those two backslashes with ‍@backslashchar{}‍ does indeed fix the issue thanks. The popd directive exits correctly and pdf and dvi documents are produced.

Regards,

Christopher.

[Michael Niedermayer]

It seems this was forgotten ...
Id add ‍backslashchar, but it does not seem to work
Can someone send a patch that makes this change and works ?

[Timothy Gu]

I'll try to reproduce this bug and prepare a patch.

[Timothy Gu]

Patch posted on ffmpeg-devel. Note that personally I really want to mark this "bug" as wontfix, because a) it is a pain to change every single instance of \ to 16 characters, and b) we don't even support building PDF docs.

[Cigaes]

Timothy_Gu: you know the tools better than me: is escaping backslash a requirement for texinfo itself? It works for all the tools we use, only not with texi2dvi.
If backslashes are offocially to be escaped, then we should probably do it, no matter how much a hassle it is.
If not, then people should probably use something more modern to produce PDF, maybe from the HTML output or something, and in that case you have my support for closing as wontfix.

[Timothy Gu]

Replying to Cigaes:

Timothy_Gu: you know the tools better than me: is escaping backslash a requirement for texinfo itself?

In short, yes. See below.

It works for all the tools we use, only not with texi2dvi.

Why? Because Texinfo is originally designed to be translated into, well, TeX (and info but that's out of scope). And that's why Texinfo has so many ugly hacks to work around the buttpain of TeX syntax.

Let's look at the tools we use:

• makeinfo for HTML. makeinfo for HTML is implemented in a way that it directly translates AST of Texinfo to HTML, without converting it to TeX first then to HTML because that would be inefficient. Because of that, we don't need to escape the backslash, which is special only in TeX.
• texi2html. For pretty much the same reason.
• texi2pod. It's even simpler than makeinfo, as it doesn't even use an AST IIRC. So, no TeX in this process either.

However, texi2dvi and makeinfo for PDF/DVI output use TeX as an intermediate format, because LaTeX PDF output is widely recognized as one of the best. And that's why there is an error here.

So in general, yes, officially backslashes are to be escaped, but our current usage is a special one that doesn't require escaped backslashes. So should we escape them if PDF generation, the only case where TeX is used as an intermediate format (and maybe Info but who cares about info?), is not officially supported by FFmpeg? The answer for me is no, simply because it takes too much to support an unsupported scenario.

Replacing all the backslashes are not trivial at all. I kind of worked around this for some instances of \ by using @var and @samp etc. tags, and @verbatim in place of @example (\ does not need to be escaped in those tags). But many instances of backslash must be escaped, ending up in diffs like:

doc/filters.texi

@@ -266 +266 @@
 @code{\} is special and needs to be escaped with another @code{\}, the
 previous string will finally result in:
 @example
--vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
+-vf "drawtext=text=this is a @backslashchar{}@backslashchar{}@backslashchar{}@backslashchar{}@backslashchar{}@backslashchar{}'string@backslashchar{}@backslashchar{}@backslashchar{}@backslashchar{}@backslashchar{}@backslashchar{}'@backslashchar{}@backslashchar{}@backslashchar{}@backslashchar{}: may contain one at backslashchar{}@backslashchar{}, or more@backslashchar{}@backslashchar{}, special characters"
 @end example
 
 @chapter Timeline editing

(​https://lists.ffmpeg.org/pipermail/ffmpeg-devel/2015-March/170629.html)

[Ganesh Ajjanagadde]

As above thread points out, the texinfo manual says that the \backslashchar{} should not be needed for the .texi files in ffmpeg: ​http://www.gnu.org/software/texinfo/manual/texinfo/html_node/Inserting-a-Backslash.html.

This is clearly an acknowledged bug in texinfo that is being actively worked on: ​http://lists.gnu.org/archive/html/bug-texinfo/2015-06/msg00001.html and link therein. It is painful, and shows the cruft of old legacy stuff, subtle incompatibilities, etc.

In short, I am closing this as a wontfix for the following reasons:

1. pdf is not even officially supported by ffmpeg.
2. If you still really want to generate pdf, you can use wkhtmltopdf. I tested on a few html files, and the results are definitely quite good.

3, As detailed above, this is an upstream bug of texinfo. If you want to generate pdf from texi, please file an upstream ticket.

4. Working around upstream bug has little value compared to the work needed in light of the above, and the thread showing a tentative workaround in comment 11.