Re: POSIX.1-2013 man pages for review

[John Spencer <maillist-musl-Am5OCHYCrcUb1SvskN2V4Q@public.gmane.org>]

On 09/20/2013 07:54 PM, Felix Janda wrote:
> John Spencer wrote:
>> musl itself does not use the man-pages project currently, as the
>> majority of manpages are very glibc specific. so the posix manpages
>> project is _imo_ currently a much better documentation for the
>> interfaces provided by musl.
>
> On the other hand the section 2 man pages from linux-manpages documenting
> Linux specific behavior of system calls might be useful, no?

indeed.

>> however, my interest in having the POSIX manpages use portable nroff
>> syntax comes from my endeavor to build a non-bloated musl-based linux
>> system, which will, at least in the basic configuration, feature the
>> below nroff-only manpage viewer, since groff is incredibly bloated (over
>> 4 MB of compressed source code! - in comparison my man.c compiles to a
>> 60 KB statically linked binary) and written in C++ so it's definitely
>> contrary to my goals. (not to talk about that some of the groff features
>> like the tbl preprocessor are just horribly misguided and completely
>> unidiomatic, introducing a completely new language namespace)
>>
>> as such i'd love to see the POSIX manpages project actually deliver
>> portable manpages, instead of assuming that the full-blown GNU userspace
>> stack is available.
>
> Could you give a definition of this portable nroff syntax?

i have a hard time finding detailed specs, but the commands implemented 
by the manviewer are sufficient to display 75% of all manpages on a full 
desktop sabotage linux install with 8000 manpages without a single 
unknown command, despite a lot of packages using their own special 
format. for example anything xorg related uses "XMan", anything 
BSD-related mdoc, and perl manpages use again another set of commands.

so this here seems to represent a very common subset:
	{"\\\"", 0, 0},
	{"nh", 0, 0},		/* This program never inserts hyphens */
	{"hy", 0, 0},		/* This program never inserts hyphens */
	{"PD", 0, 0},		/* Inter-para distance is 1 line */
	{"DT", 0, 0},		/* Default tabs, they can't be non-default! */
	{"IX", 0, 0},		/* Indexing for some weird package */
	{"Id", 0, 0},		/* Line for RCS tokens */
	{"BY", 0, 0},
	{"nf", 0, 1},		/* Line break, Turn line fill off */
	{"fi", 0, 2},		/* Line break, Turn line fill on */
	{"sp", 0, 3},		/* Line break, line space (arg for Nr lines) */
	{"br", 0, 4},		/* Line break */
	{"bp", 0, 5},		/* Page break */
	{"PP", 0, 6},
	{"LP", 0, 6},
	{"P", 0, 6},		/* Paragraph */
	{"RS", 0, 7},		/* New Para + Indent start */
	{"RE", 0, 8},		/* New Para + Indent end */
	{"HP", 0, 9},		/* Begin hanging indent (TP without arg?) */
	{"ad", 0, 10},		/* Line up right margin */
	{"na", 0, 11},		/* Leave right margin unaligned */
	{"ta", 0, 12},		/* Changes _input_ tab spacing, right? */
	{"TH", 1, 1},		/* Title and headers */
	{"SH", 1, 2},		/* Section */
	{"SS", 1, 3},		/* Subsection */
	{"IP", 1, 4},		/* New para, indent except argument 1 */
	{"TP", 1, 5},		/* New para, indent except line 1 */
	{"B", 2, 22},		/* Various font fiddles */
	{"BI", 2, 23},
	{"BR", 2, 21},
	{"I", 2, 33},
	{"IB", 2, 32},
	{"IR", 2, 31},
	{"RB", 2, 12},
	{"RI", 2, 13},
	{"SB", 2, 42},
	{"SM", 2, 44},
	{"C", 2, 22},		/* PH-UX manual pages! */
	{"CI", 2, 23},
	{"CR", 2, 21},
	{"IC", 2, 32},
	{"RC", 2, 12},
	{"so", 3, 0},

>> the alternative is to apply the tbl preprocessor before shipping the
>> manpages and instead include the preprocessed output (cleaned up from
>> groffisms as well)
>
> I'm not sure if your man can handle the output of tbl. Attached is the
> output when run against one of the tables in pax. It looks rather
> hopeless. Also the fictional script cleaning up the GNU tbl output is
> likely going to be dependent on a specific tbl version.
>
> For eqn it seems much more likely to me that one can produce output
> which makes your man implementation happy. The equations are already
> hacked to make them better suitable for nroff.

i agree that the output of tbl is even worse...

btw my research on http://www.troff.org/papers.html revealed that tbl 
and eqn preprocessors existed back in the troff days, so this seems to 
be a historical mistake rather than groff's fault ;)


>
>> as for the other groff specific formatter commands, i am refering to
>> Felix' response: all of them can either be left away or in case of tbl
>> and eqn the preprocessed source used instead.
>
> .ce remained open. Is there an alternative or could you just implement
> that?

yes, that can easily be implemented as a nop on my side, without losing 
valuable information.


--JS
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html