[FFmpeg-devel] [PATCH] doc/libavutil: add "Logging" chapter

[Alexander Strasser]

Hi Stefano,

Stefano Sabatini wrote:
> In particular, mention the environment variable which affect the logging
> color.
> ---
>  doc/libavutil.texi |   17 +++++++++++++++++
>  1 file changed, 17 insertions(+)
> 
> diff --git a/doc/libavutil.texi b/doc/libavutil.texi
> index e5304bb..e9fc1b2 100644
> --- a/doc/libavutil.texi
> +++ b/doc/libavutil.texi
> @@ -20,6 +20,23 @@ enumerations for pixel and sample formats).
>  
>  @c man end DESCRIPTION
>  
> + at chapter Logging
> + at c man begin LOGGING
> +
> +The libavutil library provides some logging utilities through the
> + at file{libavutil/log.h} interface. The logging level in the FFmpeg
> +tools can be set through the @code{loglevel} option.

  It might make sense to mention here that there is the possibility
to override the log function with av_log_set_callback. From a quick
scan of libavutil/log.h it seems that we are short of documentation
of that function thought. So it might make sense to document it first
before mentioning it here.

  If you mention the log callback overriding above you can state that
the following paragraph is about the behaviour of the default callback
provided by libavutil.

  This is only a suggestion and should probably delayed until the
API docs of log.h are more complete.

> +By default the library 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
> + at env{AV_LOG_FORCE_NOCOLOR} or @env{NO_COLOR}, or can be forced setting
> +the environment variable @env{AV_LOG_FORCE_COLOR}. The use of the
> +environment variable @env{NO_COLOR} is deprecated and will be dropped
> +in a following FFmpeg version.

"
                                                      The environment
variable @env{NO_COLOR} is deprecated and will likely be ignored by
by future FFmpeg versions.
"

  I think that version sounds more natural and is easier to grasp. I am not
sure if the concept of "a following version" is usually used in English. But
I am not a native English speaker as most of you probably know.

> +
> + at c man end LOGGING
> +
>  @include syntax.texi
>  @include eval.texi
>  
> -- 
> 1.7.9.5

  Alexander