🔗 David Sommerseth on Nostr: npub1p450a…789jz In the OpenVPN project, we had the man page as a nroff/groff ...
npub1p450apv3j8jmqjct3ddfklzusxyfkkyqpzxx4p33u099xjzvfwwsw789jz (npub1p45…89jz)
In the OpenVPN project, we had the man page as a nroff/groff formatted page which was insane to edit. Some years ago, we converted it into .rst files and generate the proper man-page using rst2man. We also split all the text into several .rst files being included from a "main file", so the result is the same single man page.
This move gave us a few advantages ... some not even intended.
A lot more people were able to correctly edit and fix the man page content.
Using more advanced groff formatting is handled far more easier (like tables, "code sections", indented "blobs" for warnings/notes, etc)
The restructuring allowed us to even split out a whole section into its own man page very easily (like example configurations)
A single source of truth, the .rst files - regardless of rendering approach (plain text, man/nroff/groff, web)
GitHub and GitLab renders the .rst files quite nicely, which makes it easier to read when supporting users, just by giving them a URL to the right area from the code repos ... which then is always kept up-to-date.
https://github.com/OpenVPN/openvpn/tree/master/doc/man-sections/link-options.rst
https://gitlab.com/openvpn/openvpn/-/blob/master/doc/man-sections/link-options.rst
In the OpenVPN project, we had the man page as a nroff/groff formatted page which was insane to edit. Some years ago, we converted it into .rst files and generate the proper man-page using rst2man. We also split all the text into several .rst files being included from a "main file", so the result is the same single man page.
This move gave us a few advantages ... some not even intended.
A lot more people were able to correctly edit and fix the man page content.
Using more advanced groff formatting is handled far more easier (like tables, "code sections", indented "blobs" for warnings/notes, etc)
The restructuring allowed us to even split out a whole section into its own man page very easily (like example configurations)
A single source of truth, the .rst files - regardless of rendering approach (plain text, man/nroff/groff, web)
GitHub and GitLab renders the .rst files quite nicely, which makes it easier to read when supporting users, just by giving them a URL to the right area from the code repos ... which then is always kept up-to-date.
https://github.com/OpenVPN/openvpn/tree/master/doc/man-sections/link-options.rst
https://gitlab.com/openvpn/openvpn/-/blob/master/doc/man-sections/link-options.rst