[FFmpeg-devel] [PATCH 3/5] doc: More semantic markup using @samp and @var where appropriate

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


---
 doc/ffprobe.texi  | 33 +++++++++++++++++----------------
 doc/filters.texi  | 15 ++++++++-------
 doc/metadata.texi | 26 +++++++++++++++-----------
 doc/utils.texi    | 10 +++++-----
 4 files changed, 45 insertions(+), 39 deletions(-)

diff --git a/doc/ffprobe.texi b/doc/ffprobe.texi
index 0fdf45e..2024eed 100644
--- a/doc/ffprobe.texi
+++ b/doc/ffprobe.texi
@@ -447,17 +447,17 @@ writer).
 It can assume one of the following values:
 @table @option
 @item c
-Perform C-like escaping. Strings containing a newline ('\n'), carriage
-return ('\r'), a tab ('\t'), a form feed ('\f'), the escaping
-character ('\') or the item separator character @var{SEP} are escaped using C-like fashioned
-escaping, so that a newline is converted to the sequence "\n", a
-carriage return to "\r", '\' to "\\" and the separator @var{SEP} is
-converted to "\@var{SEP}".
+Perform C-like escaping. Strings containing a newline (@samp{\n}), carriage
+return (@samp{\r}), a tab (@samp{\t}), a form feed (@samp{\f}), the escaping
+character (@samp{\}) or the item separator character @var{SEP} are escaped
+using C-like fashioned escaping, so that a newline is converted to the
+sequence @samp{\n}, a carriage return to @samp{\r}, @samp{\} to @samp{\\} and
+the separator @var{SEP} is converted to @samp{\@var{SEP}}.
 
 @item csv
 Perform CSV-like escaping, as described in RFC4180.  Strings
-containing a newline ('\n'), a carriage return ('\r'), a double quote
-('"'), or @var{SEP} are enclosed in double-quotes.
+containing a newline (@samp{\n}), a carriage return (@samp{\r}), a double quote
+(@samp{"}), or @var{SEP} are enclosed in double-quotes.
 
 @item none
 Perform no escaping.
@@ -485,7 +485,7 @@ The description of the accepted options follows.
 Separator character used to separate the chapter, the section name, IDs and
 potential tags in the printed field key.
 
-Default value is '.'.
+Default value is @samp{.}.
 
 @item hierarchical, h
 Specify if the section name specification should be hierarchical. If
@@ -507,21 +507,22 @@ The following conventions are adopted:
 @item
 all key and values are UTF-8
 @item
-'.' is the subgroup separator
+ at samp{.} is the subgroup separator
 @item
-newline, '\t', '\f', '\b' and the following characters are escaped
+newline, @samp{\t}, @samp{\f}, @samp{\b} and the following characters are
+escaped
 @item
-'\' is the escape character
+ at samp{\} is the escape character
 @item
-'#' is the comment indicator
+ at samp{#} is the comment indicator
 @item
-'=' is the key/value separator
+ at samp{=} is the key/value separator
 @item
-':' is not used but usually parsed as key/value separator
+ at samp{:} is not used but usually parsed as key/value separator
 @end itemize
 
 This writer accepts options as a list of @var{key}=@var{value} pairs,
-separated by ":".
+separated by @samp{:}.
 
 The description of the accepted options follows.
 
diff --git a/doc/filters.texi b/doc/filters.texi
index aea7272..8361a0a 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -163,13 +163,13 @@ follow the same constraints order of the previous point. The following
 
 If the option value itself is a list of items (e.g. the @code{format} filter
 takes a list of pixel formats), the items in the list are usually separated by
-'|'.
+ at samp{|}.
 
-The list of arguments can be quoted using the character "'" as initial
-and ending mark, and the character '\' for escaping the characters
+The list of arguments can be quoted using the character @samp{'} as initial
+and ending mark, and the character @samp{\} for escaping the characters
 within the quoted text; otherwise the argument string is considered
 terminated when the next special character (belonging to the set
-"[]=;,") is encountered.
+ at samp{[]=;,}) is encountered.
 
 The name and arguments of the filter are optionally preceded and
 followed by a list of link labels.
@@ -4149,7 +4149,7 @@ If @option{expansion} is set to @code{none}, the text is printed verbatim.
 If @option{expansion} is set to @code{normal} (which is the default),
 the following expansion mechanism is used.
 
-The backslash character '\', followed by any character, always expands to
+The backslash character @samp{\}, followed by any character, always expands to
 the second character.
 
 Sequence of the form @code{%@{...@}} are expanded. The text between the
@@ -4181,8 +4181,9 @@ value.
 Evaluate the expression's value and output as formatted integer.
 
 The first argument is the expression to be evaluated, just as for the @var{expr} function.
-The second argument specifies the output format. Allowed values are 'x', 'X', 'd' and
-'u'. They are treated exactly as in the printf function.
+The second argument specifies the output format. Allowed values are @samp{x},
+ at samp{X}, @samp{d} and @samp{u}. They are treated exactly as in the
+ at code{printf} function.
 The third parameter is optional and sets the number of positions taken by the output.
 It can be used to add padding with zeros from the left.
 
diff --git a/doc/metadata.texi b/doc/metadata.texi
index b7fc789..bddcc99 100644
--- a/doc/metadata.texi
+++ b/doc/metadata.texi
@@ -12,10 +12,10 @@ A file consists of a header and a number of metadata tags divided into sections,
 each on its own line.
 
 @item
-The header is a ';FFMETADATA' string, followed by a version number (now 1).
+The header is a @samp{;FFMETADATA} string, followed by a version number (now 1).
 
 @item
-Metadata tags are of the form 'key=value'
+Metadata tags are of the form @samp{key=value}
 
 @item
 Immediately after header follows global metadata
@@ -26,26 +26,30 @@ metadata.
 
 @item
 A section starts with the section name in uppercase (i.e. STREAM or CHAPTER) in
-brackets ('[', ']') and ends with next section or end of file.
+brackets (@samp{[}, @samp{]}) and ends with next section or end of file.
 
 @item
 At the beginning of a chapter section there may be an optional timebase to be
-used for start/end values. It must be in form 'TIMEBASE=num/den', where num and
-den are integers. If the timebase is missing then start/end times are assumed to
+used for start/end values. It must be in form
+ at samp{TIMEBASE=@var{num}/@var{den}}, where @var{num} and @var{den} are
+integers. If the timebase is missing then start/end times are assumed to
 be in milliseconds.
+
 Next a chapter section must contain chapter start and end times in form
-'START=num', 'END=num', where num is a positive integer.
+ at samp{START=@var{num}}, @samp{END=@var{num}}, where @var{num} is a positive
+integer.
 
 @item
-Empty lines and lines starting with ';' or '#' are ignored.
+Empty lines and lines starting with @samp{;} or @samp{#} are ignored.
 
 @item
-Metadata keys or values containing special characters ('=', ';', '#', '\' and a
-newline) must be escaped with a backslash '\'.
+Metadata keys or values containing special characters (@samp{=}, @samp{;},
+ at samp{#}, @samp{\} and a newline) must be escaped with a backslash @samp{\}.
 
 @item
-Note that whitespace in metadata (e.g. foo = bar) is considered to be a part of
-the tag (in the example above key is 'foo ', value is ' bar').
+Note that whitespace in metadata (e.g. @samp{foo = bar}) is considered to be
+a part of the tag (in the example above key is @samp{foo }, value is
+ at samp{ bar}).
 @end enumerate
 
 A ffmetadata file might look like this:
diff --git a/doc/utils.texi b/doc/utils.texi
index 79bf2a2..6517ac0 100644
--- a/doc/utils.texi
+++ b/doc/utils.texi
@@ -12,17 +12,17 @@ explicitly specified. The following rules are applied:
 
 @itemize
 @item
- at code{'} and @code{\} are special characters (respectively used for
+ at samp{'} and @samp{\} are special characters (respectively used for
 quoting and escaping). In addition to them, there might be other
 special characters depending on the specific syntax where the escaping
 and quoting are employed.
 
 @item
-A special character is escaped by prefixing it with a '\'.
+A special character is escaped by prefixing it with a @samp{\}.
 
 @item
-All characters enclosed between '' are included literally in the
-parsed string. The quote character @code{'} itself cannot be quoted,
+All characters enclosed between @samp{''} are included literally in the
+parsed string. The quote character @samp{'} itself cannot be quoted,
 so you may need to close the quote and escape it.
 
 @item
@@ -71,7 +71,7 @@ Escaping and quoting can be mixed together:
 @end example
 
 @item
-To include a literal @code{\} you can use either escaping or quoting:
+To include a literal @samp{\} you can use either escaping or quoting:
 @example
 'c:\foo' can be written as c:\\foo
 @end example
-- 
1.9.1



More information about the ffmpeg-devel mailing list