Stephen Hahn <[EMAIL PROTECTED]> wrote: > * Joerg Schilling <[EMAIL PROTECTED]> [2008-01-15 14:03]: > > Stephen Hahn <[EMAIL PROTECTED]> wrote: > > while I see this kind of review, it reminds me on recently introduced > > problems with the man pages: > > How recently do you mean? Many of the poorly formatted pages have > always seemed to me to be tied to the conversion to SGML as the > definitive source. (I'm sure you recall that the formatting used to > be much worse.)
Wich Solaris 9, you get sgml man pages and a tool (/usr/lib/sgml/sgml2roff) that converts into halfway acceptable troff. On Solaris 11 and on the man page downloads from: http://opensolaris.org/os/downloads/manpages/ are troff man pages, so I asume that the primary format is troff again. Note that the man pages need to be in a format that is editable by the community since we are on OpenSolaris. The man pages degraded in many aspects. e.g. superfluous blank lines that make the printed version ugly (man(1) calls more -s to remove superfluous blank lines making this aspect invisible on the screen) and using troff low level escape sequences instead of the official man(5) macro calls. > > - The man pages do no longer use the official "man -s5 man" structuring > > rules. Example: Option desriptions are correctly written: > > > > .TP > > .B \-option > > option description. > > > > The Solaris man pages instead use strange absolut positioning and font > > switching. > > I suspect this arises from the conversion from SGML/XML. What is the current internal format at Sun? Note that even on Solaris 9 the backtransformed troff was better than the troff code seen on Solaris 11. > > - Many man pages are indented too much resulting in several man pages > > to become unreadable: > > > > Example: "man sccs-admin" > > Also this (but possibly incorrectly tagged in SGML). man(1) formats troff (nroff). The official troff macros correctly deal with the differences between printed (troff) conversions for paper output and online manuals for a tty. > > - Several man pages include incorrectly expanded SCCS keywords. > > Example "man sccs-val" where even an expected %Y% was replaced by > > an expaned %T%. > > That's a content bug, and should be straightforward to fix. Well, replace %T% by %Y% and then e.g. call: sccs admin -fs30 sccs-val.1 Jörg -- EMail:[EMAIL PROTECTED] (home) Jörg Schilling D-13353 Berlin [EMAIL PROTECTED] (uni) [EMAIL PROTECTED] (work) Blog: http://schily.blogspot.com/ URL: http://cdrecord.berlios.de/old/private/ ftp://ftp.berlios.de/pub/schily _______________________________________________ opensolaris-code mailing list [email protected] http://mail.opensolaris.org/mailman/listinfo/opensolaris-code
