My response to "UNIX admin" below. Terry
------------- Begin Forwarded Message ------------- Subject: Re: [docs-discuss] Manual page creation tools To: tripivceta at hotmail.com Mime-Version: 1.0 Content-MD5: MRyTq72f4lWd8qN+r93SCA== Hello, > > I've written some simple manual pages in vi(1) before, but those cannot > compare with the kind of complex layouts and formatting options > that Sun-generated man pages have; I'd like to be able to produce such > quality-formatted documentation too, but haven't found much on the > internet on the subject of writing manual pages (not the content, the > formatting). > Which tools do you use to generate manual pages? > I'm in the SunOS man page group. Our group creates and updates most of the man pages published by Sun. There are other groups within Sun that produce man pages. In some cases, they use different tools from what we use. We use the Epic editor to edit SGML source files that conform to the Solbook 3.5 DTD. One could use any text editor to edit the SGML, but Epic provides features, among which is a link editor, that facilitate creation of properly formatted SGML files. The SunOS man pages end up in the SUNWman package (in nroff form) and on docs.sun.com (as HTML and PDF). In their HTML format, the pages are linked to the rest of Solaris documentation (e.g., admin and programmer's guides). A subset (though nearly all) SunOS pages are made available in a tar ball to OpenSolaris users. > Is there an OpenOffice / StarOffice macro capable of converting ODF > documents to nroff/troff format for manual pages? > I have written quite a bit of documentation in ODF, and it'd be really > slick, if I could produce man(1) command formatted documents. > I'm not aware of such a conversion program. > Is there any tutorial documentation on writing manual pages with > nroff(1) or troff(1), where those tools are well explained, or even > better, where advanced creation techniques for crating manual pages > are discussed in depth? I'd guess you could find some decent tutorial documentation, but I have no specific knowledge of such a document. There is the possibility we could change our tools. This is really a topic for another email, but briefly: Some believe that opening Solaris entails opening up the man page for direct editing by users. Our current tools don't support such activity. There are people in our tools group who are investigating which tools would provide support for direct editing by people outside of Sun. Terry > -- > This message posted from opensolaris.org > _______________________________________________ > docs-discuss mailing list > docs-discuss at opensolaris.org ------------- End Forwarded Message -------------
