Hello Michael, Felix,
On 09/19/2013 01:00 PM, Michael Kerrisk (man-pages) wrote:
i've run a test script[0] using my own manpage viewer[1]
and attached the results. it seems that ~10% of the manpages use some
special groff features. i'd rather see these removed/replaced with something
nroff-compatible.
I just want to check where you're coming from John. You're working on
musl, right? Does musl not use the work from the man-pages project? I
ask, because some of the pieces that your script doesn't like are also
used in the man-pages project. See below.
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.
i can't remember the exact outcome of the previous discussion on the
musl mailing list, ("Linux manpages (was Re: [musl] Request for
volunteers)"), but afaik it is unlikely that the man-pages project will
be updated as discussed in that thread before musl 1.0 is out.
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.
[0] https://github.com/rofl0r/hardcore-utils/blob/master/tests/mantest.sh
[1] https://github.com/rofl0r/hardcore-utils/blob/master/man.c
Looking at your log:
=== status report ===
total manpages : 1143
buggy manpages : 137
total failures : 406
unique failures : 12
bug list:
122 **** Unknown formatter command: .ne
Not sure about this one. From groff(7):
.ne Need a one-line vertical space.
.ne N Need N vertical space (default scaling indicator v).
I'm not sure about the circumstances where these are being applied. Felix?
106 **** Unknown formatter command: .TS
106 **** Unknown formatter command: .TE
These two are heavily used for tables in the man-pages project itself.
What's the problem/alternative?
the problem is A) that it requires groff's tbl preprocessor, which in
turn requires the full groff install, and B) that the tag cannot simply
be ignored becaused the content embedded into those tags follows a
completely random new syntax - example:
http://www.podgrid.org/linux-bible/linux-bible-page607.html
the alternative is to apply the tbl preprocessor before shipping the
manpages and instead include the preprocessed output (cleaned up from
groffisms as well)
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.
Thanks,
--JS
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
