[FFmpeg-devel] [PATCH 5/5] doc: Escape all backslashes needed to be escaped

Timothy Gu timothygu99 at gmail.com
Mon Mar 23 04:47:20 CET 2015

No, I do not want to do this, but a user requested it…

I think it is time for us to switch to a better documentation format.

Fixes #3867.
 doc/developer.texi |  4 ++--
 doc/encoders.texi  |  4 ++--
 doc/faq.texi       |  8 ++++----
 doc/ffmpeg.texi    |  4 ++--
 doc/filters.texi   | 60 +++++++++++++++++++++++++++---------------------------
 doc/indevs.texi    |  2 +-
 doc/metadata.texi  |  6 +++---
 doc/muxers.texi    | 38 +++++++++++++++++-----------------
 doc/protocols.texi |  2 +-
 doc/utils.texi     |  8 ++++----
 10 files changed, 68 insertions(+), 68 deletions(-)

diff --git a/doc/developer.texi b/doc/developer.texi
index d9ccf7b..fe8b0bf 100644
--- a/doc/developer.texi
+++ b/doc/developer.texi
@@ -222,9 +222,9 @@ set cinoptions=(0
 autocmd FileType make,automake set noexpandtab shiftwidth=8 softtabstop=8
 " Trailing whitespace and tabs are forbidden, so highlight them.
 highlight ForbiddenWhitespace ctermbg=red guibg=red
-match ForbiddenWhitespace /\s\+$\|\t/
+match ForbiddenWhitespace /@backslashchar{}s at backslashchar{}+$@backslashchar{}|@backslashchar{}t/
 " Do not highlight spaces at the end of line while typing on that line.
-autocmd InsertEnter * match ForbiddenWhitespace /\t\|\s\+\%#\@@<!$/
+autocmd InsertEnter * match ForbiddenWhitespace /@backslashchar{}t at backslashchar{}|@backslashchar{}s at backslashchar{}+ at backslashchar{}%#@backslashchar{}@@<!$/
 @end example
 For Emacs, add these roughly equivalent lines to your @file{.emacs.d/init.el}:
diff --git a/doc/encoders.texi b/doc/encoders.texi
index a6cdd99..095384a 100644
--- a/doc/encoders.texi
+++ b/doc/encoders.texi
@@ -1877,8 +1877,8 @@ duplicated for compatibility with the Libav fork.
 For example to specify libx264 encoding options with @command{ffmpeg}:
-ffmpeg -i INPUT -c:v libx264 -x264-params level=30:bframes=0:weightp=0:\
+ffmpeg -i INPUT -c:v libx264 -x264-params level=30:bframes=0:weightp=0:@backslashchar{}
 no-fast-pskip=1:subq=6:8x8dct=0:trellis=0 OUTPUT
 @end example
 @end table
diff --git a/doc/faq.texi b/doc/faq.texi
index 5fe716b..793fc46 100644
--- a/doc/faq.texi
+++ b/doc/faq.texi
@@ -278,7 +278,7 @@ then you may use any file that DirectShow can read as input.
 Just create an "input.avs" text file with this single line ...
-DirectShowSource("C:\path to your file\yourfile.asf")
+DirectShowSource("C:@backslashchar{}path to your file at backslashchar{}yourfile.asf")
 @end example
 ... and then feed that text file to ffmpeg:
@@ -384,7 +384,7 @@ mkfifo intermediate1.mpg
 mkfifo intermediate2.mpg
 ffmpeg -i input1.avi -qscale:v 1 -y intermediate1.mpg < /dev/null &
 ffmpeg -i input2.avi -qscale:v 1 -y intermediate2.mpg < /dev/null &
-cat intermediate1.mpg intermediate2.mpg |\
+cat intermediate1.mpg intermediate2.mpg |@backslashchar{}
 ffmpeg -f mpeg -i - -c:v mpeg4 -acodec libmp3lame output.avi
 @end example
@@ -413,8 +413,8 @@ ffmpeg -i input1.flv -an -f yuv4mpegpipe - > temp1.v < /dev/null &
 @{ ffmpeg -i input2.flv -an -f yuv4mpegpipe - < /dev/null | tail -n +2 > temp2.v ; @} &
 cat temp1.a temp2.a > all.a &
 cat temp1.v temp2.v > all.v &
-ffmpeg -f u16le -acodec pcm_s16le -ac 2 -ar 44100 -i all.a \
-       -f yuv4mpegpipe -i all.v \
+ffmpeg -f u16le -acodec pcm_s16le -ac 2 -ar 44100 -i all.a @backslashchar{}
+       -f yuv4mpegpipe -i all.v @backslashchar{}
        -y output.flv
 rm temp[12].[av] all.[av]
 @end example
diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi
index 5a979d5..750b894 100644
--- a/doc/ffmpeg.texi
+++ b/doc/ffmpeg.texi
@@ -1214,8 +1214,8 @@ proper support for subtitles.
 For example, to hardcode subtitles on top of a DVB-T recording stored in
 MPEG-TS format, delaying the subtitles by 1 second:
-ffmpeg -i input.ts -filter_complex \
-  '[#0x2ef] setpts=PTS+1/TB [sub] ; [#0x2d0] [sub] overlay' \
+ffmpeg -i input.ts -filter_complex @backslashchar{}
+  '[#0x2ef] setpts=PTS+1/TB [sub] ; [#0x2d0] [sub] overlay' @backslashchar{}
   -sn -map '#0x2dc' output.mkv
 @end example
 (0x2d0, 0x2dc and 0x2ef are the MPEG-TS PIDs of respectively the video,
diff --git a/doc/filters.texi b/doc/filters.texi
index 8361a0a..ac4c667 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -73,9 +73,9 @@ of the filtergraph.
 For example the sequence of commands:
-echo @var{GRAPH_DESCRIPTION} | \
-tools/graph2dot -o graph.tmp && \
-dot -Tpng graph.tmp -o graph.png && \
+echo @var{GRAPH_DESCRIPTION} | @backslashchar{}
+tools/graph2dot -o graph.tmp && @backslashchar{}
+dot -Tpng graph.tmp -o graph.png && @backslashchar{}
 display graph.png
 @end example
@@ -248,14 +248,14 @@ this is a 'string': may contain one, or more, special characters
 This string contains the @code{'} special escaping character, and the
 @code{:} special character, so it needs to be escaped in this way:
-text=this is a \'string\'\: may contain one, or more, special characters
+text=this is a @backslashchar{}'string at backslashchar{}'@backslashchar{}: may contain one, or more, special characters
 @end example
 A second level of escaping is required when embedding the filter
 description in a filtergraph description, in order to escape all the
 filtergraph special characters. Thus the example above becomes:
-drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters
+drawtext=text=this is a @backslashchar{}@backslashchar{}@backslashchar{}'string at backslashchar{}@backslashchar{}@backslashchar{}'@backslashchar{}@backslashchar{}: may contain one at backslashchar{}, or more at backslashchar{}, special characters
 @end example
 (note that in addition to the @code{\'} escaping special characters,
 also @code{,} needs to be escaped).
@@ -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:
--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
@@ -2891,7 +2891,7 @@ boxblur=2:1:cr=0:ar=0
 Set the luma and chroma radii to a fraction of the video dimension:
+boxblur=luma_radius=min(h at backslashchar{},w)/10:luma_power=1:chroma_radius=min(cw at backslashchar{},ch)/10:chroma_power=1
 @end example
 @end itemize
@@ -4234,7 +4234,7 @@ yellow with a red box around it. Both the text and the box have an
 opacity of 20%.
-drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
+drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':@backslashchar{}
           x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
 @end example
@@ -4271,19 +4271,19 @@ drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_gly
 Show text for 1 second every 3 seconds:
+drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t at backslashchar{},3)@backslashchar{},1):text='blink'"
 @end example
 Use fontconfig to set the font. Note that the colons need to be escaped.
-drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
+drawtext='fontfile=Linux Libertine O-40 at backslashchar{}:style=Semibold:text=FFmpeg'
 @end example
 Print the date of a real-time encoding (see strftime(3)):
-drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}'
+drawtext='fontfile=FreeSans.ttf:text=%@{localtime at backslashchar{}:%a %b %d %Y@}'
 @end example
@@ -4294,7 +4294,7 @@ DS=1.0 # display start
 DE=10.0 # display end
 FID=1.5 # fade in duration
 FOD=5 # fade out duration
-ffplay -f lavfi "color,drawtext=text=TEST:fontsize=50:fontfile=FreeSerif.ttf:fontcolor_expr=ff0000%@{eif\\\\: clip(255*(1*between(t\\, $DS + $FID\\, $DE - $FOD) + ((t - $DS)/$FID)*between(t\\, $DS\\, $DS + $FID) + (-(t - $DE)/$FOD)*between(t\\, $DE - $FOD\\, $DE) )\\, 0\\, 255) \\\\: x\\\\: 2 @}"
+ffplay -f lavfi "color,drawtext=text=TEST:fontsize=50:fontfile=FreeSerif.ttf:fontcolor_expr=ff0000%@{eif at backslashchar{}@backslashchar{}@backslashchar{}@backslashchar{}: clip(255*(1*between(t at backslashchar{}@backslashchar{}, $DS + $FID at backslashchar{}@backslashchar{}, $DE - $FOD) + ((t - $DS)/$FID)*between(t at backslashchar{}@backslashchar{}, $DS at backslashchar{}@backslashchar{}, $DS + $FID) + (-(t - $DE)/$FOD)*between(t at backslashchar{}@backslashchar{}, $DE - $FOD at backslashchar{}@backslashchar{}, $DE) )@backslashchar{}@backslashchar{}, 0 at backslashchar{}@backslashchar{}, 255) @backslashchar{}@backslashchar{}@backslashchar{}@backslashchar{}: x at backslashchar{}@backslashchar{}@backslashchar{}@backslashchar{}: 2 @}"
 @end example
 @end itemize
@@ -5402,7 +5402,7 @@ automatically clipped to the closer edge.
 Flip the image horizontally:
+geq=p(W-X at backslashchar{},Y)
 @end example
@@ -5415,7 +5415,7 @@ geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
 Generate a fancy enigmatic moving light:
+nullsrc=s=256x256,geq=random(1)/hypot(X-cos(N*0.07)*W/2-W/2 at backslashchar{},Y-sin(N*0.09)*H/2-H/2)^2*1000000*sin(N*0.02):128:128
 @end example
@@ -5846,23 +5846,23 @@ hue="H=2*PI*t: s=sin(2*PI*t)+1"
 Apply a 3 seconds saturation fade-in effect starting at 0:
+hue="s=min(t/3 at backslashchar{},1)"
 @end example
 The general fade-in expression can be written as:
-hue="s=min(0\, max((t-START)/DURATION\, 1))"
+hue="s=min(0 at backslashchar{}, max((t-START)/DURATION at backslashchar{}, 1))"
 @end example
 Apply a 3 seconds saturation fade-out effect starting at 5 seconds:
-hue="s=max(0\, min(1\, (8-t)/3))"
+hue="s=max(0 at backslashchar{}, min(1 at backslashchar{}, (8-t)/3))"
 @end example
 The general fade-out expression can be written as:
-hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
+hue="s=max(0 at backslashchar{}, min(1 at backslashchar{}, (START+DURATION-t)/DURATION))"
 @end example
 @end itemize
@@ -6244,7 +6244,7 @@ The computed value in @var{val}, clipped to the
 The computed gamma correction value of the pixel component value,
 clipped to the @var{minval}- at var{maxval} range. It corresponds to the
-"pow((clipval-minval)/(maxval-minval)\, at var{gamma})*(maxval-minval)+minval"
+"pow((clipval-minval)/(maxval-minval)@backslashchar{}, at var{gamma})*(maxval-minval)+minval"
 @end table
@@ -7008,7 +7008,7 @@ Pad the input to get a squared output with size equal to the maximum
 value between the input width and height, and put the input video at
 the center of the padded area:
+pad="max(iw at backslashchar{},ih):ow:(ow-iw)/2:(oh-ih)/2"
 @end example
@@ -8137,7 +8137,7 @@ scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
 Increase the width to a maximum of 500 pixels,
 keeping the same aspect ratio as the input:
-scale=w='min(500\, iw*3/2):h=-1'
+scale=w='min(500 at backslashchar{}, iw*3/2):h=-1'
 @end example
 @end itemize
@@ -10732,9 +10732,9 @@ at output; be sure to configure the output file to handle it.
 Concatenate an opening, an episode and an ending, all in bilingual version
 (video in stream 0, audio in streams 1 and 2):
-ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \
+ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex @backslashchar{}
   '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2]
-   concat=n=3:v=1:a=2 [v] [a1] [a2]' \
+   concat=n=3:v=1:a=2 [v] [a1] [a2]' @backslashchar{}
   -map '[v]' -map '[a1]' -map '[a2]' output.mkv
 @end example
@@ -11071,43 +11071,43 @@ select=0
 Select only I-frames:
+select='eq(pict_type at backslashchar{},I)'
 @end example
 Select one frame every 100:
+select='not(mod(n at backslashchar{},100))'
 @end example
 Select only frames contained in the 10-20 time interval:
+select=between(t at backslashchar{},10 at backslashchar{},20)
 @end example
 Select only I frames contained in the 10-20 time interval:
+select=between(t at backslashchar{},10 at backslashchar{},20)*eq(pict_type at backslashchar{},I)
 @end example
 Select frames with a minimum distance of 10 seconds:
+select='isnan(prev_selected_t)+gte(t-prev_selected_t at backslashchar{},10)'
 @end example
 Use aselect to select only audio frames with samples number > 100:
+aselect='gt(samples_n at backslashchar{},100)'
 @end example
 Create a mosaic of the first scenes:
-ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
+ffmpeg -i video.avi -vf select='gt(scene at backslashchar{},0.4)',scale=160:120,tile -frames:v 1 preview.png
 @end example
 Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane
diff --git a/doc/indevs.texi b/doc/indevs.texi
index dca0f51..9f48079 100644
--- a/doc/indevs.texi
+++ b/doc/indevs.texi
@@ -395,7 +395,7 @@ $ ffmpeg -list_options true -f dshow -i video="Camera"
 Specify pin names to capture by name or alternative name, specify alternative device name:
-$ ffmpeg -f dshow -audio_pin_name "Audio Out" -video_pin_name 2 -i video=video="@@device_pnp_\\?\pci#ven_1a0a&dev_6200&subsys_62021461&rev_01#4&e2c7dd6&0&00e1#@{65e8773d-8f56-11d0-a3b9-00a0c9223196@}\@{ca465100-deb0-4d59-818f-8c477184adf6@}":audio="Microphone"
+$ ffmpeg -f dshow -audio_pin_name "Audio Out" -video_pin_name 2 -i video=video="@@device_pnp_ at backslashchar{}@backslashchar{}?@backslashchar{}pci#ven_1a0a&dev_6200&subsys_62021461&rev_01#4&e2c7dd6&0&00e1#@{65e8773d-8f56-11d0-a3b9-00a0c9223196@}@backslashchar{}@{ca465100-deb0-4d59-818f-8c477184adf6@}":audio="Microphone"
 @end example
diff --git a/doc/metadata.texi b/doc/metadata.texi
index bddcc99..353a4ef 100644
--- a/doc/metadata.texi
+++ b/doc/metadata.texi
@@ -55,7 +55,7 @@ a part of the tag (in the example above key is @samp{foo }, value is
 A ffmetadata file might look like this:
+title=bike at backslashchar{}@backslashchar{}shed
 ;this is a comment
 artist=FFmpeg troll team
@@ -64,9 +64,9 @@ TIMEBASE=1/1000
 #chapter ends at 0:01:00
-title=chapter \#1
+title=chapter @backslashchar{}#1
+title=multi at backslashchar{}
 @end example
diff --git a/doc/muxers.texi b/doc/muxers.texi
index a8225fc..833ee89 100644
--- a/doc/muxers.texi
+++ b/doc/muxers.texi
@@ -759,14 +759,14 @@ Use LATM packetization for AAC.
 @subsection Example
-ffmpeg -i file.mpg -c copy \
-     -mpegts_original_network_id 0x1122 \
-     -mpegts_transport_stream_id 0x3344 \
-     -mpegts_service_id 0x5566 \
-     -mpegts_pmt_start_pid 0x1500 \
-     -mpegts_start_pid 0x150 \
-     -metadata service_provider="Some provider" \
-     -metadata service_name="Some Channel" \
+ffmpeg -i file.mpg -c copy @backslashchar{}
+     -mpegts_original_network_id 0x1122 @backslashchar{}
+     -mpegts_transport_stream_id 0x3344 @backslashchar{}
+     -mpegts_service_id 0x5566 @backslashchar{}
+     -mpegts_pmt_start_pid 0x1500 @backslashchar{}
+     -mpegts_start_pid 0x150 @backslashchar{}
+     -metadata service_provider="Some provider" @backslashchar{}
+     -metadata service_name="Some Channel" @backslashchar{}
      -y out.ts
 @end example
@@ -1071,7 +1071,7 @@ option to force key frames in the input at the specified location, together
 with the segment option @option{segment_time_delta} to account for
 possible roundings operated when setting key frame times.
-ffmpeg -i in.mkv -force_key_frames 1,2,3,5,8,13,21 -codec:v mpeg4 -codec:a pcm_s16le -map 0 \
+ffmpeg -i in.mkv -force_key_frames 1,2,3,5,8,13,21 -codec:v mpeg4 -codec:a pcm_s16le -map 0 @backslashchar{}
 -f segment -segment_list out.csv -segment_times 1,2,3,5,8,13,21 -segment_time_delta 0.05 out%03d.nut
 @end example
 In order to force key frames on the input file, transcoding is
@@ -1095,7 +1095,7 @@ ffmpeg -i in.mkv -map 0 -codec:v libx264 -codec:a libfaac -f ssegment -segment_l
 Segment the input file, and create an M3U8 live playlist (can be used
 as live HLS source):
-ffmpeg -re -i in.mkv -codec copy -map 0 -f segment -segment_list playlist.m3u8 \
+ffmpeg -re -i in.mkv -codec copy -map 0 -f segment -segment_list playlist.m3u8 @backslashchar{}
 -segment_list_flags +live -segment_time 10 out%03d.mkv
 @end example
 @end itemize
@@ -1198,7 +1198,7 @@ that a second level escaping must be performed, as ":" is a special
 character used to separate options.
 ffmpeg -i ... -map 0 -flags +global_header -c:v libx264 -c:a aac -strict experimental
-       -f tee "[bsfs/v=dump_extra]out.ts|[movflags=+faststart]out.mp4|[select=\'a:1\']out.aac"
+       -f tee "[bsfs/v=dump_extra]out.ts|[movflags=+faststart]out.mp4|[select=@backslashchar{}'a:1 at backslashchar{}']out.aac"
 @end example
 @end itemize
@@ -1225,14 +1225,14 @@ audio and video streams. Any number of adaptation sets can be added using this o
 @subsection Example
-ffmpeg -f webm_dash_manifest -i video1.webm \
-       -f webm_dash_manifest -i video2.webm \
-       -f webm_dash_manifest -i audio1.webm \
-       -f webm_dash_manifest -i audio2.webm \
-       -map 0 -map 1 -map 2 -map 3 \
-       -c copy \
-       -f webm_dash_manifest \
-       -adaptation_sets "id=0,streams=0,1 id=1,streams=2,3" \
+ffmpeg -f webm_dash_manifest -i video1.webm @backslashchar{}
+       -f webm_dash_manifest -i video2.webm @backslashchar{}
+       -f webm_dash_manifest -i audio1.webm @backslashchar{}
+       -f webm_dash_manifest -i audio2.webm @backslashchar{}
+       -map 0 -map 1 -map 2 -map 3 @backslashchar{}
+       -c copy @backslashchar{}
+       -f webm_dash_manifest @backslashchar{}
+       -adaptation_sets "id=0,streams=0,1 id=1,streams=2,3" @backslashchar{}
 @end example
diff --git a/doc/protocols.texi b/doc/protocols.texi
index 2a19b41..117e2af 100644
--- a/doc/protocols.texi
+++ b/doc/protocols.texi
@@ -79,7 +79,7 @@ For example to read a sequence of files @file{split1.mpeg},
 @file{split2.mpeg}, @file{split3.mpeg} with @command{ffplay} use the
-ffplay concat:split1.mpeg\|split2.mpeg\|split3.mpeg
+ffplay concat:split1.mpeg at backslashchar{}|split2.mpeg at backslashchar{}|split3.mpeg
 @end example
 Note that you may need to escape the character "|" which is special for
diff --git a/doc/utils.texi b/doc/utils.texi
index 6517ac0..fd00272 100644
--- a/doc/utils.texi
+++ b/doc/utils.texi
@@ -48,14 +48,14 @@ to automatically quote or escape a string in a script.
 Escape the string @code{Crime d'Amour} containing the @code{'} special
-Crime d\'Amour
+Crime d at backslashchar{}'Amour
 @end example
 The string above contains a quote, so the @code{'} needs to be escaped
 when quoting it:
-'Crime d'\''Amour'
+'Crime d'@backslashchar{}''Amour'
 @end example
@@ -67,13 +67,13 @@ Include leading or trailing whitespaces using quoting:
 Escaping and quoting can be mixed together:
-' The string '\'string\'' is a string '
+' The string '@backslashchar{}'string at backslashchar{}'' is a string '
 @end example
 To include a literal @samp{\} you can use either escaping or quoting:
-'c:\foo' can be written as c:\\foo
+'c:@backslashchar{}foo' can be written as c:@backslashchar{}@backslashchar{}foo
 @end example
 @end itemize

More information about the ffmpeg-devel mailing list