Add man pages for `avifenc` and `avifdec` (#916)
`AVIF_BUILD_MAN_PAGES` requires `AVIF_BUILD_APPS` to be on.
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 663a6ec..8410435 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -523,6 +523,37 @@
add_subdirectory(tests)
endif()
+option(AVIF_BUILD_MAN_PAGES "Build avif man pages." OFF)
+if(AVIF_BUILD_MAN_PAGES)
+ if(AVIF_BUILD_APPS)
+ find_program(PANDOC_EXE pandoc)
+ if(PANDOC_EXE)
+ message(STATUS "libavif: Using pandoc: ${PANDOC_EXE}")
+ else()
+ message(FATAL_ERROR "libavif: Pandoc is missing, bailing out")
+ endif()
+
+ set(MAN_PAGES avifenc.1 avifdec.1)
+
+ foreach(MAN_PAGE ${MAN_PAGES})
+ add_custom_command(
+ OUTPUT ${MAN_PAGE}
+ COMMAND ${PANDOC_EXE} -s -V "footer=libavif ${PROJECT_VERSION}" -f markdown -t man -o
+ "${CMAKE_CURRENT_BINARY_DIR}/${MAN_PAGE}" "${CMAKE_CURRENT_SOURCE_DIR}/docs/${MAN_PAGE}.md"
+ DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/docs/${MAN_PAGE}.md"
+ VERBATIM
+ )
+ endforeach()
+ add_custom_target(man_pages ALL DEPENDS ${MAN_PAGES})
+
+ foreach(MAN_PAGE ${MAN_PAGES})
+ install(FILES "${CMAKE_CURRENT_BINARY_DIR}/${MAN_PAGE}" DESTINATION "${CMAKE_INSTALL_MANDIR}/man1")
+ endforeach()
+ else()
+ message(WARNING "libavif: No man pages is built (AVIF_BUILD_MAN_PAGES); AVIF_BUILD_APPS must be on.")
+ endif()
+endif()
+
if(NOT SKIP_INSTALL_LIBRARIES AND NOT SKIP_INSTALL_ALL)
install(
TARGETS avif
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..6f87a91
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,8 @@
+# libavif man pages
+
+This contains the man pages for `avifenc` and `avifdec`. These are written in
+[pandoc's Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown), so
+[pandoc](https://pandoc.org/) is required to build these.
+
+Building man pages is disabled by default. Enable the CMake option
+`AVIF_BUILD_MAN_PAGES` to build these.
diff --git a/docs/avifdec.1.md b/docs/avifdec.1.md
new file mode 100644
index 0000000..dcac08d
--- /dev/null
+++ b/docs/avifdec.1.md
@@ -0,0 +1,127 @@
+% AVIFDEC(1) | General Commands Manual
+%
+% 2022-04-30
+
+<!--
+This man page is written in pandoc's Markdown.
+See: https://pandoc.org/MANUAL.html#pandocs-markdown
+-->
+
+# NAME
+
+avifdec - decompress an AVIF file to an image file
+
+# SYNOPSIS
+
+**avifdec** [_options_] _input.avif_ _output._[_jpg_|_jpeg_|_png_|_y4m_]
+
+**avifdec** **\--info** _input.avif_
+
+# DESCRIPTION
+
+**avifdec** decompresses an AVIF file to an image file.
+Output format can be either JPEG, PNG or YUV4MPEG2 (Y4M).
+
+# OPTIONS
+
+**-h**, **\--help**
+: Show syntax help.
+
+**-V**, **\--version**
+: Show the version number.
+
+**-j**, **\--jobs** _J_
+: Number of jobs (worker threads).
+ 1 or less means single-threaded.
+ Default is 1.
+ Use **all** to use all available cores.
+
+**-c**, **\--codec** _C_
+: AV1 codec to use.
+ Possible values depend on the codecs enabled at build time (see **\--help**
+ or **\--version** for the available codecs).
+ Default is auto-selected from the available codecs.
+
+ Possible values are:
+
+ : - **aom**
+ - **dav1d**
+ - **libgav1**
+
+**-d**, **\--depth** _D_
+: Output PNG depth.
+ Ignored when the output format is JPEG (always 8 bits per channel) or Y4M
+ (input depth is retained).
+
+ Possible values are:
+
+ : - **8**
+ - **16**
+
+**-q**, **\--quality** _Q_
+: Output JPEG quality in the range **0**-**100**.
+ Default is 90.
+ Ignored if the output format is not JPEG.
+
+**\--png-compress** _L_
+: Output PNG compression level in the range **0**-**9** (fastest to maximum
+ compression).
+ Default is libpng's built-in default.
+ Ignored if the output format is not PNG.
+
+**-u**, **\--upsampling** _U_
+: Chroma upsampling method.
+ Ignored unless the input format is 4:2:0 or 4:2:2.
+
+ Possible values are:
+
+ : - **automatic** (default)
+ - **fastest**
+ - **best**
+ - **nearest**
+ - **bilinear**
+
+**-r**, **\--raw-color**
+: Output raw RGB values instead of multiplying by alpha when saving to opaque
+ formats.
+ This is available if the output format is JPEG, and not applicable to y4m.
+
+**\--index** _I_
+: When decoding an image sequence or progressive image, specify which frame
+ index to decode.
+ Default is 0.
+
+**\--progressive**
+: Enable progressive AVIF processing.
+ If a progressive image is encountered and **\--progressive** is passed,
+ **avifdec** will use **\--index** to choose which layer to decode (in
+ progressive order).
+
+**\--no-strict**
+: Disable strict decoding, which disables strict validation checks and errors.
+
+**-i**, **\--info**
+: Decode all frames and display all image information instead of saving to
+ disk.
+
+**\--ignore-icc**
+: If the input file contains an embedded ICC profile, ignore it (no-op if
+ absent).
+
+**\--size-limit** _C_
+: Specifies the image size limit (in total pixels) that should be tolerated.
+ Default is 268,435,456 pixels (16,384 by 16,384 pixels for a square image).
+
+# EXAMPLES
+
+Decompress an AVIF file to a PNG file:
+: $ **avifdec input.avif output.png**
+
+# REPORTING BUGS
+
+Bugs can be reported on GitHub at:
+: <https://github.com/AOMediaCodec/libavif/issues>
+
+# SEE ALSO
+
+**avifenc**(1)
diff --git a/docs/avifenc.1.md b/docs/avifenc.1.md
new file mode 100644
index 0000000..7196278
--- /dev/null
+++ b/docs/avifenc.1.md
@@ -0,0 +1,241 @@
+% AVIFENC(1) | General Commands Manual
+%
+% 2022-04-30
+
+<!--
+This man page is written in pandoc's Markdown.
+See: https://pandoc.org/MANUAL.html#pandocs-markdown
+-->
+
+# NAME
+
+avifenc - compress an image file to an AVIF file
+
+# SYNOPSIS
+
+**avifenc** [_options_] _input._[_jpg_|_jpeg_|_png_|_y4m_] _output.avif_
+
+# DESCRIPTION
+
+**avifenc** compresses an image file to an AVIF file.
+Input format can be either JPEG, PNG or YUV4MPEG2 (Y4M).
+
+# OPTIONS
+
+**-h**, **\--help**
+: Show syntax help.
+
+**-V**, **\--version**
+: Show the version number.
+
+**-j**, **\--jobs** _J_
+: Number of jobs (worker threads).
+ 1 or less means single-threaded.
+ Default is 1.
+ Use **all** to use all available cores.
+
+**-o**, **\--output** _FILENAME_
+: Instead of using the last filename given as output, use this filename.
+
+**-l**, **\--lossless**
+: Set all defaults to encode losslessly, and emit warnings when
+ settings/input don't allow for it.
+
+**-d**, **\--depth** _D_
+: Output depth.
+ This is available if the input format is JPEG/PNG, and for y4m or stdin,
+ depth is retained.
+
+ Possible values are:
+
+ : - **8**
+ - **10**
+ - **12**
+
+**-y**, **\--yuv** _FORMAT_
+: Output format.
+ Ignored for y4m or stdin (y4m format is retained).
+ For JPEG, auto honors the JPEG's internal format, if possible.
+ For all other cases, auto defaults to 444.
+
+ Possible values are:
+
+ : - **auto** (default)
+ - **444**
+ - **422**
+ - **420**
+ - **400**
+
+**-p**, **\--premultiply**
+: Premultiply color by the alpha channel and signal this in the AVIF.
+
+**\--stdin**
+: Read y4m frames from stdin instead of files.
+ No input filenames allowed, must be set before specifying the output
+ filename.
+
+**\--cicp**, **\--nclx** *P***/***T***/***M*
+: Specify CICP values (nclx colr box) by 3 raw numbers.
+ Use **2** for any you wish to leave unspecified.
+
+ - _P_ = color primaries
+ - _T_ = transfer characteristics
+ - _M_ = matrix coefficients
+
+**-r**, **\--range** _RANGE_
+: YUV range.
+ This is available if the input format is JPEG/PNG, and for y4m or stdin,
+ range is retained.
+
+ Possible values are:
+
+ : - **full**, **f** (default)
+ - **limited**, **l**
+
+**\--min** _Q_
+: Set min quantizer for color.
+ Possible values are in the range **0**-**63**, where 0 is lossless.
+
+**\--max** _Q_
+: Set max quantizer for color.
+ Possible values are in the range **0**-**63**, where 0 is lossless.
+
+**\--minalpha** _Q_
+: Set min quantizer for alpha.
+ Possible values are in the range **0**-**63**, where 0 is lossless.
+
+**\--maxalpha** _Q_
+: Set max quantizer for alpha.
+ Possible values are in the range **0**-**63**, where 0 is lossless.
+
+**\--tilerowslog2** _R_
+: Set log2 of number of tile rows.
+ Possible values are in the range **0**-**6**.
+ Default is 0.
+
+**\--tilecolslog2** _C_
+: Set log2 of number of tile columns.
+ Possible values are in the range **0**-**6**.
+ Default is 0.
+
+**-g**, **\--grid** *M***x***N*
+: Encode a single-image grid AVIF with _M_ cols and _N_ rows.
+ Either supply MxN images of the same width, height and depth, or a single
+ image that can be evenly split into the MxN grid and follow AVIF grid image
+ restrictions.
+ The grid will adopt the color profile of the first image supplied.
+ Possible values for _M_ and _N_ are in the range **1**-**256**.
+
+**-s**, **\--speed** _S_
+: Encoder speed.
+ Default is 6.
+
+ Possible values are:
+
+ : - **0**-**10** (slowest-fastest)
+ - **default**, **d** (codec internal defaults)
+
+**-c**, **\--codec** _C_
+: AV1 codec to use.
+ Possible values depend on the codecs enabled at build time (see **\--help**
+ or **\--version** for the available codecs).
+ Default is auto-selected from the available codecs.
+
+ Possible values are:
+
+ : - **aom**
+ - **rav1e**
+ - **svt**
+
+**\--exif** _FILENAME_
+: Provide an Exif metadata payload to be associated with the primary item.
+
+**\--xmp** _FILENAME_
+: Provide an XMP metadata payload to be associated with the primary item.
+
+**\--icc** _FILENAME_
+: Provide an ICC profile payload to be associated with the primary item.
+
+**-a**, **\--advanced** _KEY_[_=VALUE_]
+: Pass an advanced, codec-specific key/value string pair directly to the
+ codec.
+ **avifenc** will warn on any unused by the codec.
+ The aom-specific advanced options can be used if the AOM codec is available
+ (see **\--help** for details).
+
+**\--duration** _D_
+: Set all following frame durations (in timescales) to _D_.
+ Can be set multiple times (before supplying each filename).
+ Default is 1.
+
+**\--timescale**, **\--fps** _V_
+: Set the timescale to _V_.
+ If all frames are 1 timescale in length, this is equivalent to frames per
+ second.
+ If neither duration nor timescale are set, **avifenc** will attempt to use
+ the framerate stored in a y4m header, if present.
+ Default is 30.
+
+**-k**, **\--keyframe** _INTERVAL_
+: Set the forced keyframe interval (maximum frames between keyframes).
+ Set to **0** to disable.
+ Default is 0.
+
+**\--ignore-icc**
+: If the input file contains an embedded ICC profile, ignore it (no-op if
+ absent).
+
+**\--pasp** *H***,***V*
+: Add pasp property (aspect ratio).
+
+ - _H_ = horizontal spacing
+ - _V_ = vertical spacing
+
+**\--crop** *CROPX***,***CROPY***,***CROPW***,***CROPH*
+: Add clap property (clean aperture), but calculated from a crop rectangle.
+
+ - _CROPX_ = X-axis of a crop rectangle
+ - _CROPY_ = Y-axis of a crop rectangle
+ - _CROPW_ = width of a crop rectangle
+ - _CROPH_ = height of a crop rectangle
+
+**\--clap** *WN***,***WD***,***HN***,***HD***,***HON***,***HOD***,***VON***,***VOD*
+: Add clap property (clean aperture).
+
+ - _WN_ = numerator of width
+ - _WD_ = denominator of width
+ - _HN_ = numerator of height
+ - _HD_ = denominator of height
+ - _HON_ = numerator of horizontal offset
+ - _HOD_ = denominator of horizontal offset
+ - _VON_ = numerator of vertical offset
+ - _VOD_ = denominator of vertical offset
+
+**\--irot** _ANGLE_
+: Add irot property (rotation).
+ Possible values are in the range **0**-**3**, and makes (90 * _ANGLE_)
+ degree rotation anti-clockwise.
+
+**\--imir** _MODE_
+: Add imir property (mirroring).
+
+ Note: Rotation is applied before mirroring at rendering.
+
+ Possible values are:
+
+ : - **0** (top-to-bottom)
+ - **1** (left-to-right)
+
+# EXAMPLES
+
+Compress a PNG file to an AVIF file:
+: $ **avifenc input.png output.avif**
+
+# REPORTING BUGS
+
+Bugs can be reported on GitHub at:
+: <https://github.com/AOMediaCodec/libavif/issues>
+
+# SEE ALSO
+
+**avifdec**(1)
