Hi Vadim,
Vadim Zhukov wrote on Thu, Jan 23, 2014 at 08:05:36PM +0400:
> The following port installs the POSIX standard as manual pages.
> This could be handy when developing new code.
I agree that a port is useful and /books/ is the right primary
category. However, i object to multiple aspects of what you have done.
Please do not commit this as it is.
Besides, as it stands, the port would need USE_GROFF. There are
many mandoc errors, and i did not yet find the time to investigate
in detail. But one class of errors is clear: The layout of
some tbl(7) code contained therein is not supported by mandoc,
so these tables are missing from mandoc output. USE_GROFF would
be very unfortunate in a port of this kind, and in addition to that,
the license specifically forbids it.
Probably, fixing mandoc to deal with the table layouts won't be
a big deal, but i need to come round to it. I suggest you don't
worry about the tables for now. They will be broken at first, but
i will repair them at some time in the future.
> Due to the fact that we use "p" suffix in category names for Perl, and
> do not have "0" category, I renamed the pages:
>
> 1p => 1u (programs)
> 3p => 3u (API)
> 0p => 7u (headers)
I strongly object to both versions, that is, 1u/3u/7u is about as bad
as 1p/3p/0p. The port is clearly not important enough to warrant
inventing dedicated section numbers, which would entail supporting
them in the tools. Neither mandoc nor groff will support such
categories properly right now.
Do not install these manuals to /usr/local/man/,
but to a dedicated directory, something like
/usr/local/share/doc/posix/man/man{1,3}/*.{1,3}
These are not real manuals documenting real software you can install
and use. They are just a book, a standard. As an analogy,
consider that we do not even install tcl manuals to /usr/local/man/
but to there dedicated, separate tree.
The point is that they must not show up in man(1) unless you
add the path to them to /etc/man.conf, which nobody in their
right mind would ever do. You would use them as follows:
alias poman='man -M /usr/local/share/doc/posix/man'
poman ls
poman chmod
poman 1 chmod
poman 3 chmod
You might be tempted to add
posix /usr/local/share/doc/posix/man/
to /etc/man.conf. But that's of questionable worth. Sure,
now you can say
man -s posix chmod
but now you can no longer select chmod(1) or chmod(3) below -s posix.
Also, 7 seems like the wrong section for headers.
Basically, header file documentation belongs so library
documentation, so i'd suggest putting it into section 3.
Watch out for collisions, though, and fix any you find.
> This probably needs a note about man.conf tweaking, but I'm totally
> lost at wording.
It's not a matter of wording. I think our docs should warn
*against* tweaking man.conf and advertise using -M, preferably
using the alias shown above.
Unfortunately, man.conf(5) is on the one hand bloated and
overengineered, on the other hand feature-imcomplete and clumsy
at the same time. This is biting us in such cases.
I guess i will have to redesign man.conf from scratch one day.
> Given that it's a one line as of now, I've put it in
> MESSAGE rather than in README.
Maybe make this files/posix.7 and install it to /usr/local/man/man7/posix.7?
That way, it would show up in apropos(1), and we could add some
more background information as needed. Of course, a README would be
OK with me, too, if you don't like the posix.7 idea.
> Also, I'm not sure that I got PERMIT_* right.
The relevant part of the POSIX-COPYRIGHT file reads:
Redistribution of this material is permitted so long as this
notice and the corresponding notices within each POSIX manual
page are retained on any distribution, and the nroff source is
included. Modifications to the text are permitted so long as any
conflicts with the standard are clearly marked as such in the
text.
The port can easily comply with that, so i consider
# Custom permissive license, see POSIX-COPYRIGHT
PERMIT_PACKAGE_CDROM = Yes
to be in order.
Yours,
Ingo
