Date: Sun, 15 Jul 2001 02:20:19 -0700 (PDT) From: <pavalos@theshell.com> To: freebsd-doc@freebsd.org Subject: Capitalizing functions et al in man pages Message-ID: <200107150920.f6F9KJ802572@oxygen.theshell.com>
next in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200107150920.f6F9KJ802572>