2014/1/24 Ingo Schwarze <[email protected]>: > 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.
Thank you, Ingo. Your input is invaluable. I've reworked the port based on your feedback. I preferred a README instead of posix.7 because it will get noticed at the install time, and with "posix" you'll have a clash with POSIX(3p) from base, too. But I like the idea of being reached via apropos, too, so if someone will have stronger opinion, I'll rework this part. -- WBR, Vadim Zhukov
man-pages-posix_port.tar.gz
Description: GNU Zip compressed data
