From owner-freebsd-doc Sun Jul 15 2:20:23 2001 Delivered-To: freebsd-doc@freebsd.org Received: from theshell.com (arsenic.theshell.com [63.236.138.5]) by hub.freebsd.org (Postfix) with SMTP id EF79E37B401 for ; Sun, 15 Jul 2001 02:20:20 -0700 (PDT) (envelope-from pavalos@theshell.com) Received: (qmail 19304 invoked from network); 15 Jul 2001 09:20:24 -0000 Received: from oxygen.theshell.com (root@63.236.138.8) by arsenic.theshell.com with SMTP; 15 Jul 2001 09:20:24 -0000 Received: (from pavalos@localhost) by oxygen.theshell.com (8.11.4/8.11.4) id f6F9KJ802572 for freebsd-doc@freebsd.org; Sun, 15 Jul 2001 02:20:19 -0700 (PDT) (envelope-from pavalos) Date: Sun, 15 Jul 2001 02:20:19 -0700 (PDT) From: Message-Id: <200107150920.f6F9KJ802572@oxygen.theshell.com> To: freebsd-doc@freebsd.org Subject: Capitalizing functions et al in man pages Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org I'm wondering what ever became of the "trailing dot in .Nd" thread at the end of January: http://docs.freebsd.org/cgi/getmsg.cgi?fetch=23542+0+archive/2001/freebsd-doc/20010128.freebsd-doc Specifically I am referring to what Ben Smithurst wrote: ------------------- "I'm tempted also to change things like ".Nm Foo" to just ".Nm" at the start of sentences, when the name really is "foo". IMO even at the start of a sentence we shouldn't capitalize things wrong. There's a lot more of these to change though, so there may be stronger objections. I don't feel that strongly about it, it just seems "wrong" to capitalize things wrong." ------------------- If these type of things are case-sensitive, (shell commands, system calls, library functions, kernel interfaces, file names, etc.), then the man page should reflect it. I do not believe that the "The command/utility/etc .Nm" type approach is correct either. Chapter 10 of the fdp-primer suggests "avoid[ing] redundant phrases" like "the command", "the utility", and "the file". I tried to find a good publishing standard that would state how to deal with starting sentences with functions, commands, et al, but I couldn't find one. FDP points to O'Reilly's publishing style, but they also did not specify how to handle this. I finally just pulled out an O'Reilly book that I had laying next to me, _Building Internet Firewalls_, to see how they dealt with it: ------------------- "The two most common network management tools are ping and traceroute. Both are named after the UNIX programs that were the first implementations... "_ping_ simply tests reachability; it tells you whether or not you can get a packet to and from a given host, and often additional information like how long it took the packet to make the round trip. _traceroute_ tells you..." -------------------- They did not capitalize the names of these tools even though they started a sentence. There are other instances of this throughout the book, so it seems they kept this style consistent, and I think we should too. --Pete To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message