Update man pages based on avifenc/dec's --help message. #2582
Conversation
Try to minimize differences with the --help message. Ideally, any change should be made in both, unless it's man-page specific formatting. Do not include deprecated flags (--min/--max etc.) Don't impose any line length limit in the markdown files to minimize work. Fixes AOMediaCodec#2534
|
Maryla: Thank you very much! I will take a look. |
|
FYI I started over from the --help message and markdown-ified it, then made a few changes or reverted some. But I did remove some nicer formatting in the man page for the sake of matching the --help message. Let me know if you're ok with this approach or if I should revert more stuff. |
|
Maryla: This is a good approach. I will review the new man pages by comparing them with the help messages. |
doc/avifdec.1.md
Outdated
|
|
||
| : - **8** | ||
| - **16** | ||
| : Output depth [8,16]. (PNG only; For y4m, depth is retained, and JPEG is always 8bpc). |
There was a problem hiding this comment.
we have some inconsistency with how we note intervals and sets. How about {8,16} for a finite set of values and (0..100) (WebP notation in the command line) for an interval?
There was a problem hiding this comment.
I will leave this as is until we have a decision or for some future PR :)
| : Decode all frames and display all image information instead of saving to disk. | ||
|
|
||
| **\--icc** _FILENAME_ | ||
| : Provide an ICC profile payload (implies \--ignore-icc). |
There was a problem hiding this comment.
Which style do we choose ? Provides or Provide ? Below, it is Specifies. The usual where this parameteris implied?
There was a problem hiding this comment.
Good point. I removed a bunch of "set" and "provide" "specify" except where I thought it still made sense. There's probably still room for improvement.
There was a problem hiding this comment.
https://www.gnu.org/prep/standards/html_node/Man-Pages.html#Man-Pages and https://man7.org/linux/man-pages/man7/man-pages.7.html do not seem to address this issue. (I searched for the word "verb" in those two pages and didn't find anything.)
I suggest we follow the convention in the Unix man pages, which seem to use Provide rather than Provides. Here are three examples:
doc/avifenc.1.md
Outdated
| If neither duration nor timescale are set, **avifenc** will attempt to use | ||
| the framerate stored in a y4m header, if present. | ||
| Default is 30. | ||
| : Set the timescale to V. If all frames are 1 timescale in length, this is equivalent to frames per second (Default: 30) |
|
@jzern , what's your take on interval/set notations? From previous discussions for WebP, I believe we chose: |
|
[Maryla: This comment is a discussion, not a request for change.] Re: Vincent's question: For integers we can omit the parentheses and square brackets. The following would be my suggestion:
|
| : Decode all frames and display all image information instead of saving to disk. | ||
|
|
||
| **\--icc** _FILENAME_ | ||
| : Provide an ICC profile payload (implies \--ignore-icc). |
There was a problem hiding this comment.
https://www.gnu.org/prep/standards/html_node/Man-Pages.html#Man-Pages and https://man7.org/linux/man-pages/man7/man-pages.7.html do not seem to address this issue. (I searched for the word "verb" in those two pages and didn't find anything.)
I suggest we follow the convention in the Unix man pages, which seem to use Provide rather than Provides. Here are three examples:
Try to minimize differences with the --help message. Ideally, any change should be made in both, unless it's man-page specific formatting.
Do not include deprecated flags (--min/--max etc.) Don't impose any line length limit in the markdown files to minimize work.
Fixes #2534