POSIX.1-2013 man pages for review

POSIX.1-2013 man pages for review

[Michael Kerrisk (man-pages)]

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: POSIX.1-2013 man pages for review

[John Spencer]

[-- Attachment #1: Type: text/plain, Size: 1097 bytes --]

Michael, Felix,

On 09/19/2013 09:59 AM, Michael Kerrisk (man-pages) wrote:
>
> 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

great work, thanks !


> 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.


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

[-- Attachment #2: man.log --]
[-- Type: text/x-log, Size: 4917 bytes --]

=== 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

Re: POSIX.1-2013 man pages for review

[Michael Kerrisk (man-pages)]

Hi John,

Thanks for taking a look at this.

[...]

>> 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.
>
>
>
> 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.

> [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?

>      24 **** Unknown formatter command: .ce

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

Is there an alternative?

>      14 **** Unknown formatter command: .EQ
>      14 **** Unknown formatter command: .EN

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

>      11 **** Unknown formatter command: .nr

Not sure about this. Maybe Felix has a comment.

>       3 **** Unknown formatter command: .T&

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

>       2 **** Unknown formatter command: .tr

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?

>       2 **** Unknown formatter command: .in

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

>       1 **** Unknown formatter command: .Im

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: POSIX.1-2013 man pages for review

[Felix Janda]

Hi all,

Michael Kerrisk (man-pages) wrote:
> Hi John,
> 
> Thanks for taking a look at this.
> 
> [...]
> 
> >> 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.
> >
> >
> >
> > 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.
> 
> > [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?

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

> >     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?
>
> >      24 **** Unknown formatter command: .ce
> 
>        .ce       Center the next input line.
>        .ce N     Center following N input lines.
> 
> Is there an alternative?

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.

> >      14 **** Unknown formatter command: .EQ
> >      14 **** Unknown formatter command: .EN
> 
> These are groff escapes to eqn(1). Is there an alternative?

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

> >      11 **** Unknown formatter command: .nr
> 
> Not sure about this. Maybe Felix has a comment.

Should be stripped.

> >       3 **** Unknown formatter command: .T&
> 
> I suspect that this is a macro that should have been converted during
> the translation. Felix?

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.

> >       2 **** Unknown formatter command: .tr
> 
> 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?

Should be stripped.

> >       2 **** Unknown formatter command: .in
> 
> This is heavily used in the man-pages project (albeit little used
> here). Could be converted to .RS/.RE, I suppose.

Appears only in pax. Can be stripped.

> >       1 **** Unknown formatter command: .Im
> 
> 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?

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: POSIX.1-2013 man pages for review

[John Spencer]

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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: POSIX.1-2013 man pages for review

[Simon Paillard]

Hello,

On Fri, Sep 20, 2013 at 03:09:03PM +0200, 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.

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: POSIX.1-2013 man pages for review

[Felix Janda]

[-- Attachment #1: Type: text/plain, Size: 4286 bytes --]

John Spencer wrote:
> 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.

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

> 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.

Could you give a definition of this portable nroff syntax?

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

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.

> 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?

Felix

[-- Attachment #2: pax.1p --]
[-- Type: text/plain, Size: 13908 bytes --]

.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 \x02\x03
.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'\x02\x03\f[B]Header Field Name\f[\n[3fnt]]\x03\x02\h'|\n[3cl1]u'\x02\x03\f[B]Length (in Octets)\f[\n[3fnt]]\x03\x02\h'|\n[3cl2]u'\x02\x03\f[B]Interpreted as\f[\n[3fnt]]\x03\x02
.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'\x02\x03\f[B]Filename Field Name\f[\n[3fnt]]\x03\x02\h'|\n[3cl1]u'\x02\x03\f[B]Length\f[\n[3fnt]]\x03\x02\h'|\n[3cl2]u'\x02\x03\f[B]Interpreted as\f[\n[3fnt]]\x03\x02
.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'\x02\x03\f[B]File Data Field Name\f[\n[3fnt]]\x03\x02\h'|\n[3cl1]u'\x02\x03\f[B]Length\f[\n[3fnt]]\x03\x02\h'|\n[3cl2]u'\x02\x03\f[B]Interpreted as\f[\n[3fnt]]\x03\x02
.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

Re: POSIX.1-2013 man pages for review

[John Spencer]

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

Re: POSIX.1-2013 man pages for review

[Felix Janda]

John Spencer wrote:
[...]
> >> 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},

Ok, but that seems a bit arbitrary.

How about escape sequences?

> >> 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...

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.

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

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

> >> 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.

Good.

Felix
--
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

Re: POSIX.1-2013 man pages for review

[John Spencer]

On 09/22/2013 09:25 PM, Felix Janda wrote:
>
> How about escape sequences?
>

they're supported, yes.
--
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

Re: POSIX.1-2013 man pages for review

[Rob Landley]

On 09/21/2013 07:20:22 AM, John Spencer wrote:
> On 09/20/2013 07:54 PM, Felix Janda wrote:
>> John Spencer wrote:
...
>> 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 ;)

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 esr-4uCgticg2UFBDgjK7y7TUQ@public.gmane.org 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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: POSIX.1-2013 man pages for review

[Xose Vazquez Perez]

On 09/19/2013 Michael Kerrisk wrote:

> 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.

Is there any news on that ?
--
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

Re: POSIX.1-2013 man pages for review

[Michael Kerrisk (man-pages)]

On 12/10/13 06:58, Xose Vazquez Perez wrote:
> On 09/19/2013 Michael Kerrisk wrote:
> 
>> 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.
> 
> Is there any news on that ?
> 

We're nearly there. There were some unforeseen delays.

Cheers,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
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