kww@cbosgd.UUCP (03/03/87)
First of all, let me apologize for posting NON-SOURCE to net.sources, but
the news group "net.sources.d" has seemed to disappeared, at least on cbosgd.
Also, please don't consider this a "flame", but rather a useful tidbit of
information. Frankly, I'm little surprised I haven't seen others "flame"
this on the "net" before.
When posting sources to net.sources, mod.sources, etc., please do NOT use
the suffix .l (i.e., the lowercase letter L) for the names of manual pages.
This suffix is "reserved" for LEX files ("reserved" as in "conventional"),
and also quite often breaks makefiles.
The accepted notation is to name manual pages with the basename of the
program and the suffix being the section in the manual in which the said
manual page is supposed to be placed, adding an optional lowercase L (i.e.,
a 'l') to the suffix, if it is a "local" command. However the manual section
portion of the suffix should ALWAYS (by convention) appear. For example,
if we have a program called "prog", then the following file names
are used by convention:
File name Meaning
---------- ---------------------------
prog.1 Standard (non-local) command called "prog".
prog.1l Local command called "prog".
Note, that ``prog.l'' is not an accepted file name, and would normally be
intrepreted as a LEX source file. The reason that this may cause further
confusion is because incompletely specified makefiles (i.e., those relying
on many of the usual built-in rules to "make") can cause unintended results.
Consider for a moment the short makefile, given below. (Patterned after a
real, but greatly simplified example. The program name has been changed to
the generic "prog" to protect the original poster [and myself :-] from flames.)
##### Begin example makefile: prog.mk
SRCS = prog.c
PROG = prog
# Note "incorrect"--v--suffix name. Should be "prog.1".
MANPG = prog.l
all: $(PROG)
@echo Everything has been made!
##### End example makefile: prog.mk
Let's further suppose that the makefile was called "prog.mk", the C source
file called "prog.c", and the manual page source (i.e., [nt]roff source) is
called "prog.l" (<-- Note that's .l, NOT the CORRECT .1 !!!), and everything
is packed together into a shell archive.
If the shell acrhive was packaged in such a way that the .c file has an
OLDER modification date than the manual page source, running "make" with
this supplied makefile will cause make to try to rebuild the .c file from
the .l file using its built-in rules, since "make" thinks that .l files
are LEX source. Thus if you would run
make -nf prog.mk
you would see:
lex prog.l
mv lex.yy.c prog.c
cc -O prog.c -o prog
echo Everything has been made!
If you run "make" withOUT the "-n" flag, LEX will most assuredly barf because
of a syntax error. (I have yet to see a LEX source that will run as a manual
page, and vice-versa, and no, I am NOT looking for one!)
Also, if the .c file happens to be NEWER than the .l file, you would only see:
cc -O prog.c -o prog
echo Everything has been made!
But you have disaster waiting around the corner as soon as you edit the
manual page.
Now, maybe the BSD 4.x versions of "make" don't behave this way; I don't know
because I haven't tried this. But the System V versions of "make" do
interpret '.l' suffixes to be LEX source code. And over the past month or
so I have retrieved a dozen or so sources who manual pages that were
named '.l' instead of the accepted '.1' or '.1l' (which is what I prefer)
and whose makefiles I've had to edit, and whose manual page files I've had
to rename.
Possibly I'm naive enough to believe that the reason that people put manual
pages in '.l' files is due to ignorance. If so, consider yourself educated.
(Or possibly you don't have real 1's on your keyboards???)
But the bottom line is, PLEASE NO MORE '.l' manual pages. Thanks!!!
I am directing all followups to this article to "comp.unix.wizards", to which I
have cross-posted.
In person: Kevin W. Wall U.S.Snail: Room 0B-115
USENET/E-mail: {ihnp4|cbosgd!}ncpe!kww AT&T Bell Laboratories
DDD: (614) 860-4775 6200 E. Broad St.
Cornet: 8-353-4775 Columbus, Oh. 43213
--
In person: Kevin W. Wall U.S.Snail: Room 0B-115
USENET/E-mail: {ihnp4|cbosgd!}ncpe!kww AT&T Bell Laboratories
DDD: (614) 860-4775 6200 E. Broad St.
Cornet: 8-353-4775 Columbus, Oh. 43213wohler@sri-spam.UUCP (03/03/87)
In article <3403@cbosgd.ATT.COM> kww@cbosgd.UUCP (Kevin W. Wall) writes: >When posting sources to net.sources, mod.sources, etc., please do NOT use >the suffix .l (i.e., the lowercase letter L) for the names of manual pages. >This suffix is "reserved" for LEX files ("reserved" as in "conventional"), >and also quite often breaks makefiles. ... > File name Meaning > ---------- --------------------------- > prog.1 Standard (non-local) command called "prog". > prog.1l Local command called "prog". kevin, even 4.xBSD make interprets the '.l' suffix as a file that contains lex source. another "standard" which makes life easier (ever see Sun's tmac.an file?) is to just append the '.1' suffix to ANY section one command, whether it be local (l), new (n), or whatever IN THE SOURCE. then, have your "make install" portion of the makefile copy the man page to the desired location in /usr/man with the correct suffix. for instance: ----- MAN = foo.1 MANDIR = /usr/man/man MANSECT = n install: cp ${MAN} ${MANDIR}n/`basename ${MAN} .1`.${MANSECT} ----- when distributing source, don't make any assumptions about where people might like to put your sources (ie. with man page file names like foo.1l). let the Makefile contain that information. --bw
decot@hpisod2.UUCP (03/05/87)
Nor should one post LISP sources named *.l with a collection that includes a makefile, for similar reasons. Dave Decot hpda!decot
rbj@icst-cmr.arpa (Root Boy Jim) (03/06/87)
All you people out there are missing the completely obvious!!! We put all our nonstandard manual sections in /usr/man/man9!!! Works great! Just type man 9 foo. Trivial hacks to man and catman will search section 9 by default. Of course, you can't put both foo.1 and foo.5 into section 9, but then there's always section zero! More involved hacks would allow ANY numeric manual section. Why not? (Root Boy) Jim "Just Say Yes" Cottrell <rbj@icst-cmr.arpa> Why did Paul Simon name his album after Elvis Presley's house?
roy@phri.UUCP (Roy Smith) (03/08/87)
In article <4762@brl-adm.ARPA> rbj@icst-cmr.arpa (Root Boy Jim) writes: > We put all our nonstandard manual sections in /usr/man/man9!!! > [...] Of course, you can't put both foo.1 and foo.5 into section 9 I never did understand why you had to have the suffix on the file name match the last character of the man sub-directory. When we upgraded from 4.2 to 4.3, we had a hell of a time tracking down *all* the local stuff and made a decision that as much as possible we were going to put all the local stuff in separate directories from now on. Thus, all the stuff we added to /usr/man/manN should be moved to /usr/man/manl. But, what to do about terminfo.3 and terminfo.5? Can't call them *both* terminfo.l, can you? It seems to me that the most logical thing would be to have files called /usr/man/manl/terminfo.3 and /usr/man/manl/terminfo.5; when you say "man 3 terminfo", you get the former and when you say "man 5 terminfo" you get the latter. If you just say "man terminfo", you get one or the other, depending on the usual search-path rules, which I forget offhand. Can anybody see any reason why this would be a Bad Thing? -- Roy Smith, {allegra,cmcl2,philabs}!phri!roy System Administrator, Public Health Research Institute 455 First Avenue, New York, NY 10016 "you can't spell deoxyribonucleic without unix!"
chris@mimsy.UUCP (Chris Torek) (03/09/87)
In article <3403@cbosgd.ATT.COM> kww@cbosgd.ATT.COM (Kevin W. Wall) writes: >The accepted notation is to name manual pages with the basename of the >program and the suffix being the section in the manual in which the said >manual page is supposed to be placed, adding an optional lowercase L (i.e., >a 'l') to the suffix, if it is a "local" command. Whose standard is this? (We once added this to 4.1BSD, and later, I think, to 4.2BSD, but have a `better' solution now.) 4.1, 4.2, and 4.3 BSD `man' all have eight `regular' manual sections, and two `special' sections `l' and `n' (Local and New). Anyway, we decided that using either `prog.l' *or* `prog.1l' or `prog.8l' sections both were bad. The `.l' suffix provides too little information (is this a general use program, or a library, or a file format?). The `.1l' suffix means the file must be tracked carefully, and must be copied at every upgrade: These files are too easily lost. The `better' solution is, once again, paths. The 4.3BSD man program already understands manual paths; all that is needed is a change to make it search /usr/local/man before /usr/man, and then local manuals can be properly named (e.g., error.3s), yet will be easy to find (/usr/local/man/*/*) and *no* trouble to maintain across releases. -- In-Real-Life: Chris Torek, Univ of MD Comp Sci Dept (+1 301 454 7690) UUCP: seismo!mimsy!chris ARPA/CSNet: chris@mimsy.umd.edu
beede@hubcap.UUCP (03/09/87)
The consensus seems to be that .l is a bad suffix for files supplied in conjunction with a makefile. Under BSD and System V, the default suffixes can be overridden with .SUFFIXES: .SUFFIXES: .c .o .p . . . .whatever after which, of course, the rules .x.y have to be specified. This is not a hardship, since ``make -fp - </dev/null >>makefile'' will append the default rules, which can then be edited. So it seems to me that the only difficulty with .l files (after all, this is the default extension for some Lisps) is when you are using lex, too. Adding this is probably no more trouble than remembering to rename .man files to .l when installing them (within the make file, that is). -- Mike Beede UUCP: . . . ! gatech!hubcap!beede Computer Science Dept. Clemson University Clemson SC 29631-1906
mac@esl.UUCP (Mike McNamara) (03/19/87)
Actually, there is the little known (visible in source only) -P
flag, which specifies the use of an alternate root directory, other
than /usr/man. So man -P/usr/local/man getopt would find getopt(3C)
in the /usr/local/man/man3/getopt.3C file.
This is useful if you install things on a machine for which you have not
the root passwd, yet want to have man pages for your utilities...
mac@esl
--
Michael Mc Namara
ESL Incorporated
ARPA: mac%esl@lll-lcc.ARPA