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