Date: Sun, 1 Aug 1999 07:30:12 -0500 (CDT) From: Mike Pritchard <mpp@mpp.pro-ns.net> To: bde@zeta.org.au (Bruce Evans) Cc: bde@FreeBSD.org, cvs-all@FreeBSD.org, cvs-committers@FreeBSD.org Subject: Re: cvs commit: src/lib/libc/sys utimes.2 Message-ID: <199908011230.HAA02229@mpp.pro-ns.net> In-Reply-To: <199908011144.VAA29846@godzilla.zeta.org.au> from Bruce Evans at "Aug 1, 1999 09:44:48 pm"
next in thread | previous in thread | raw e-mail | index | archive | help
> >> Removed POSIX.1/NetBSD markup (braces) for NAME_MAX, etc. We don't
> >> define this. Most FreeBSD man pages hard-code the limits; in fact,
> >> utimes.2 recently became the only file in libc/sys/*.2 that mentions
> >> NAME_MAX. There probably should be mandoc macros for this.
>
> >What kind of mdoc macros did you have in mind? .Dv is how these should
> >be specified with mdoc currently, but I'm open to suggestions.
>
> I'd like one which looked up XXX_MAX somewhere (probably in the macro
> file) and expanded to XXX_MAX, its implementation defined value, and some
> connecting text. Can mdoc handle this? If not, there could be more
> specialised macros for at least PATH_MAX and NAME_MAX. In *.2, there
> are 46 references to 1023 (PATH_MAX or MAXPATHLEN - 1), 6 references to
> 1024 (PATH_MAX) and 49 references to 255 (NAME_MAX). NAME_MAX shouldn't
> actually be defined, since it is fs-dependent. OTOH, POSIX.1 uses
> {NAME_MAX} as an abreviation for "NAME_MAX if that is defined, else the
> fs-dependent value given by pathconf(path, _PC_NAME_MAX) or fpathconf()
> where `path' is ...". The macro should handle some of this.
>
> Bruce
With what whe currently have, no, we can't do it.
It should be possible to do what you are asking with some changes to
mdoc, grofff and "make buildworld". Off the top of my head, buildworld
would create a mdoc symbol file in /usr/share/man. Then we would
add a new mdoc macro, say, .Iv (included variable0. When groff
runs across this macro (which would boil down to some new groff
directive, too), it would parse the symbol file. If there is only one
definition, it would substitute the specified value, otherwise
it would still list it by its defined name.
We could probably use .Dv to do this, but we would see so many
if these.
...returns the value NULL (0) on failure.
For those man pages that have ambigious variable refernces, the
text should be expanded to state exactly which header file they
are obtaining their definitions from.
For things like NAME_MAX, the man page text should reflect that the
value specified is for the default (UFS, probably) filesystem,
but that other filesystems may be different values.
I really like this idea. I hate the idea of having to touch groff :-(.
But, it would be nice for man pages to print something like this:
[ENAMETOOLONG]
A componnent of a patch name exeeded NAME_MAX (255) characters, or an
entire path name exceeded PATH_MAX (1024)-1 characters.
Old documentation like this would then also need a line like:
NAME_MAX is filesysten dependent. NAME_MAX (255) is the default for UFS
filesystems.
Or maybe we need a new man page that documents these types of things,
E.g. man 7 sysdefaults,
Any changes along these lines makes our man pages incompatible with the
other *BSDs.
-Mike
--
Mike Pritchard
mpp@FreeBSD.ORG or mpp@mpp.pro-ns.net
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe cvs-all" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?199908011230.HAA02229>