manpages is mdoc(7)

[Rainer Müller]

On 03/30/2017 07:08 PM, Jan Stary wrote:
> Currently, the port-* manpages are written
> using the legacy man(7) language which uses
> low-level roff constructs to described presentational details.
> 
> I propose to rewrite them into the _semantic_ markup of mdoc(7) language.
> Both have been around for decades and are well supported by groff.
> 
> As an example, please see a proposed rewrite of port-cat.1
> (and compare it to the current version).

Our man pages are actually written in AsciiDoc and then converted to the roff
output. We only maintain the generated roff output in the repository to solve
the problem of installing base without any external dependencies.

Changing the output format would require adjusting the corresponding DocBook XSL
stylesheets, which is not trivial and out of our scope.

To edit the man pages, first get the required dependencies:

$ sudo port install asciidoc docbook-xsl

1) Modify port-*.1.txt
2) Run 'make' to generate port-*.1
3) Check result 'man ./port-*.1' and repeat 1)-2) as necessary

To finalize your changes:

4) git commit -m 'Fix ...' port-*.1.txt
5) make
6) git commit -m 'Regenerate man pages' port-*.1

This separate commit after regenerating is required because the build rules use
the git author date of the latest commit to set the date of the man page.

Rainer