Re: POSIX standard as manual pages
2014-07-06 8:21 GMT+04:00, Anthony J. Bentley : > Hi Vadim, > > Vadim Zhukov writes: >> As usual, I totally forgot to send updated port version. Here it is. >> >> Okay to import? > > From PLIST: > > share/doc/posix/man-pages-posix-2013-a.tar.xz > > Is that really necessary? Otherwise, ok bentley@ Yes, that's a license restriction: we patch manual pages in package and thus have to provide unmodified version. Thank you for review! -- WBR, Vadim Zhukov
Re: POSIX standard as manual pages
Hi Vadim, Vadim Zhukov writes: > As usual, I totally forgot to send updated port version. Here it is. > > Okay to import? >From PLIST: share/doc/posix/man-pages-posix-2013-a.tar.xz Is that really necessary? Otherwise, ok bentley@ -- Anthony J. Bentley
Re: POSIX standard as manual pages
2014-05-09 19:18 GMT+04:00, Vadim Zhukov :
> 09.05.2014 17:17 пользователь "Ingo Schwarze" написал:
>>
>> Hi Dmitrij and Vadim,
>>
>> Vadim Zhukov wrote on Fri, May 09, 2014 at 11:57:28AM +0400:
>> > 09.05.2014 2:03 "Dmitrij D. Czarkoff" :
>>
>> >> Why not shorten "man-pages-posix" to just "posix"?
>>
>> That's what i originally suggested, too:
>>
>> From: Ingo Schwarze
>> Date: Fri, 24 Jan 2014 00:45:56 +0100
>> To: Vadim Zhukov
>> Cc: ports@openbsd.org
>> Subject: Re: POSIX standard as manual pages
>> [...]
>> 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}
>>
>> One advantage is that if any other POSIX documentation should ever
>> show up in ports, it could go into share/doc/posix, too.
>> There is no danger of clashes, posix/man is quite clear,
>> man-pages-posix/man somewhat redundant.
>>
>> > It's upstream name, FWIW.
>>
>> The argument that a port should follow upstream's name (unless it is
>> very badly chosen) and that most subdirectories of /usr/local/share/doc/
>> follow the respective ports' names is a valid one.
>>
>> > I won't mind to change actual folder if there will be a real reason.
>> > You won't go to this folder directly anyway, will you?
>>
>> I already have your port installed because it is useful for me
>> when doing work regarding POSIX conformance and when doing work
>> regarding HISTORY sections. I already cd'ed into that directory
>> several times, mostly to do multiple consecutive grep -R commands.
>> Given that all this is still man(7), not mdoc(7), the new apropos
>> is not yet very helpful, so searching still needs to be done the
>> old way.
>
> This is a good point, thank you for input. The packages are for people, not
> the other direction. So if people use this directory, err, directly, then
> it's better to have an exception. I'll rename the folder when I'll get my
> laptop back to normal operation.
>
>> Then again, i don't feel strongly either way, both paths seem
>> acceptable to me. It's your port, and you are more used to ports
>> naming conventions, so you should decide this detail, i think.
As usual, I totally forgot to send updated port version. Here it is.
Okay to import?
--
WBR,
Vadim Zhukov
man-pages-posix_port.tar.gz
Description: GNU Zip compressed data
Re: POSIX standard as manual pages
09.05.2014 21:18 пользователь "Matthew Dempsky"
написал:
>
> Just curious, are the older POSIX standards available as man pages
> too? Is there a way to install them side-by-side?
>
> I'm by far most interested in the current up-to-date standard, but
> being able to easily cross-reference older revisions is sometimes
> handy. (E.g., when trying to make sure we're still compliant with
> older standards.)
There is one more release from the same project, from 2003 year, IIRC. I do
not know about any other successful POSIX-as-a-man projects; feel free to
point me at those, and I'll prepare ports for them, too.
> On Fri, May 9, 2014 at 8:18 AM, Vadim Zhukov wrote:
> > 09.05.2014 17:17 пользователь "Ingo Schwarze"
написал:
> >>
> >> Hi Dmitrij and Vadim,
> >>
> >> Vadim Zhukov wrote on Fri, May 09, 2014 at 11:57:28AM +0400:
> >> > 09.05.2014 2:03 "Dmitrij D. Czarkoff" :
> >>
> >> >> Why not shorten "man-pages-posix" to just "posix"?
> >>
> >> That's what i originally suggested, too:
> >>
> >> From: Ingo Schwarze
> >> Date: Fri, 24 Jan 2014 00:45:56 +0100
> >> To: Vadim Zhukov
> >> Cc: ports@openbsd.org
> >> Subject: Re: POSIX standard as manual pages
> >> [...]
> >> 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}
> >>
> >> One advantage is that if any other POSIX documentation should ever
> >> show up in ports, it could go into share/doc/posix, too.
> >> There is no danger of clashes, posix/man is quite clear,
> >> man-pages-posix/man somewhat redundant.
> >>
> >> > It's upstream name, FWIW.
> >>
> >> The argument that a port should follow upstream's name (unless it is
> >> very badly chosen) and that most subdirectories of
/usr/local/share/doc/
> >> follow the respective ports' names is a valid one.
> >>
> >> > I won't mind to change actual folder if there will be a real reason.
> >> > You won't go to this folder directly anyway, will you?
> >>
> >> I already have your port installed because it is useful for me
> >> when doing work regarding POSIX conformance and when doing work
> >> regarding HISTORY sections. I already cd'ed into that directory
> >> several times, mostly to do multiple consecutive grep -R commands.
> >> Given that all this is still man(7), not mdoc(7), the new apropos
> >> is not yet very helpful, so searching still needs to be done the
> >> old way.
> >
> > This is a good point, thank you for input. The packages are for people,
not
> > the other direction. So if people use this directory, err, directly,
then
> > it's better to have an exception. I'll rename the folder when I'll get
my
> > laptop back to normal operation.
> >
> >> Then again, i don't feel strongly either way, both paths seem
> >> acceptable to me. It's your port, and you are more used to ports
> >> naming conventions, so you should decide this detail, i think.
> >>
> >> Yours,
> >> Ingo
> >>
Re: POSIX standard as manual pages
Just curious, are the older POSIX standards available as man pages
too? Is there a way to install them side-by-side?
I'm by far most interested in the current up-to-date standard, but
being able to easily cross-reference older revisions is sometimes
handy. (E.g., when trying to make sure we're still compliant with
older standards.)
On Fri, May 9, 2014 at 8:18 AM, Vadim Zhukov wrote:
> 09.05.2014 17:17 пользователь "Ingo Schwarze" написал:
>>
>> Hi Dmitrij and Vadim,
>>
>> Vadim Zhukov wrote on Fri, May 09, 2014 at 11:57:28AM +0400:
>> > 09.05.2014 2:03 "Dmitrij D. Czarkoff" :
>>
>> >> Why not shorten "man-pages-posix" to just "posix"?
>>
>> That's what i originally suggested, too:
>>
>> From: Ingo Schwarze
>> Date: Fri, 24 Jan 2014 00:45:56 +0100
>> To: Vadim Zhukov
>> Cc: ports@openbsd.org
>> Subject: Re: POSIX standard as manual pages
>> [...]
>> 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}
>>
>> One advantage is that if any other POSIX documentation should ever
>> show up in ports, it could go into share/doc/posix, too.
>> There is no danger of clashes, posix/man is quite clear,
>> man-pages-posix/man somewhat redundant.
>>
>> > It's upstream name, FWIW.
>>
>> The argument that a port should follow upstream's name (unless it is
>> very badly chosen) and that most subdirectories of /usr/local/share/doc/
>> follow the respective ports' names is a valid one.
>>
>> > I won't mind to change actual folder if there will be a real reason.
>> > You won't go to this folder directly anyway, will you?
>>
>> I already have your port installed because it is useful for me
>> when doing work regarding POSIX conformance and when doing work
>> regarding HISTORY sections. I already cd'ed into that directory
>> several times, mostly to do multiple consecutive grep -R commands.
>> Given that all this is still man(7), not mdoc(7), the new apropos
>> is not yet very helpful, so searching still needs to be done the
>> old way.
>
> This is a good point, thank you for input. The packages are for people, not
> the other direction. So if people use this directory, err, directly, then
> it's better to have an exception. I'll rename the folder when I'll get my
> laptop back to normal operation.
>
>> Then again, i don't feel strongly either way, both paths seem
>> acceptable to me. It's your port, and you are more used to ports
>> naming conventions, so you should decide this detail, i think.
>>
>> Yours,
>> Ingo
>>
Re: POSIX standard as manual pages
09.05.2014 17:17 пользователь "Ingo Schwarze" написал:
>
> Hi Dmitrij and Vadim,
>
> Vadim Zhukov wrote on Fri, May 09, 2014 at 11:57:28AM +0400:
> > 09.05.2014 2:03 "Dmitrij D. Czarkoff" :
>
> >> Why not shorten "man-pages-posix" to just "posix"?
>
> That's what i originally suggested, too:
>
> From: Ingo Schwarze
> Date: Fri, 24 Jan 2014 00:45:56 +0100
> To: Vadim Zhukov
> Cc: ports@openbsd.org
> Subject: Re: POSIX standard as manual pages
> [...]
> 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}
>
> One advantage is that if any other POSIX documentation should ever
> show up in ports, it could go into share/doc/posix, too.
> There is no danger of clashes, posix/man is quite clear,
> man-pages-posix/man somewhat redundant.
>
> > It's upstream name, FWIW.
>
> The argument that a port should follow upstream's name (unless it is
> very badly chosen) and that most subdirectories of /usr/local/share/doc/
> follow the respective ports' names is a valid one.
>
> > I won't mind to change actual folder if there will be a real reason.
> > You won't go to this folder directly anyway, will you?
>
> I already have your port installed because it is useful for me
> when doing work regarding POSIX conformance and when doing work
> regarding HISTORY sections. I already cd'ed into that directory
> several times, mostly to do multiple consecutive grep -R commands.
> Given that all this is still man(7), not mdoc(7), the new apropos
> is not yet very helpful, so searching still needs to be done the
> old way.
This is a good point, thank you for input. The packages are for people, not
the other direction. So if people use this directory, err, directly, then
it's better to have an exception. I'll rename the folder when I'll get my
laptop back to normal operation.
> Then again, i don't feel strongly either way, both paths seem
> acceptable to me. It's your port, and you are more used to ports
> naming conventions, so you should decide this detail, i think.
>
> Yours,
> Ingo
>
Re: POSIX standard as manual pages
Hi Dmitrij and Vadim,
Vadim Zhukov wrote on Fri, May 09, 2014 at 11:57:28AM +0400:
> 09.05.2014 2:03 "Dmitrij D. Czarkoff" :
>> Why not shorten "man-pages-posix" to just "posix"?
That's what i originally suggested, too:
From: Ingo Schwarze
Date: Fri, 24 Jan 2014 00:45:56 +0100
To: Vadim Zhukov
Cc: ports@openbsd.org
Subject: Re: POSIX standard as manual pages
[...]
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}
One advantage is that if any other POSIX documentation should ever
show up in ports, it could go into share/doc/posix, too.
There is no danger of clashes, posix/man is quite clear,
man-pages-posix/man somewhat redundant.
> It's upstream name, FWIW.
The argument that a port should follow upstream's name (unless it is
very badly chosen) and that most subdirectories of /usr/local/share/doc/
follow the respective ports' names is a valid one.
> I won't mind to change actual folder if there will be a real reason.
> You won't go to this folder directly anyway, will you?
I already have your port installed because it is useful for me
when doing work regarding POSIX conformance and when doing work
regarding HISTORY sections. I already cd'ed into that directory
several times, mostly to do multiple consecutive grep -R commands.
Given that all this is still man(7), not mdoc(7), the new apropos
is not yet very helpful, so searching still needs to be done the
old way.
Then again, i don't feel strongly either way, both paths seem
acceptable to me. It's your port, and you are more used to ports
naming conventions, so you should decide this detail, i think.
Yours,
Ingo
Re: POSIX standard as manual pages
09.05.2014 2:03 пользователь "Dmitrij D. Czarkoff"
написал:
>
> Ingo Schwarze said:
> > Looking again, i think it is better to shorten this to
> >
> > share/doc/man-pages-posix/man{1,3}/*.{1,3}
>
> Why not shorten "man-pages-posix" to just "posix"?
It's upstream name, FWIW. I won't mind to change actual folder if there
will be a real reason. You won't go to this folder directly anyway, will
you?
Re: POSIX standard as manual pages
Ingo Schwarze said:
> Looking again, i think it is better to shorten this to
>
> share/doc/man-pages-posix/man{1,3}/*.{1,3}
Why not shorten "man-pages-posix" to just "posix"?
--
Dmitrij D. Czarkoff
Re: POSIX standard as manual pages
Hi Vadim,
Vadim Zhukov wrote on Thu, May 08, 2014 at 12:56:58AM +0400:
> All other nits were fixed, and here is an updated port.
ok schwarze@
If you want, wrap the line after "${DOCDIR}," in pkg/README
before commit, then the installed file
/usr/local/share/doc/pkg-readmes/man-pages-posix-2013a
will look better because ${DOCDIR} is quite long when expanded.
Yours,
Ingo
Re: POSIX standard as manual pages
2014-05-07 22:05 GMT+04:00, Ingo Schwarze : > Hi Vadim, > > Vadim Zhukov wrote on Wed, May 07, 2014 at 09:49:39PM +0400: >> 07.05.2014 21:29 Ingo Schwarze: > >>> Really, you must remove USE_GROFF from the Makefile, even though >>> that will break some of the pages. The license plainly doesn't >>> allow distributing the manuals without distributing the source. > >> Hm-m-m, we could just distribute packaged source files somewhere under >> /usr/local/share, can't we? IMHO, it's better to fill disk a bit more >> than to provide incorrect info. > > It's not incorrect info, it's just imcomplete info, and it affects > only a few pages using tbl(7). At some point, i will fix our tbl(7) > implementation in mandoc(1), and the problem will go away without > even the need to bump the port. > > Sure, you can install two copies of everything. I wouldn't strongly > object to that, but does it really make things better? > > You could also go without USE_GROFF and additionally install the > cat versions just for those pages containing tbl(7) code mandoc > doesn't handle yet, making sure that the time stamps of the cat files > are newer than those of the man files, such that man(1) selects the > cat versions where available. But that's quite some work to set up > correctly, and it will become obsolete once tbl(7) is fixed. > > Three possibilities - so much choice... :-) > > I guess ultimately, it's your call. I was lazy, thus I just added the tarball. :) The "/man/" could not be stripped from paths, or USE_GROFF and makewhatis magic won't work. All other nits were fixed, and here is an updated port. -- WBR, Vadim Zhukov man-pages-posix_port.tar.gz Description: GNU Zip compressed data
Re: POSIX standard as manual pages
Hi Vadim, Vadim Zhukov wrote on Wed, May 07, 2014 at 09:49:39PM +0400: > 07.05.2014 21:29 Ingo Schwarze: >> Really, you must remove USE_GROFF from the Makefile, even though >> that will break some of the pages. The license plainly doesn't >> allow distributing the manuals without distributing the source. > Hm-m-m, we could just distribute packaged source files somewhere under > /usr/local/share, can't we? IMHO, it's better to fill disk a bit more > than to provide incorrect info. It's not incorrect info, it's just imcomplete info, and it affects only a few pages using tbl(7). At some point, i will fix our tbl(7) implementation in mandoc(1), and the problem will go away without even the need to bump the port. Sure, you can install two copies of everything. I wouldn't strongly object to that, but does it really make things better? You could also go without USE_GROFF and additionally install the cat versions just for those pages containing tbl(7) code mandoc doesn't handle yet, making sure that the time stamps of the cat files are newer than those of the man files, such that man(1) selects the cat versions where available. But that's quite some work to set up correctly, and it will become obsolete once tbl(7) is fixed. Three possibilities - so much choice... :-) I guess ultimately, it's your call. Yours, Ingo
Re: POSIX standard as manual pages
07.05.2014 21:29 пользователь "Ingo Schwarze" написал:
>
> Hi Vadim,
>
> as it stands, the port is still not OK, but you are coming closer.
>
> Vadim Zhukov wrote on Sun, May 04, 2014 at 02:05:51PM +0400:
> > "Vadim Zhukov" :
> >> 2014/1/24 Ingo Schwarze :
>
> >>> USE_GROFF would be very unfortunate in a port of this kind,
> >>> and in addition to that, the license specifically forbids it.
>
> Really, you must remove USE_GROFF from the Makefile, even though
> that will break some of the pages. The license plainly doesn't
> allow distributing the manuals without distributing the source.
Hm-m-m, we could just distribute packaged source files somewhere under
/usr/local/share, can't we? IMHO, it's better to fill disk a bit more than
to provide incorrect info.
> >>> 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.
>
> That said, i think the comment
>
> # permissive, see POSIX-COPYRIGHT
>
> in the Makefile is misleading. The term "permissive" is normally
> used for BSD-style licenses, but this one is more like GPL.
> Make something like:
>
> # custom copyleft license, see POSIX-COPYRIGHT
Agree, will be fixed.
> [...]
> >>> 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}
>
> You have chosen:
>
> share/doc/man-pages-posix/man/man{1,3}/*.{1,3}
>
> Looking again, i think it is better to shorten this to
>
> share/doc/man-pages-posix/man{1,3}/*.{1,3}
Nice idea, thanks. Will be changed.
> [...]
> >>> Of course, a README would be OK with me, too.
>
> The README needs a few improvements:
>
> * I don't like the reasoning in the first sentence, i think it
>misses the point. Maybe something like:
>"Because the manuals contained in this package do not match
> any real software installed, they are not installed into
> directories that man(1) searches by default."
>
> * "You're promised" in the second sentence is not correct English.
>You might say:
>"Consider adding something like this..."
>
> * The final note should also be reworded, this is not specific
>to OpenBSD at all. Maybe like this:
>"Because manual page handling tools do not support section 0,
> header documentation is installed into section 3."
>
> There are also some issues with the DESCR:
>
> * The string "POSIX 1003.1-2013" is imprecise. You should say:
>"This package contains the IEEE Std 1003.1-2008 (POSIX.1)
> manual pages including the corrections contained in
> the first Technical Corrigendum, IEEE Std 1003.1-2008/Cor 1-2013."
>
> * The directories in the second sentence are wrong, and i don't
>see the point in listing them at all. Maybe:
>"It include manuals for utilities in section 1 and for functions
> and headers in section 3."
>
> So far, that's all from visual inspection. I think this needs
> another iteration before it makes sense to start with actual testing.
Got it.
> Thanks for working on this,
Thank you for reviewing. I'll send you updated port as it'll be ready.
Re: POSIX standard as manual pages
Hi Vadim,
as it stands, the port is still not OK, but you are coming closer.
Vadim Zhukov wrote on Sun, May 04, 2014 at 02:05:51PM +0400:
> "Vadim Zhukov" :
>> 2014/1/24 Ingo Schwarze :
>>> USE_GROFF would be very unfortunate in a port of this kind,
>>> and in addition to that, the license specifically forbids it.
Really, you must remove USE_GROFF from the Makefile, even though
that will break some of the pages. The license plainly doesn't
allow distributing the manuals without distributing the source.
>>> 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.
That said, i think the comment
# permissive, see POSIX-COPYRIGHT
in the Makefile is misleading. The term "permissive" is normally
used for BSD-style licenses, but this one is more like GPL.
Make something like:
# custom copyleft license, see POSIX-COPYRIGHT
[...]
>>> 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}
You have chosen:
share/doc/man-pages-posix/man/man{1,3}/*.{1,3}
Looking again, i think it is better to shorten this to
share/doc/man-pages-posix/man{1,3}/*.{1,3}
[...]
>>> Of course, a README would be OK with me, too.
The README needs a few improvements:
* I don't like the reasoning in the first sentence, i think it
misses the point. Maybe something like:
"Because the manuals contained in this package do not match
any real software installed, they are not installed into
directories that man(1) searches by default."
* "You're promised" in the second sentence is not correct English.
You might say:
"Consider adding something like this..."
* The final note should also be reworded, this is not specific
to OpenBSD at all. Maybe like this:
"Because manual page handling tools do not support section 0,
header documentation is installed into section 3."
There are also some issues with the DESCR:
* The string "POSIX 1003.1-2013" is imprecise. You should say:
"This package contains the IEEE Std 1003.1-2008 (POSIX.1)
manual pages including the corrections contained in
the first Technical Corrigendum, IEEE Std 1003.1-2008/Cor 1-2013."
* The directories in the second sentence are wrong, and i don't
see the point in listing them at all. Maybe:
"It include manuals for utilities in section 1 and for functions
and headers in section 3."
So far, that's all from visual inspection. I think this needs
another iteration before it makes sense to start with actual testing.
Thanks for working on this,
Ingo
Re: POSIX standard as manual pages
24.01.2014 17:27 пользователь "Vadim Zhukov" написал:
>
> 2014/1/24 Ingo Schwarze :
> > 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
Re: POSIX standard as manual pages
2014/1/24 Ingo Schwarze :
> 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
Re: POSIX standard as manual pages
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
Re: POSIX standard as manual pages
On Thu, 23 Jan 2014 21:33:18 +0400 Vadim Zhukov wrote: > I don't see that this restriction applies to the given package. See the > man-pages-posix-2013-a.Announce and POSIX-COPYRIGHT files in WRKSRC. There > was a policy like that some time ago with documentation published online, > but it's gone, unless I'm mistaken. Fair enough my only reference was that the site seems to ask you to on the website when you go to download it but maybe that explains why the submit didn't work rather than being a problem with the website or webkit-gtk.
Re: POSIX standard as manual pages
23.01.2014 20:19 пользователь "Kevin Chadwick" написал: > > previously on this list Vadim Zhukov contributed: > > > The following port installs the POSIX standard as manual pages. This > > could be handy when developing new code. > > Should the port mention the site wanting those that download the specs > to submit their email and perhaps they should if they use the port? > > Though when I tried with xombrero, the site let me download but didn't > let me submit my email anyway. I don't see that this restriction applies to the given package. See the man-pages-posix-2013-a.Announce and POSIX-COPYRIGHT files in WRKSRC. There was a policy like that some time ago with documentation published online, but it's gone, unless I'm mistaken. ___ > > 'Write programs that do one thing and do it well. Write programs to work > together. Write programs to handle text streams, because that is a > universal interface' > > (Doug McIlroy) > > In Other Words - Don't design like polkit or systemd > ___ >
Re: POSIX standard as manual pages
previously on this list Vadim Zhukov contributed: > The following port installs the POSIX standard as manual pages. This > could be handy when developing new code. Should the port mention the site wanting those that download the specs to submit their email and perhaps they should if they use the port? Though when I tried with xombrero, the site let me download but didn't let me submit my email anyway. -- ___ 'Write programs that do one thing and do it well. Write programs to work together. Write programs to handle text streams, because that is a universal interface' (Doug McIlroy) In Other Words - Don't design like polkit or systemd ___
POSIX standard as manual pages
The following port installs the POSIX standard as manual pages. This could be handy when developing new code. 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) This probably needs a note about man.conf tweaking, but I'm totally lost at wording. Given that it's a one line as of now, I've put it in MESSAGE rather than in README. Also, I'm not sure that I got PERMIT_* right. -- WBR, Vadim Zhukov man-pages-posix-2013_port.tar.gz Description: GNU Zip compressed data
