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. ________________________________________________ Kerberos mailing list [email protected] https://mailman.mit.edu/mailman/listinfo/kerberos
