Skip to main content

We first made the #curl build use #nroff for building the hugehelp file in December 1998, for curl 5.2. This makes "curl -M" work.

Now, I'm working on a change that finally removes nroff from the curl build process: github.com/curl/curl/pull/1304…


docs: ascii version of manpage without nroff by bagder · Pull Request #13047 · curl/curl

create ascii version of the manpage without nroff build src/tool_hugegelp.c from the ascii manpage move the the manpage and the ascii version build to docs/cmdline-opts remove all use of nroff fro...
GitHub
#curl #nroff
in reply to daniel:// stenberg://

🔗 David Sommerseth
🔗 David Sommerseth
• •

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.

github.com/OpenVPN/openvpn/tre…

gitlab.com/openvpn/openvpn/-/b…

doc/man-sections/link-options.rst · master · OpenVPN / openvpn · GitLab

Upstream OpenVPN 2.x source tree. This is one of several public git repositories which are intended to be kept in sync.
GitLab
⇧