POSIX.1-2013 man pages for review

Hello all,

Recently, the Linux man-pages project received kind permission from the IEEE and The Open Group to distribute the interface specifications from POSIX.1-2013 (also known as POSIX.1-2008 + Technical Corrigendum 1) as a set of manual pages. This allows us to repeat the exercise that was performed in 2004, whereby the POSIX.1-2003 man pages were distributed as man pages for Linux in sections 0p, 1p, and 3p.

Thanks to some work by Felix Janda, we now have a set of scripts that convert the source format that we received from IEEE/TOG to the man pages using the "man" macros. Felix has done some excellent work, and I've spent quite some time reviewing the results. However, before definitively releasing these pages, I would like to have further review of the pages, and I am soliciting that review with this mail

The main purposes of this review are to:
* detect any problems injected by the conversion process (e.g., spurious text added or deleted)
* find any formatting issues with the resulting pages.

If you are interested to help with reviewing these pages, the amount of time required is up to you: it's simply a question of how many (randomly selected) pages you care to check over. Even checking just a half dozen pages is helpful, so long as you let me know how many pages you checked and whether you found problems or whether everything looked okay.

A tarball of the converted pages can be found here:

http://man7.org/linux/posix-man-pages/posix-man-pages-130917-draft.tar.gz

Once you have unpacked the tarball, individual pages can be read using the command

man -l <pagename>

If desired you can compare the pages against the HTML versions of the standard online here:
http://pubs.opengroup.org/onlinepubs/9699919799/

If you would prefer to compare the converted pages against the PFDF version of the standard, I believe it is possible to register (without cost) at The Open Group website:

https://www2.opengroup.org/ogsys/catalog/t101

to obtain a PDF version of the standard.

Thank you,

Michael
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Michael, Felix,

great work, thanks !

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.

[0] https://github.com/rofl0r/hardcore-utils/blob/master/tests/mantest.sh
[1] https://github.com/rofl0r/hardcore-utils/blob/master/man.c

--JS

=== status report ===
total manpages : 1143
buggy manpages : 137
total failures : 406
unique failures : 12

bug list:
122 **** Unknown formatter command: .ne
106 **** Unknown formatter command: .TS
106 **** Unknown formatter command: .TE
24 **** Unknown formatter command: .ce
14 **** Unknown formatter command: .EQ
14 **** Unknown formatter command: .EN
11 **** Unknown formatter command: .nr
3 **** Unknown formatter command: .T&
2 **** Unknown formatter command: .tr
2 **** Unknown formatter command: .in
1 **** Unknown formatter command: .Im

=== detail ===
page total unique
/root/man/man3p/posix_trace_close.3p 3 3
/root/man/man3p/regcomp.3p 2 4
/root/man/man3p/nl_langinfo.3p 1 1
/root/man/man3p/semop.3p 3 3
/root/man/man3p/ilogb.3p 2 2
/root/man/man3p/endutxent.3p 2 2
/root/man/man3p/wctype.3p 2 2
/root/man/man3p/open.3p 1 1
/root/man/man3p/posix_madvise.3p 1 1
/root/man/man3p/semctl.3p 1 1
/root/man/man3p/glob.3p 2 2
/root/man/man3p/freopen.3p 2 2
/root/man/man3p/localeconv.3p 2 4
/root/man/man3p/shmctl.3p 1 1
/root/man/man3p/fopen.3p 2 2
/root/man/man3p/pthread_cond_timedwait.3p 1 1
/root/man/man3p/strftime.3p 2 2
/root/man/man3p/posix_trace_getnext_event.3p 1 1
/root/man/man3p/drand48.3p 3 4
/root/man/man3p/sigaction.3p 3 3
/root/man/man3p/realpath.3p 1 1
/root/man/man3p/posix_spawn_file_actions_addclose.3p 1 1
/root/man/man3p/fma.3p 1 1
/root/man/man3p/fork.3p 1 1
/root/man/man3p/dirname.3p 2 2
/root/man/man3p/msync.3p 2 2
/root/man/man3p/putmsg.3p 1 2
/root/man/man3p/futimens.3p 1 1
/root/man/man3p/getdate.3p 2 4
/root/man/man3p/log1p.3p 1 1
/root/man/man3p/timer_create.3p 1 1
/root/man/man3p/getsockname.3p 1 1
/root/man/man3p/sysconf.3p 2 4
/root/man/man3p/tgamma.3p 1 1
/root/man/man3p/scalbln.3p 1 1
/root/man/man3p/pthread_key_create.3p 1 1
/root/man/man3p/mq_open.3p 1 1
/root/man/man3p/socket.3p 1 1
/root/man/man3p/lgamma.3p 2 2
/root/man/man3p/system.3p 1 1
/root/man/man3p/posix_trace_create.3p 2 8
/root/man/man3p/printf.3p 3 3
/root/man/man3p/sigtimedwait.3p 1 1
/root/man/man3p/getpriority.3p 1 1
/root/man/man3p/chmod.3p 2 4
/root/man/man3p/fwscanf.3p 1 1
/root/man/man3p/pthread_mutex_lock.3p 2 2
/root/man/man3p/sendto.3p 1 2
/root/man/man3p/tzset.3p 2 2
/root/man/man3p/sqrt.3p 2 2
/root/man/man3p/readlink.3p 1 1
/root/man/man3p/fputc.3p 1 1
/root/man/man3p/write.3p 1 1
/root/man/man3p/posix_spawn_file_actions_destroy.3p 1 1
/root/man/man3p/getc_unlocked.3p 1 1
/root/man/man3p/fstatvfs.3p 1 1
/root/man/man3p/gai_strerror.3p 2 2
/root/man/man3p/mmap.3p 3 5
/root/man/man3p/erf.3p 3 3
/root/man/man3p/wordexp.3p 3 3
/root/man/man3p/fdopendir.3p 1 1
/root/man/man3p/msgsnd.3p 1 1
/root/man/man3p/truncate.3p 1 1
/root/man/man3p/mknod.3p 3 5
/root/man/man3p/ioctl.3p 1 2
/root/man/man3p/pthread_mutex_destroy.3p 1 1
/root/man/man3p/fstatat.3p 1 1
/root/man/man3p/fcntl.3p 1 1
/root/man/man3p/getpeername.3p 1 1
/root/man/man3p/sendmsg.3p 1 1
/root/man/man3p/lockf.3p 2 2
/root/man/man3p/fscanf.3p 1 1
/root/man/man3p/atanh.3p 1 1
/root/man/man3p/utime.3p 1 1
/root/man/man3p/tan.3p 1 1
/root/man/man3p/fattach.3p 1 1
/root/man/man3p/fpathconf.3p 3 3
/root/man/man3p/fgetwc.3p 1 1
/root/man/man3p/fwprintf.3p 1 4
/root/man/man1p/write.1p 1 1
/root/man/man1p/sccs.1p 1 1
/root/man/man1p/val.1p 2 2
/root/man/man1p/ctags.1p 1 2
/root/man/man1p/nl.1p 2 2
/root/man/man1p/expr.1p 3 5
/root/man/man1p/pax.1p 7 31
/root/man/man1p/ex.1p 3 10
/root/man/man1p/lex.1p 4 12
/root/man/man1p/ps.1p 4 7
/root/man/man1p/dirname.1p 2 2
/root/man/man1p/touch.1p 2 2
/root/man/man1p/c99.1p 4 13
/root/man/man1p/yacc.1p 4 5
/root/man/man1p/mailx.1p 1 2
/root/man/man1p/dd.1p 2 3
/root/man/man1p/find.1p 1 2
/root/man/man1p/qsub.1p 4 4
/root/man/man1p/awk.1p 4 14
/root/man/man1p/file.1p 4 5
/root/man/man1p/tail.1p 2 2
/root/man/man1p/bc.1p 3 5
/root/man/man1p/gencat.1p 2 2
/root/man/man1p/ed.1p 2 4
/root/man/man1p/get.1p 3 4
/root/man/man1p/tr.1p 2 2
/root/man/man1p/prs.1p 2 2
/root/man/man1p/ls.1p 1 1
/root/man/man1p/printf.1p 3 3
/root/man/man1p/qhold.1p 1 1
/root/man/man1p/chmod.1p 2 4
/root/man/man1p/vi.1p 1 3
/root/man/man1p/od.1p 4 4
/root/man/man1p/stty.1p 4 7
/root/man/man1p/sort.1p 2 2
/root/man/man1p/uuencode.1p 4 4
/root/man/man1p/ar.1p 1 1
/root/man/man1p/sed.1p 1 8
/root/man/man0p/tar.h.0p 2 6
/root/man/man0p/complex.h.0p 2 2
/root/man/man0p/tgmath.h.0p 2 6
/root/man/man0p/cpio.h.0p 2 2
/root/man/man0p/float.h.0p 3 15
/root/man/man0p/langinfo.h.0p 2 2
/root/man/man0p/pthread.h.0p 2 2
/root/man/man0p/fcntl.h.0p 1 1
/root/man/man0p/fmtmsg.h.0p 2 2
/root/man/man0p/inttypes.h.0p 2 8
/root/man/man0p/sys_stat.h.0p 3 3
/root/man/man0p/math.h.0p 2 2
/root/man/man0p/time.h.0p 1 1
/root/man/man0p/termios.h.0p 2 4
/root/man/man0p/signal.h.0p 3 9
/root/man/man0p/netinet_in.h.0p 1 1
/root/man/man0p/unistd.h.0p 1 3
/root/man/man0p/stdint.h.0p 3 3
/root/man/man0p/spawn.h.0p 1 1
/root/man/man0p/stdio.h.0p 1 1

Hi John,

Thanks for taking a look at this.

[...]

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.

Looking at your log:

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?

These two are heavily used for tables in the man-pages project itself. What's the problem/alternative?

.ce Center the next input line.
.ce N Center following N input lines.

Is there an alternative?

These are groff escapes to eqn(1). Is there an alternative?

Not sure about this. Maybe Felix has a comment.

I suspect that this is a macro that should have been converted during the translation. Felix?

groff(7) says:

.tr abcd...
Translate a to b, c to d, etc. on output.

Looks like this one was in the original source. Not sure whether we need to keep it. Felix?

This is heavily used in the man-pages project (albeit little used here). Could be converted to .RS/.RE, I suppose.

Looks to me as though this one should have been fixed in the conversion, but was missed by the script. Felix, could you take a look?

Cheers,

Michael

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Hi all,

My script does not touch these. Seems to be ignored by nroff anyway. So the next version of the script will strip them.

These are added by the script for the table and figure captions. I think it's done the same way in the old posix man pages.

Not many pages make use of eqn. We could maybe let eqn pass over the man pages before publishing them.

Should be stripped.

Appears only in pax in the "Table: Octet-Oriented cpio Archive Entry". Seems to be to have multiple headers in the table. Seems to be standard tbl feature.

Should be stripped.

Appears only in pax. Can be stripped.

This is a bug in the source. I added a patch to fix it, but it was apparently not applied...

Cheers,
Felix
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Hello Michael, Felix,

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.

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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Hello,

On Fri, Sep 20, 2013 at 03:09:03PM +0200, John Spencer wrote:
[..]

Note that posix manpages are not released under a free license.

That is a problem when you want manpages in a free software distribution (like debian, where we can ship manpages{,-dev} by default, but
not manpages-posix{,dev}).

Simon Paillard
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

On the other hand the section 2 man pages from linux-manpages documenting Linux specific behavior of system calls might be useful, no?

Could you give a definition of this portable nroff syntax?

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.

.ce remained open. Is there an alternative or could you just implement that?

Felix

.if !\n(.g .ab GNU tbl requires GNU troff.
.if !dTS .ds TS
.if !dTE .ds TE
.lf 1 pax.1p
.ce 1
\fBTable: Octet-Oriented cpio Archive Entry\fP
.TS
.nr 3c \n(.C
.cp 0
.nr 3lps \n[.s]
.de 3init
.ft \n[.f]
.ps \n[.s]
.vs \n[.v]u
.in \n[.i]u
.ll \n[.l]u
.ls \n[.L]
.ad \n[.j]
.ie \n[.u] .fi
.el .nf
.ce \n[.ce]
..
.nr 3ind \n[.i]
.nr 3fnt \n[.f]
.nr 3sz \n[.s]
.nr 3fll \n[.u]
.nr T. 0
.nr 3crow 0-1
.nr 3passed 0-1
.nr 3sflag 0
.ds 3trans
.ds 3quote
.nr 3brule 1
.nr 3supbot 0
.eo
.de 3rmk
.mk \$1
.if !'\n(.z'' \!.3rmk "\$1"
..
.de 3rvpt
.vpt \$1
.if !'\n(.z'' \!.3rvpt "\$1"
..
.de 3keep
.if '\n[.z]'' \{.ds 3quote \\
.ds 3trans \!
.di 3section
.nr 3sflag 1
.in 0
.\}
..
.de 3release
.if \n[3sflag] \{.di
.in \n[3ind]u
.nr 3dn \n[dn]
.ds 3quote
.ds 3trans
.nr 3sflag 0
.if \n[.t]<=\n[dn] \{.nr T. 1
.T#
.nr 3supbot 1
.sp \n[.t]u
.nr 3supbot 0
.mk #T
.\}
.if \n[.t]<=\n[3dn] .tm warning: page \n%: table text block will not fit on one page
.nf
.ls 1
.3section
.ls
.rm 3section
.\}
..
.nr 3tflag 0
.de 3tkeep
.if '\n[.z]'' \{.di 3table
.nr 3tflag 1
.\}
..
.de 3trelease
.if \n[3tflag] \{.br
.di
.nr 3dn \n[dn]
.ne \n[dn]u+\n[.V]u
.ie \n[.t]<=\n[3dn] .tm error: page \n%: table will not fit on one page; use .TS H/.TH with a supporting macro package
.el \{.in 0
.ls 1
.nf
.3table
.\}
.rm 3table
.\}
..
.ec
.ce 0
.nf
.nr 3sep 1n
.nr 3w0 \n(.H
.nr 3aw0 0
.nr 3lnw0 0
.nr 3rnw0 0
.nr 3w1 \n(.H
.nr 3aw1 0
.nr 3lnw1 0
.nr 3rnw1 0
.nr 3w2 \n(.H
.nr 3aw2 0
.nr 3lnw2 0
.nr 3rnw2 0
.lf 7 pax.1p
.nr 3w0 \n[3w0]>?\w\[tbl]\f[B]Header Field Name\f[\n[3fnt]]\[tbl]
.lf 7
.nr 3w1 \n[3w1]>?\w\[tbl]\f[B]Length (in Octets)\f[\n[3fnt]]\[tbl]
.lf 7
.nr 3w2 \n[3w2]>?\w\[tbl]\f[B]Interpreted as\f[\n[3fnt]]\[tbl]
.lf 9
.nr 3w0 \n[3w0]>?\w\[tbl]\f[I]c_magic\f[\n[3fnt]]\[tbl]
.lf 9
.nr 3tbw1,1 0\w\[tbl]6\[tbl]
.nr 3lnw1 \n[3lnw1]>?\n[3tbw1,1]
.lf 9
.nr 3w2 \n[3w2]>?\w\[tbl]Octal number\[tbl]
.lf 10
.nr 3w0 \n[3w0]>?\w\[tbl]\f[I]c_dev\f[\n[3fnt]]\[tbl]
.lf 10
.nr 3tbw2,1 0\w\[tbl]6\[tbl]
.nr 3lnw1 \n[3lnw1]>?\n[3tbw2,1]
.lf 10
.nr 3w2 \n[3w2]>?\w\[tbl]Octal number\[tbl]
.lf 11
.nr 3w0 \n[3w0]>?\w\[tbl]\f[I]c_ino\f[\n[3fnt]]\[tbl]
.lf 11
.nr 3tbw3,1 0\w\[tbl]6\[tbl]
.nr 3lnw1 \n[3lnw1]>?\n[3tbw3,1]
.lf 11
.nr 3w2 \n[3w2]>?\w\[tbl]Octal number\[tbl]
.lf 12
.nr 3w0 \n[3w0]>?\w\[tbl]\f[I]c_mode\f[\n[3fnt]]\[tbl]
.lf 12
.nr 3tbw4,1 0\w\[tbl]6\[tbl]
.nr 3lnw1 \n[3lnw1]>?\n[3tbw4,1]
.lf 12
.nr 3w2 \n[3w2]>?\w\[tbl]Octal number\[tbl]
.lf 13
.nr 3w0 \n[3w0]>?\w\[tbl]\f[I]c_uid\f[\n[3fnt]]\[tbl]
.lf 13
.nr 3tbw5,1 0\w\[tbl]6\[tbl]
.nr 3lnw1 \n[3lnw1]>?\n[3tbw5,1]
.lf 13
.nr 3w2 \n[3w2]>?\w\[tbl]Octal number\[tbl]
.lf 14
.nr 3w0 \n[3w0]>?\w\[tbl]\f[I]c_gid\f[\n[3fnt]]\[tbl]
.lf 14
.nr 3tbw6,1 0\w\[tbl]6\[tbl]
.nr 3lnw1 \n[3lnw1]>?\n[3tbw6,1]
.lf 14
.nr 3w2 \n[3w2]>?\w\[tbl]Octal number\[tbl]
.lf 15
.nr 3w0 \n[3w0]>?\w\[tbl]\f[I]c_nlink\f[\n[3fnt]]\[tbl]
.lf 15
.nr 3tbw7,1 0\w\[tbl]6\[tbl]
.nr 3lnw1 \n[3lnw1]>?\n[3tbw7,1]
.lf 15
.nr 3w2 \n[3w2]>?\w\[tbl]Octal number\[tbl]
.lf 16
.nr 3w0 \n[3w0]>?\w\[tbl]\f[I]c_rdev\f[\n[3fnt]]\[tbl]
.lf 16
.nr 3tbw8,1 0\w\[tbl]6\[tbl]
.nr 3lnw1 \n[3lnw1]>?\n[3tbw8,1]
.lf 16
.nr 3w2 \n[3w2]>?\w\[tbl]Octal number\[tbl]
.lf 17
.nr 3w0 \n[3w0]>?\w\[tbl]\f[I]c_mtime\f[\n[3fnt]]\[tbl]
.lf 17
.nr 3tbw9,1 0\w\[tbl]11\[tbl]
.nr 3lnw1 \n[3lnw1]>?\n[3tbw9,1]
.lf 17
.nr 3w2 \n[3w2]>?\w\[tbl]Octal number\[tbl]
.lf 18
.nr 3w0 \n[3w0]>?\w\[tbl]\f[I]c_namesize\f[\n[3fnt]]\[tbl]
.lf 18
.nr 3tbw10,1 0\w\[tbl]6\[tbl]
.nr 3lnw1 \n[3lnw1]>?\n[3tbw10,1]
.lf 18
.nr 3w2 \n[3w2]>?\w\[tbl]Octal number\[tbl]
.lf 19
.nr 3w0 \n[3w0]>?\w\[tbl]\f[I]c_filesize\f[\n[3fnt]]\[tbl]
.lf 19
.nr 3tbw11,1 0\w\[tbl]11\[tbl]
.nr 3lnw1 \n[3lnw1]>?\n[3tbw11,1]
.lf 19
.nr 3w2 \n[3w2]>?\w\[tbl]Octal number\[tbl]
.lf 24
.nr 3w0 \n[3w0]>?\w\[tbl]\f[B]Filename Field Name\f[\n[3fnt]]\[tbl]
.lf 24
.nr 3w1 \n[3w1]>?\w\[tbl]\f[B]Length\f[\n[3fnt]]\[tbl]
.lf 24
.nr 3w2 \n[3w2]>?\w\[tbl]\f[B]Interpreted as\f[\n[3fnt]]\[tbl]
.lf 26
.nr 3w0 \n[3w0]>?\w\[tbl]\f[I]c_name\f[\n[3fnt]]\[tbl]
.lf 26
.nr 3w1 \n[3w1]>?\w\[tbl]\f[I]c_namesize\f[\n[3fnt]]\[tbl]
.lf 26
.nr 3w2 \n[3w2]>?\w\[tbl]Pathname string\[tbl]
.lf 31
.nr 3w0 \n[3w0]>?\w\[tbl]\f[B]File Data Field Name\f[\n[3fnt]]\[tbl]
.lf 31
.nr 3w1 \n[3w1]>?\w\[tbl]\f[B]Length\f[\n[3fnt]]\[tbl]
.lf 31
.nr 3w2 \n[3w2]>?\w\[tbl]\f[B]Interpreted as\f[\n[3fnt]]\[tbl]
.lf 33
.nr 3w0 \n[3w0]>?\w\[tbl]\f[I]c_filedata\f[\n[3fnt]]\[tbl]
.lf 33
.nr 3w1 \n[3w1]>?\w\[tbl]\f[I]c_filesize\f[\n[3fnt]]\[tbl]
.lf 33
.nr 3w2 \n[3w2]>?\w\[tbl]Data\[tbl]
.nr 3w0 \n[3w0]>?(\n[3lnw0]+\n[3rnw0])
.if \n[3aw0] .nr 3w0 \n[3w0]>?(\n[3aw0]+2n)
.nr 3w1 \n[3w1]>?(\n[3lnw1]+\n[3rnw1])
.if \n[3aw1] .nr 3w1 \n[3w1]>?(\n[3aw1]+2n)
.nr 3w2 \n[3w2]>?(\n[3lnw2]+\n[3rnw2])
.if \n[3aw2] .nr 3w2 \n[3w2]>?(\n[3aw2]+2n)
.nr 3expand \n[.l]-\n[.i]-\n[3w0]-\n[3w1]-\n[3w2]-8n
.if \n[3expand]<0 \{.lf 7
.tm1 "warning: file `\n[.F]', around line \n[.c]:
.tm1 " table wider than line width
.nr 3expand 0
.\}
.nr 3cd0 0
.nr 3cl0 1*\n[3sep]
.nr 3ce0 \n[3cl0]+\n[3w0]
.nr 3cl1 \n[3ce0]+(3*\n[3sep])
.nr 3cd1 \n[3ce0]+\n[3cl1]/2
.nr 3ce1 \n[3cl1]+\n[3w1]
.nr 3cl2 \n[3ce1]+(3*\n[3sep])
.nr 3cd2 \n[3ce1]+\n[3cl2]/2
.nr 3ce2 \n[3cl2]+\n[3w2]
.nr 3cd3 \n[3ce2]+(1*\n[3sep])
.nr TW \n[3cd3]
.in +(u;\n[.l]-\n[.i]-\n[TW]/2>?-\n[.i])
.nr 3ind \n[.i]
.eo
.de T#
.if !\n[3supbot] \{.3rvpt 0
.mk 3vert
.if \n[T.]&\n[3brule] \{.vs 2p>?\n[.V]u
.ls 1
\v'.25m'\s[\n[3lps]]\h'|\n[3cd0]u'\D'l |\n[3cd3]u 0'\s0
.ls
.vs
.\}
.ls 1
.if \n[3crow]>=14&(\n[3crow]<14) \{.if 14<=\n[3passed] .nr 3rt14 \n[#T]
.sp -1
\v'.25m'\h'\n[3cd2]u'\s[\n[3lps]]\D'l 0 |\n[3rt14]u-1v'\s0
.\}
.if \n[3crow]>=14&(\n[3crow]<14) \{.if 14<=\n[3passed] .nr 3rt14 \n[#T]
.sp -1
\v'.25m'\h'\n[3cd1]u'\s[\n[3lps]]\D'l 0 |\n[3rt14]u-1v'\s0
.\}
.if \n[3crow]>=0&(\n[3crow]<12) \{.if 0<=\n[3passed] .nr 3rt0 \n[#T]
.sp -1
\v'.25m'\h'\n[3cd2]u'\s[\n[3lps]]\D'l 0 |\n[3rt0]u-1v'\s0
.\}
.if \n[3crow]>=0&(\n[3crow]<12) \{.if 0<=\n[3passed] .nr 3rt0 \n[#T]
.sp -1
\v'.25m'\h'\n[3cd1]u'\s[\n[3lps]]\D'l 0 |\n[3rt0]u-1v'\s0
.\}
.if \n[3crow]>=0 \{.if 0<=\n[3passed] .nr 3rt0 \n[#T]
.sp -1
\v'.25m'\h'\n[3cd3]u'\s[\n[3lps]]\D'l 0 |\n[3rt0]u-1v'\s0
.\}
.if \n[3crow]>=0 \{.if 0<=\n[3passed] .nr 3rt0 \n[#T]
.sp -1
\v'.25m'\h'\n[3cd0]u'\s[\n[3lps]]\D'l 0 |\n[3rt0]u-1v'\s0
.\}
.ls
.nr 3passed \n[3crow]
.sp |\n[3vert]u
.3rvpt 1
.\}
..
.ec
.fc 
.3tkeep
.vs 2p>?\n[.V]u
.ls 1
\v'.25m'\s[\n[3lps]]\h'|\n[3cd0]u'\D'l |\n[3cd3]u 0'\s0
.ls
.vs
.3keep
.3rmk 3rt0
\*[3trans].nr 3crow 0
.3keep
.mk 3rs0
.mk 3bot
.3rvpt 0
.ta \n[3ce0]u \n[3ce1]u \n[3ce2]u
.lf 7
\&\h'|\n[3cl0]u'\f[B]Header Field Name\f[\n[3fnt]]\h'|\n[3cl1]u'\f[B]Length (in Octets)\f[\n[3fnt]]\h'|\n[3cl2]u'\f[B]Interpreted as\f[\n[3fnt]] .nr 3bot \n[3bot]>?\n[.d]
.sp |\n[3rs0]u
.3rvpt 1
.sp |\n[3bot]u
\*[3trans].nr 3brule 1
.vs 2p>?\n[.V]u
.ls 1
\v'.25m'\s[\n[3lps]]\h'|\n[3cd0]u'\D'l |\n[3cd3]u 0'\s0
.ls
.vs
\*[3trans].nr 3brule 0
.3release
.3keep
.3rmk 3rt1
\*[3trans].nr 3crow 1
.3keep
.mk 3rs1
.mk 3bot
.3rvpt 0
.ta \n[3ce0]u \n[3ce2]u
.lf 9 \&\h'|\n[3cl0]u'\f[I]c_magic\f[\n[3fnt]]\h'|(\n[3w1]u-\n[3lnw1]u-\n[3rnw1]u/2u+\n[3lnw1]u+\n[3cl1]u-\n[3tbw1,1]u)'6\h'|\n[3cl2]u'Octal number .nr 3bot \n[3bot]>?\n[.d]
.sp |\n[3rs1]u
.3rvpt 1
.sp |\n[3bot]u
\*[3trans].nr 3brule 1
.3release
.3keep
.3rmk 3rt2
\*[3trans].nr 3crow 2
.3keep
.mk 3rs2
.mk 3bot
.3rvpt 0
.ta \n[3ce0]u \n[3ce2]u
.lf 10 \&\h'|\n[3cl0]u'\f[I]c_dev\f[\n[3fnt]]\h'|(\n[3w1]u-\n[3lnw1]u-\n[3rnw1]u/2u+\n[3lnw1]u+\n[3cl1]u-\n[3tbw2,1]u)'6\h'|\n[3cl2]u'Octal number .nr 3bot \n[3bot]>?\n[.d]
.sp |\n[3rs2]u
.3rvpt 1
.sp |\n[3bot]u
\*[3trans].nr 3brule 1
.3release
.3keep
.3rmk 3rt3
\*[3trans].nr 3crow 3
.3keep
.mk 3rs3
.mk 3bot
.3rvpt 0
.ta \n[3ce0]u \n[3ce2]u
.lf 11 \&\h'|\n[3cl0]u'\f[I]c_ino\f[\n[3fnt]]\h'|(\n[3w1]u-\n[3lnw1]u-\n[3rnw1]u/2u+\n[3lnw1]u+\n[3cl1]u-\n[3tbw3,1]u)'6\h'|\n[3cl2]u'Octal number .nr 3bot \n[3bot]>?\n[.d]
.sp |\n[3rs3]u
.3rvpt 1
.sp |\n[3bot]u
\*[3trans].nr 3brule 1
.3release
.3keep
.3rmk 3rt4
\*[3trans].nr 3crow 4
.3keep
.mk 3rs4
.mk 3bot
.3rvpt 0
.ta \n[3ce0]u \n[3ce2]u
.lf 12 \&\h'|\n[3cl0]u'\f[I]c_mode\f[\n[3fnt]]\h'|(\n[3w1]u-\n[3lnw1]u-\n[3rnw1]u/2u+\n[3lnw1]u+\n[3cl1]u-\n[3tbw4,1]u)'6\h'|\n[3cl2]u'Octal number .nr 3bot \n[3bot]>?\n[.d]
.sp |\n[3rs4]u
.3rvpt 1
.sp |\n[3bot]u
\*[3trans].nr 3brule 1
.3release
.3keep
.3rmk 3rt5
\*[3trans].nr 3crow 5
.3keep
.mk 3rs5
.mk 3bot
.3rvpt 0
.ta \n[3ce0]u \n[3ce2]u
.lf 13 \&\h'|\n[3cl0]u'\f[I]c_uid\f[\n[3fnt]]\h'|(\n[3w1]u-\n[3lnw1]u-\n[3rnw1]u/2u+\n[3lnw1]u+\n[3cl1]u-\n[3tbw5,1]u)'6\h'|\n[3cl2]u'Octal number .nr 3bot \n[3bot]>?\n[.d]
.sp |\n[3rs5]u
.3rvpt 1
.sp |\n[3bot]u
\*[3trans].nr 3brule 1
.3release
.3keep
.3rmk 3rt6
\*[3trans].nr 3crow 6
.3keep
.mk 3rs6
.mk 3bot
.3rvpt 0
.ta \n[3ce0]u \n[3ce2]u
.lf 14 \&\h'|\n[3cl0]u'\f[I]c_gid\f[\n[3fnt]]\h'|(\n[3w1]u-\n[3lnw1]u-\n[3rnw1]u/2u+\n[3lnw1]u+\n[3cl1]u-\n[3tbw6,1]u)'6\h'|\n[3cl2]u'Octal number .nr 3bot \n[3bot]>?\n[.d]
.sp |\n[3rs6]u
.3rvpt 1
.sp |\n[3bot]u
\*[3trans].nr 3brule 1
.3release
.3keep
.3rmk 3rt7
\*[3trans].nr 3crow 7
.3keep
.mk 3rs7
.mk 3bot
.3rvpt 0
.ta \n[3ce0]u \n[3ce2]u
.lf 15 \&\h'|\n[3cl0]u'\f[I]c_nlink\f[\n[3fnt]]\h'|(\n[3w1]u-\n[3lnw1]u-\n[3rnw1]u/2u+\n[3lnw1]u+\n[3cl1]u-\n[3tbw7,1]u)'6\h'|\n[3cl2]u'Octal number .nr 3bot \n[3bot]>?\n[.d]
.sp |\n[3rs7]u
.3rvpt 1
.sp |\n[3bot]u
\*[3trans].nr 3brule 1
.3release
.3keep
.3rmk 3rt8
\*[3trans].nr 3crow 8
.3keep
.mk 3rs8
.mk 3bot
.3rvpt 0
.ta \n[3ce0]u \n[3ce2]u
.lf 16 \&\h'|\n[3cl0]u'\f[I]c_rdev\f[\n[3fnt]]\h'|(\n[3w1]u-\n[3lnw1]u-\n[3rnw1]u/2u+\n[3lnw1]u+\n[3cl1]u-\n[3tbw8,1]u)'6\h'|\n[3cl2]u'Octal number .nr 3bot \n[3bot]>?\n[.d]
.sp |\n[3rs8]u
.3rvpt 1
.sp |\n[3bot]u
\*[3trans].nr 3brule 1
.3release
.3keep
.3rmk 3rt9
\*[3trans].nr 3crow 9
.3keep
.mk 3rs9
.mk 3bot
.3rvpt 0
.ta \n[3ce0]u \n[3ce2]u
.lf 17 \&\h'|\n[3cl0]u'\f[I]c_mtime\f[\n[3fnt]]\h'|(\n[3w1]u-\n[3lnw1]u-\n[3rnw1]u/2u+\n[3lnw1]u+\n[3cl1]u-\n[3tbw9,1]u)'11\h'|\n[3cl2]u'Octal number .nr 3bot \n[3bot]>?\n[.d]
.sp |\n[3rs9]u
.3rvpt 1
.sp |\n[3bot]u
\*[3trans].nr 3brule 1
.3release
.3keep
.3rmk 3rt10
\*[3trans].nr 3crow 10
.3keep
.mk 3rs10
.mk 3bot
.3rvpt 0
.ta \n[3ce0]u \n[3ce2]u
.lf 18 \&\h'|\n[3cl0]u'\f[I]c_namesize\f[\n[3fnt]]\h'|(\n[3w1]u-\n[3lnw1]u-\n[3rnw1]u/2u+\n[3lnw1]u+\n[3cl1]u-\n[3tbw10,1]u)'6\h'|\n[3cl2]u'Octal number .nr 3bot \n[3bot]>?\n[.d]
.sp |\n[3rs10]u
.3rvpt 1
.sp |\n[3bot]u
\*[3trans].nr 3brule 1
.3release
.3keep
.3rmk 3rt11
\*[3trans].nr 3crow 11
.3keep
.mk 3rs11
.mk 3bot
.3rvpt 0
.ta \n[3ce0]u \n[3ce2]u
.lf 19 \&\h'|\n[3cl0]u'\f[I]c_filesize\f[\n[3fnt]]\h'|(\n[3w1]u-\n[3lnw1]u-\n[3rnw1]u/2u+\n[3lnw1]u+\n[3cl1]u-\n[3tbw11,1]u)'11\h'|\n[3cl2]u'Octal number .nr 3bot \n[3bot]>?\n[.d]
.sp |\n[3rs11]u
.3rvpt 1
.sp |\n[3bot]u
\*[3trans].nr 3brule 1
.vs 2p>?\n[.V]u
.ls 1
\v'.25m'\s[\n[3lps]]\h'|\n[3cd0]u'\D'l |\n[3cd3]u 0'\s0
.ls
.vs
\*[3trans].nr 3brule 0
.3release
.3keep
.3rmk 3rt12
.cp \n(3c
.lf 21
.T&
.cp 0
\*[3trans].nr 3crow 12
.3keep
.mk 3rs12
.mk 3bot
.3rvpt 0
.ta \n[3ce0]u \n[3ce1]u \n[3ce2]u
.lf 24 pax.1p
\&\h'|\n[3cl0]u'\f[B]Filename Field Name\f[\n[3fnt]]\h'|\n[3cl1]u'\f[B]Length\f[\n[3fnt]]\h'|\n[3cl2]u'\f[B]Interpreted as\f[\n[3fnt]] .nr 3bot \n[3bot]>?\n[.d]
.sp |\n[3rs12]u
.3rvpt 1
.sp |\n[3bot]u
\*[3trans].nr 3brule 1
.vs 2p>?\n[.V]u
.ls 1
\v'.25m'\s[\n[3lps]]\h'|\n[3cd0]u'\D'l |\n[3cd3]u 0'\s0
.ls
.vs
\*[3trans].nr 3brule 0
.3rvpt 0
\*[3trans].if 0<=\*[3quote]\n[3passed] .nr 3rt0 \*[3quote]\n[#T]
\*[3trans].sp -1
\*[3trans]\v'.25m'\h'\n[3cd2]u'\s[\n[3lps]]\D'l 0 |\*[3quote]\n[3rt0]u-1v'\s0
\*[3trans].if 0<=\*[3quote]\n[3passed] .nr 3rt0 \*[3quote]\n[#T]
\*[3trans].sp -1
\*[3trans]\v'.25m'\h'\n[3cd1]u'\s[\n[3lps]]\D'l 0 |\*[3quote]\n[3rt0]u-1v'\s0
.3rvpt 1
.3release
.3keep
.3rmk 3rt13
\*[3trans].nr 3crow 13
.3keep
.mk 3rs13
.mk 3bot
.3rvpt 0
.ta \n[3ce0]u \n[3ce1]u \n[3ce2]u
.lf 26
\&\h'|\n[3cl0]u'\f[I]c_name\f[\n[3fnt]]\h'|\n[3cl1]u'\f[I]c_namesize\f[\n[3fnt]]\h'|\n[3cl2]u'Pathname string
.nr 3bot \n[3bot]>?\n[.d]
.sp |\n[3rs13]u
.3rvpt 1
.sp |\n[3bot]u
\*[3trans].nr 3brule 1
.vs 2p>?\n[.V]u
.ls 1
\v'.25m'\s[\n[3lps]]\h'|\n[3cd0]u'\D'l |\n[3cd3]u 0'\s0
.ls
.vs
\*[3trans].nr 3brule 0
.3release
.3keep
.3rmk 3rt14
.cp \n(3c
.lf 28
.T&
.cp 0
\*[3trans].nr 3crow 14
.3keep
.mk 3rs14
.mk 3bot
.3rvpt 0
.ta \n[3ce0]u \n[3ce1]u \n[3ce2]u
.lf 31 pax.1p
\&\h'|\n[3cl0]u'\f[B]File Data Field Name\f[\n[3fnt]]\h'|\n[3cl1]u'\f[B]Length\f[\n[3fnt]]\h'|\n[3cl2]u'\f[B]Interpreted as\f[\n[3fnt]] .nr 3bot \n[3bot]>?\n[.d]
.sp |\n[3rs14]u
.3rvpt 1
.sp |\n[3bot]u
\*[3trans].nr 3brule 1
.vs 2p>?\n[.V]u
.ls 1
\v'.25m'\s[\n[3lps]]\h'|\n[3cd0]u'\D'l |\n[3cd3]u 0'\s0
.ls
.vs
\*[3trans].nr 3brule 0
.3rvpt 0
\*[3trans].if 14<=\*[3quote]\n[3passed] .nr 3rt14 \*[3quote]\n[#T]
\*[3trans].sp -1
\*[3trans]\v'.25m'\h'\n[3cd2]u'\s[\n[3lps]]\D'l 0 |\*[3quote]\n[3rt14]u-1v'\s0
\*[3trans].if 14<=\*[3quote]\n[3passed] .nr 3rt14 \*[3quote]\n[#T]
\*[3trans].sp -1
\*[3trans]\v'.25m'\h'\n[3cd1]u'\s[\n[3lps]]\D'l 0 |\*[3quote]\n[3rt14]u-1v'\s0
.3rvpt 1
.3release
.3keep
.3rmk 3rt15
\*[3trans].nr 3crow 15
.3keep
.mk 3rs15
.mk 3bot
.3rvpt 0
.ta \n[3ce0]u \n[3ce1]u \n[3ce2]u
.lf 33
\&\h'|\n[3cl0]u'\f[I]c_filedata\f[\n[3fnt]]\h'|\n[3cl1]u'\f[I]c_filesize\f[\n[3fnt]]\h'|\n[3cl2]u'Data
.nr 3bot \n[3bot]>?\n[.d]
.sp |\n[3rs15]u
.3rvpt 1
.sp |\n[3bot]u
\*[3trans].nr 3brule 1
.3release
.mk 3rt16
.nr 3brule 1
.nr T. 1
.T#
.3trelease
.3init
.fc
.cp \n(3c
.lf 34
.TE

indeed.

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},

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 ;)

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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

John Spencer wrote:
[...]

Ok, but that seems a bit arbitrary.

How about escape sequences?

For eqn it looks similar. I think I identified the interesting part of its output, but it still contains a lot of escape sequences. There are just not that many pages using eqn (i.e. 8) to make me write an eqn preprocessor with acceptable nroff output.

You might also be interested in

http://plan9.bell-labs.com/7thEdMan/index.html

(In order to claim that .T& is classical I checked the original tbl manual.)

Good.

Felix
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

they're supported, yes.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

...

Eric Raymond's doclifter project was a python script that parsed man pages to produce docbook output. There's more horrible domain-specific knowledge encoded into that than you can possibly imagine, you might want to poke [email protected] to see if he wants to comment on your thing.

Rob--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html