add manual page in pod format

[josch]

When not installing box64 from git but from a distro package manager (like apt install box64) then one expects man box64 to contain reasonable documentation as the user will not have access to the files from the git repository.

Unfortunately, the format man pages are written in, is quite hard to read and write (I think) so I prepared a manual page in the POD format which can be turned into a man page by running:

pod2man --center "Manual" --release "box64 0.2.2" box64.pod

Maybe CMake should do that conversion?

[ptitSeb]

Thanks. I need to remember that the pod file needs to be updated along the USAGE.md or can the pod also be converted as a markdown?

[josch]

There is https://github.com/remarkjs/remark-man and https://github.com/sunaku/md2man. The former is not packaged in Debian or Ubuntu, the latter is.

Another option would be to store the environment variables and their documentation in a machine readable format and from that generate:

• the --help output of box64
• a human readable markdown manual like USAGE.md
• a man page in roff format

What would you prefer?

I also noticed that I copypasted more spelling mistakes and/or typos from USAGE.md into the man page. I'll send a follow-up pull request about that in a bit.

[josch]

Another option: help2man

The advantage of pod2man is, that it is part of Perl itself which is already available on most platforms. A disadvantage of a markdown to roff converter would be, that it would add another build dependency. Another disadvantage of converting Markdown to roff is, that the markdown format does not have the concept of named lists, that is, lists where each item has a name (or subject or heading). For example with POD I can create a man page that ends up looking like this (taking box64 as an example):

       BOX64_ENV=env=val
               Add an variable with value to the environment.

       BOX64_ENV1=env=val BOX64_ENV2=env=val ...
               Add arbitrary many variables using BOX64_ENV1, BOX64_ENV2, ...

       BOX64_NORCFILES
               No rc files (like /etc/box64.box64rc and ~/.box64rc) will be loaded.

I'm not aware how to do this with markdown, unless one makes each environment variable its own subsection?

[josch]

Another option: help2man

The advantage of pod2man is, that it is part of Perl itself which is already available on most platforms. A disadvantage of a markdown to roff converter would be, that it would add another build dependency. Another disadvantage of converting Markdown to roff is, that the markdown format does not have the concept of named lists, that is, lists where each item has a name (or subject or heading). For example with POD I can create a man page that ends up looking like this (taking box64 as an example):

       BOX64_ENV=env=val
               Add an variable with value to the environment.

       BOX64_ENV1=env=val BOX64_ENV2=env=val ...
               Add arbitrary many variables using BOX64_ENV1, BOX64_ENV2, ...

       BOX64_NORCFILES
               No rc files (like /etc/box64.box64rc and ~/.box64rc) will be loaded.

I'm not aware how to do this with markdown, unless one makes each environment variable its own subsection?

[ptitSeb]

The convertion tool from pod (or whatever) to md doesn't need to be in the makefile. It could be a manual process pod -> md, just done when the help is updated.