[FFmpeg-devel,v2] doc: update loglevel option documentation

Submitted by Tobias Rapp on April 10, 2018, 6:59 a.m.

Details

Message ID 1523343563-1598-1-git-send-email-t.rapp@noa-archive.com
State New
Headers show

Commit Message

Tobias Rapp April 10, 2018, 6:59 a.m.
Updates documentation after the changes to loglevel flag prefix parsing
in 4b736bc921ed96ad6d312ce0cbe0de29b9e3fe81.

Signed-off-by: Tobias Rapp <t.rapp@noa-archive.com>
---
 doc/fftools-common-opts.texi | 37 +++++++++++++++++++++++++++++--------
 1 file changed, 29 insertions(+), 8 deletions(-)

Comments

Lou Logan April 10, 2018, 8:26 p.m.
On Mon, Apr 9, 2018, at 10:59 PM, Tobias Rapp wrote:
>
> +For example to enable repeated log output and set @var{loglevel} to
> +@code{verbose}:
> +@example
> +ffmpeg -loglevel repeat+verbose -i input output
> +@end example

Just to show all current flags and the loglevel I prefer:

For example to enable repeated log output, add the @code{level} prefix, and set @var{loglevel} to
@code{verbose}:
@example
ffmpeg -loglevel repeat+level+verbose -i input output
@end example

> +Another example that disables the @code{level} prefix without affecting the
> +current state of @code{repeat} flag or @var{loglevel}:
> +@example
> +ffmpeg [...] -loglevel -level
> +@end example

I'm not sure how useful this example is. Sure, it displays how to use "-", but is there an actual use case for using "-loglevel -level" since the level prefix is not shown by default anyway?
Tobias Rapp April 11, 2018, 7:11 a.m.
On 10.04.2018 22:26, Lou Logan wrote:
> On Mon, Apr 9, 2018, at 10:59 PM, Tobias Rapp wrote:
>>
>> +For example to enable repeated log output and set @var{loglevel} to
>> +@code{verbose}:
>> +@example
>> +ffmpeg -loglevel repeat+verbose -i input output
>> +@end example
> 
> Just to show all current flags and the loglevel I prefer:
> 
> For example to enable repeated log output, add the @code{level} prefix, and set @var{loglevel} to
> @code{verbose}:
> @example
> ffmpeg -loglevel repeat+level+verbose -i input output
> @end example

OK, will change.

>> +Another example that disables the @code{level} prefix without affecting the
>> +current state of @code{repeat} flag or @var{loglevel}:
>> +@example
>> +ffmpeg [...] -loglevel -level
>> +@end example
> 
> I'm not sure how useful this example is. Sure, it displays how to use "-", but is there an actual use case for using "-loglevel -level" since the level prefix is not shown by default anyway?

Yeah I added this to show that incrementally updating the loglevel 
option and the "-" also works. Can change it to "+" if that is preferred.

BTW: Is there some documentation on the generic flags syntax used in 
FFmpeg for options like "-fflags" or "-cpuflags" and how to combine the 
tokens with "+" or "-"? I couldn't find something on a quick scan.

Regards,
Tobias

Patch hide | download patch | download mbox

diff --git a/doc/fftools-common-opts.texi b/doc/fftools-common-opts.texi
index 185ec21..aa1bb63 100644
--- a/doc/fftools-common-opts.texi
+++ b/doc/fftools-common-opts.texi
@@ -168,14 +168,24 @@  The returned list cannot be assumed to be always complete.
 ffmpeg -sinks pulse,server=192.168.0.4
 @end example
 
-@item -loglevel [repeat+]@var{loglevel} | -v [repeat+]@var{loglevel}
-Set the logging level used by the library.
-Adding "repeat+" indicates that repeated log output should not be compressed
-to the first line and the "Last message repeated n times" line will be
-omitted. "repeat" can also be used alone.
-If "repeat" is used alone, and with no prior loglevel set, the default
-loglevel will be used. If multiple loglevel parameters are given, using
-'repeat' will not change the loglevel.
+@item -loglevel [@var{flags}+]@var{loglevel} | -v [@var{flags}+]@var{loglevel}
+Set logging level and flags used by the library.
+
+The optional @var{flags} prefix can consist of the following values:
+@table @samp
+@item repeat
+Indicates that repeated log output should not be compressed to the first line
+and the "Last message repeated n times" line will be omitted.
+@item level
+Indicates that log output should add a @code{[level]} prefix to each message
+line. This can be used as an alternative to log coloring, e.g. when dumping the
+log to file.
+@end table
+Flags can also be used alone by adding a '+'/'-' prefix to set/reset a single
+flag without affecting other @var{flags} or changing @var{loglevel}. When
+setting both @var{flags} and @var{loglevel}, a '+' separator is expected
+between the last @var{flags} value and before @var{loglevel}.
+
 @var{loglevel} is a string or a number containing one of the following values:
 @table @samp
 @item quiet, -8
@@ -201,6 +211,17 @@  Show everything, including debugging information.
 @item trace, 56
 @end table
 
+For example to enable repeated log output and set @var{loglevel} to
+@code{verbose}:
+@example
+ffmpeg -loglevel repeat+verbose -i input output
+@end example
+Another example that disables the @code{level} prefix without affecting the
+current state of @code{repeat} flag or @var{loglevel}:
+@example
+ffmpeg [...] -loglevel -level
+@end example
+
 By default the program logs to stderr. If coloring is supported by the
 terminal, colors are used to mark errors and warnings. Log coloring
 can be disabled setting the environment variable