Convention for naming manual pages: .l vs .1

[kww at cbosgd.UUCP]

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. 43213