RFC: krb5 manual pages becoming groff-only?

[Tom Yu]

Upcoming changes to the MIT krb5 documentation could cause our manual
pages to become unreadable on Unix systems where the "man" program
uses a Unix (AT&T-derived) nroff program instead of the GNU version
(groff).  We would appreciate some feedback about this possibility.
We're soliciting feedback both from people who build our software from
source code, and from redistributors who might customize our software.

Our existing manual pages are hand-coded nroff in the traditional Unix
".man" format.  As part of an effort to improve our documentation, we
are experimenting with consolidating our various documentation sources
(including Unix "man" pages) into Sphinx (http://sphinx.pocoo.org/)
reStructuredText format.

The following questions are directly primarily at people who deal with
Unix systems whose "man" program runs a Unix nroff rather than groff.
More background information follows these questions.

    1. How much will you be inconvenienced if the krb5 manual pages
       became groff-only?

    2. If you're a redistributor, would you translate (manually or
       automatically) our groff-only manual pages into a
       Unix-compatible nroff format?  If not, would you instead be
       willing to distribute our manual pages in a preformatted
       ("catman") form only?

    3. Are you willing to help revise the Docutils manpage writer
       (used by Sphinx to generate manpages) so that it generates
       manual pages compatible with Unix nroff?

    4. What other alternatives do you think we should consider for
       this situation?

Additional background:

Sphinx (in releases 1.0 and later, which are not yet available in some
OS distributions) is capable of generating Unix manual pages, but
these generated manual pages rely on GNU extensions to nroff.  These
generated manual pages do not render correctly on a Unix version of
nroff.  (tested on Solaris 10; some Linux OSes and some BSD
derivatives seem to ship with groff)

While it's possible that the manual page "writer" component of Sphinx
(actually a Docutils component used by Sphinx) could be changed to
generate manual page output that renders correctly under traditional
Unix nroff, such changes would take some time to implement and to
propagate through their release process.  We could develop our own
replacement for that component, but that creates more maintenance
difficulties for us.

It is very likely that we will either generate the manual pages from
Sphinx when we build release tarfiles, or periodically check in
generated manual pages to the source repository as needed.  This
avoids requiring casual builders to install the most recent version of
Sphinx (which might not be readily available on their OSes), but does
not necessarily remove the requirement to have groff available.