[FFmpeg-trac] #3867(documentation:new): PDF documentation fails to build on LINUX.

[FFmpeg]

#3867: PDF documentation fails to build on LINUX.
-------------------------------------+-------------------------------------
             Reporter:  cjg          |                    Owner:
                 Type:  enhancement  |                   Status:  new
             Priority:  normal       |                Component:
              Version:  git-master   |  documentation
             Keywords:               |               Resolution:
             Blocking:               |               Blocked By:
Analyzed by developer:  0            |  Reproduced by developer:  0
-------------------------------------+-------------------------------------

Comment (by Timothy_Gu):

 Replying to [comment:10 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:

 {{{
 #!diff
 diff --git a/doc/filters.texi b/doc/filters.texi
 index 8361a0a..ac4c667 100644
 --- a/doc/filters.texi
 +++ b/doc/filters.texi
 @@ -266,7 +266,7 @@ 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 at backslashchar{}@backslashchar{}@backslashchar{}@backslashchar{}@backslashchar{}@backslashchar{}'@backslashchar{}@backslashchar{}@backslashchar{}@backslashchar{}:
 may contain one at backslashchar{}@backslashchar{}, or
 more at backslashchar{}@backslashchar{}, special characters"
  @end example

  @chapter Timeline editing
 }}}

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

--
Ticket URL: <https://trac.ffmpeg.org/ticket/3867#comment:11>
FFmpeg <https://ffmpeg.org>
FFmpeg issue tracker