headers
David Holland | 1 Jun 2010 07:11
Picon

Re: NAME_MAX usage not consistent across man pages

On Sun, May 23, 2010 at 11:01:16PM +0200, Nicolas Joly wrote:
 > While looking to some man pages, i noticed that NAME_MAX define usage
 > is not consistent ... Some of them use it enclosed with braces, and
 > some others do not; and there is 3 variants for setting braces :
 > 
 > njoly <at> petaure [share/man]> find man* -type f -name '*.[1-9]' | xargs grep -h '[^_A-Z]NAME_MAX' | sort |
uniq -c
 >    5 .Brq Dv NAME_MAX
 >    2 .Brq Dv NAME_MAX .
 >   14 .Dv NAME_MAX
 >    4 .Dv NAME_MAX .
 >    3 .Dv { NAME_MAX }
 >   30 .Dv {NAME_MAX}
 > 
 > To be consistent across all pages, we should use a single expression
 > in all pages. I'm for using the `.Brq Dv NAME_MAX' one, which add the
 > braces (without spaces, following the opengroup man pages) using a
 > mdoc macro.
 > 
 > Comments ?

Why do we want the braces? And if we do, why is this particular symbol
different from all other uses of Dv?

I'd go with just .Dv NAME_MAX.

--

-- 
David A. Holland
dholland <at> netbsd.org
(Continue reading)

Permalink | Reply | 1 comment |
headers
Nicolas Joly | 1 Jun 2010 09:53
Picon
Picon
Favicon

Re: NAME_MAX usage not consistent across man pages

On Tue, Jun 01, 2010 at 05:11:54AM +0000, David Holland wrote:
> On Sun, May 23, 2010 at 11:01:16PM +0200, Nicolas Joly wrote:
>  > While looking to some man pages, i noticed that NAME_MAX define usage
>  > is not consistent ... Some of them use it enclosed with braces, and
>  > some others do not; and there is 3 variants for setting braces :
>  > 
>  > njoly <at> petaure [share/man]> find man* -type f -name '*.[1-9]' | xargs grep -h '[^_A-Z]NAME_MAX' | sort |
uniq -c
>  >    5 .Brq Dv NAME_MAX
>  >    2 .Brq Dv NAME_MAX .
>  >   14 .Dv NAME_MAX
>  >    4 .Dv NAME_MAX .
>  >    3 .Dv { NAME_MAX }
>  >   30 .Dv {NAME_MAX}
>  > 
>  > To be consistent across all pages, we should use a single expression
>  > in all pages. I'm for using the `.Brq Dv NAME_MAX' one, which add the
>  > braces (without spaces, following the opengroup man pages) using a
>  > mdoc macro.
>  > 
>  > Comments ?
> 
> Why do we want the braces? And if we do, why is this particular symbol
> different from all other uses of Dv?

Actually, AFAIK, in the syscalls man pages we do not refers strictly
to the globally defined XXX_MAX value; but rather to a symbolic name
which value may differs depending on the underlying
filesystem... value which can be retrieved with statvfs(2) or
pathconf(2).
(Continue reading)

Permalink | Reply | 0 comments |
headers
Jukka Ruohonen | 30 Jun 2010 14:52
Picon
Picon
Favicon

Splitting large pages to smaller ones

Hello.

Any opinions about splitting large manual pages to several smaller ones?

I recall a debate about this some time ago, but can't recall the resolution
(if any). Examples where this might apply: kauth(9), ukfs(9), fileassoc(9),
and uvm(9).

Few points:

	1. The manual page format lends itself badly to anything bigger than
	   three or four pages. This is especially evident when a page is
	   viewed from a terminal and the content is mostly discussion
	   around function prototypes. $PAGER has also poor search
	   capabilities, etc.

	2. I have personally tried to follow a format where there is a
	   single introductory page with references to the actual functions
	   and other technical details. In my opinion this works well. And
	   of course this format appears also in some older pages; take
	   stdio(3) as an example. It is also the format used by the
	   standard committees such as the Open Group (POSIX).

	3. If pages are small, it is possible to follow the standard manual
	   page format; function prototypes appear in the synopsis and not
	   in the body of the text, etc. This should also ensure that proper
	   links are build for the functions (in the big pages it is a rule
	   rather than an exception that some links are missing).

I am inclined to think that (1) is supported by some human (pedagogical?)
(Continue reading)

Permalink | Reply | 2 comments |
headers
Thomas Klausner | 1 Jul 2010 00:41
Picon

Re: Splitting large pages to smaller ones

On Wed, Jun 30, 2010 at 03:52:10PM +0300, Jukka Ruohonen wrote:
> Any opinions about splitting large manual pages to several smaller ones?

Good idea! As long as there are overview man pages that teach you
where to start looking.
 Thomas
Permalink | Reply | 0 comments |

Gmane