This repository holds a small stand-alone utility which helps with converting illumos man pages from the legacy man(7) format to the newer mdoc(7).
It does not aim to completely automate conversion, the output will need reviewing and more work, but it does take care of the more laborious conversion tasks, speeding up the process.
This tool will likely continue to evolve (and pull requests or feature requests
are very welcome) but it's already pretty good at reformatting long paragraphs
or textual sections (such as DESCRIPTION), fixing up formatting and converting
cross references. It also has a fairly good stab at converting lists (although
it currently assumes that they are in a specific form) and it can handle
nested lists and bullet points. Even when it gets this a bit wrong, there is
still a lot less work needed by the human editor afterwards.
It does not currently attempt to transform the SYNOPSIS or ATTRIBUTES
sections beyond formatting.
The illumos-gate prototype templates
provide useful guidance on completing conversion of ATTRIBUTES in particular.
tomdoc can be used as a filter or by providing a filename as the only
argument. Usage is generally something like one of these:
% ./tomdoc /usr/share/man/man1/zonename.1 > zonename.1
% ./tomdoc /usr/share/man/man1/zonename.1 | less
% ./tomdoc < /usr/share/man/man1/zonename.1 | mandoc | less
Processing the DESCRIPTION section from adb(1).
There is one instance of .Sy mdb , in the output there that I would possibly
manually adjust (one feature of the old format man pages is very liberal use
of emboldening that I have generally not seen carried forward in conversions),
but otherwise it's exactly what I would have done by hand.
% ./tomdoc /usr/share/man/man1/adb.1 | sed -n '/Sh DESCRIPTION/,/^\.Sh/p'
.Sh DESCRIPTION
The
.Nm
utility is an interactive, general-purpose debugger.
It can be used to examine files and provides a controlled environment for
the execution of programs.
.Pp
The
.Nm
utility is now implemented as a link to the
.Xr mdb 1
utility.
.Xr mdb 1
is a low-level debugging utility that can be used to examine user processes
as well as the live operating system or operating system crash dumps.
The new
.Xr mdb 1
utility provides complete backwards compatibility with the existing syntax
and features of
.Nm ,
including support for processing
.Nm
macro files.
The
.%T Modular Debugger Guide
and
.Xr mdb 1
man page describe the features of
.Sy mdb ,
including its
.Nm
compatibility mode.
This mode will be activated by default when the
.Nm
link is executed.