[GH-ISSUE #247] Update man page for 2.0 release #177

New issue

Closed

opened 2026-02-25 20:32:58 +03:00 by kerem · 4 comments

kerem commented

2026-02-25 20:32:58 +03:00

Owner

Originally created by @ku1ik on GitHub (Dec 2, 2017).
Original GitHub issue: https://github.com/asciinema/asciinema/issues/247

Would be great if we could generate man page automatically from some parts of the README file.

Originally created by @ku1ik on GitHub (Dec 2, 2017). Original GitHub issue: https://github.com/asciinema/asciinema/issues/247 Would be great if we could generate man page automatically from some parts of the README file.

kerem

2026-02-25 20:32:58 +03:00

closed this issue
added the
help wanted
label

kerem commented

2026-02-25 20:32:58 +03:00

Author

Owner

@pdfkungfoo commented on GitHub (Dec 9, 2017):

For when do you aim at a release?

I could probably help in writing the man page or updating the existing one. (I most likely cannot be of any help with generating the man page from [parts of] the README file.)

From what I see is that you currently keep the man page in groff in the sources. What I would do is write the man page in (Pandoc's dialect of) Markdown, then use pandoc --from markdown --to man in order to get the groff. You may want to consider keeping the markdown in the source tree as well?

@pdfkungfoo commented on GitHub (Dec 9, 2017): For when do you aim at a release? I could probably help in writing the man page or updating the existing one. *(I most likely* **cannot** *be of any help with generating the man page from [parts of] the README file.)* From what I see is that you currently keep the man page in groff in the sources. What I would do is write the man page in (Pandoc's dialect of) Markdown, then use *`pandoc --from markdown --to man`* in order to get the groff. You may want to consider keeping the markdown in the source tree as well?

kerem commented

2026-02-25 20:32:58 +03:00

Author

Owner

@pdfkungfoo commented on GitHub (Dec 9, 2017):

@sickill,

I created a Gist for you to look at. It contains the current manpage converted to Markdown, with some additions for (so far empty) sections:

https://gist.github.com/KurtPfeifle/163305395f14733d276e8f358d907eb2

Be sure to also read my comment in that Gist....

Do you also want man pages describing the v1 and v2 formats? (These would probably have to go to "Section 7" of the manual pages.)

Cheers,
-kp-

@pdfkungfoo commented on GitHub (Dec 9, 2017): @sickill, I created a Gist for you to look at. It contains the current manpage converted to Markdown, with some additions for (so far empty) sections: * https://gist.github.com/KurtPfeifle/163305395f14733d276e8f358d907eb2 Be sure to also read my comment in that Gist.... Do you also want man pages describing the v1 and v2 formats? (These would probably have to go to "Section 7" of the manual pages.) Cheers, -kp-

kerem commented

2026-02-25 20:32:58 +03:00

Author

Owner

@asnair commented on GitHub (Dec 25, 2017):

If you wanted to generate parts of the man page from the README instead of vice versa as @KurtPfeifle suggests, an idea to do so would just be to find code blocks from the README using regex and dump them as well as the line before the code block into the man page, as well as bulleted lists maybe? KP's method seems much more reliable.

If you want to stick to regex, a small bash script for pulling out the code blocks and line before could be the following:

sudo cat README.md | sed -n '/^```/,/^```/ p' | sed '/^```/ d' | sudo tee man.page

Note if you wanted to get the line before as well as the code block, you could use the following code to get the line before using sed and buffers, although grep might be a better tool but then cutting out the ``` might be more difficult: http://www.grymoire.com/Unix/Sed.html#uh-54

@asnair commented on GitHub (Dec 25, 2017): If you wanted to generate parts of the man page from the README instead of vice versa as @KurtPfeifle suggests, an idea to do so would just be to find code blocks from the README using regex and dump them as well as the line before the code block into the man page, as well as bulleted lists maybe? KP's method seems much more reliable. If you want to stick to regex, a small bash script for pulling out the code blocks and line before could be the following: ``` sudo cat README.md | sed -n '/^```/,/^```/ p' | sed '/^```/ d' | sudo tee man.page ``` Note if you wanted to get the line before as well as the code block, you could use the following code to get the line before using sed and buffers, although grep might be a better tool but then cutting out the \`\`\` might be more difficult: http://www.grymoire.com/Unix/Sed.html#uh-54

kerem commented

2026-02-25 20:32:58 +03:00

Author

Owner

@ku1ik commented on GitHub (Feb 5, 2018):

@asnair thanks for suggestion. I went with separate source markdown file as it's indeed more reliable option.

@KurtPfeifle thanks for help with this!

@ku1ik commented on GitHub (Feb 5, 2018): @asnair thanks for suggestion. I went with separate source markdown file as it's indeed more reliable option. @KurtPfeifle thanks for help with this!