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