Opened 5 years ago

Closed 4 years ago

# PDF documentation fails to build on LINUX.

Reported by: Owned by: cjg normal documentation git-master michael, timothygu99@gmail.com, gajjanagadde@gmail.com no no

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
\bindingoffset=\dimen16
\normaloffset=\dimen17
\pagewidth=\dimen18
\pageheight=\dimen19
\outerhsize=\dimen20
\outervsize=\dimen21
\cornerlong=\dimen22
\cornerthick=\dimen23
\topandbottommargin=\dimen24
\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
markup,
\fontdepth=\count33
glyphs,
\errorbox=\box20

\titlepagetopglue=\skip20
\titlepagebottomglue=\skip21
\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
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>
\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{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
@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)


platform log

### comment:1 follow-up: ↓ 5 Changed 5 years ago by 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?)

### comment:2 Changed 5 years ago by Cigaes

• Description modified (diff)

### comment:3 follow-up: ↓ 4 Changed 5 years ago by cehoyos

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

### comment:4 in reply to: ↑ 3 Changed 5 years ago by cjg

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:

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.

Version 0, edited 5 years ago by cjg (next)

### comment:5 in reply to: ↑ 1 Changed 5 years ago by cjg

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.

### comment:6 Changed 4 years ago by michael

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 ?

### comment:7 Changed 4 years ago by michael

• Cc michael added

### comment:8 Changed 4 years ago by Timothy_Gu

• Cc timothygu99@gmail.com added
• Type changed from defect to enhancement
• Version changed from 2.3 to git-master

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

### comment:9 Changed 4 years ago by 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.

### comment:10 follow-up: ↓ 11 Changed 4 years ago by 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.

### comment:11 in reply to: ↑ 10 Changed 4 years ago by Timothy_Gu

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

diff --git a/doc/filters.texi b/doc/filters.texi
index 8361a0a..ac4c667 100644
 a escaping rules of the adopted shell. For example, assuming that @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

### comment:12 Changed 4 years ago by gajjanag

• Resolution set to wontfix
• Status changed from new to closed

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.

1. 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.
Note: See TracTickets for help on using tickets.