Hi all, Thanks for the new subject-line. I will certainly look into the issues cited in your previous mail regarding the sccs-admin and sccs-val man pages. My additional comments inline below.
Joerg Schilling wrote: > 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 redistributable man pages on the downloads center are nroff. However, the primary format is still SGML. We continue to work hard on the issues that will enable us, once overcome, to author and make redistributable SolBook XML man page source files rather than just the generated nroff. I'm currently working the conversion to XML and cleanup, tools development and/or man command development, and teamware to Mercurial transition for the gate. > 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? > Current internal format is SolBook SGML. > 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. >> Yes, I will check on this specific problem. Joerg, I realize that you are calling out a larger, more global issue, however I'm not exactly sure what it is, or maybe it is the list of several issues in your previous mail? Either way, let's discuss it further offline or on the docs-discuss list, so I can better understand your concerns. Regards, Michelle > > Well, replace %T% by %Y% and then e.g. call: > > sccs admin -fs30 sccs-val.1 > > Jörg > > _______________________________________________ opensolaris-code mailing list [email protected] http://mail.opensolaris.org/mailman/listinfo/opensolaris-code
