Date: 05 Nov 2002 13:02:32 -0800 From: swear@attbi.com (Gary W. Swearingen) To: "FreeBSD LIST" <FreeBSD-Questions@FreeBSD.ORG> Cc: "Giorgos Keramidas" <keramida@ceid.upatras.gr>, "Peter Leftwich" <Hostmaster@Video2Video.Com>, "DaleCo Help Desk" <daleco@daleco.biz>, freebsd-doc@FreeBSD.ORG Subject: Manual title standards (was: man 1 eject) Message-ID: <ivu1ivpw5z.1iv_-_@localhost.localdomain> In-Reply-To: <050201c284e3$1b3f4890$fa00a8c0@DaleCoportable> References: <20021104183704.C39772@welearn.com.au> <20021105020032.I87446-100000@earl-grey.cloud9.net> <20021105141249.GH573@gray.sea.gr> <050201c284e3$1b3f4890$fa00a8c0@DaleCoportable>
next in thread | previous in thread | raw e-mail | index | archive | help
"DaleCo Help Desk" <daleco@daleco.biz> writes: > Peter, what in the *header* of your eject > manpage? Generally, FBSD's own man- > pages show up with "FreeBSD System > Manager's Manual", or "FreeBSD General > Commands Manual", etc., etc. Changing the subject, those "FreeBSD ... Manual" strings are the default middle portion of a manual entry's title as produced by the required mdoc(7) ".Dt" macro when the section number is given, but the "volume" is not given. (The left and right portions are usually like "EJECT(1)".) There is apparently no standard on what the title should be. There are non-FreeBSD parts (eg, named(8)) of the base OS which use the default title. There are ports (eg, eject(1) and portupgrade(1)) which do the same. Most of the ports I looked at have no middle portion. A few have silly things like "FSF" (grub(8)). Some seem to be in parts of their manual like "Ruby Programmers Reference Manual" (ruby(1)). Many of the ports will never be patched to have correct titles, but do you all think there should be a standard on titling? Or is there one? Where should it be found? mdoc(7)? Should we pretend that there is only one "UNIX" or "System" or "FreeBSD" manual, or also a Ruby Manual, etc? Should the title (middle portition) of every page of a section, be the same? (A porter's script could probably enforce that standard.) Should the title (middle portition) be the same across the whole manual? Should the titles be unique to parts of the base system, so that other non-base entries MUST NOT use those titles? Or instead of "base system" should it be "FreeBSD parts of the base system"? My preference is that all entries use section-default titles, and that ports be (auto-)patched to conform. I'd prefer a one-manual style: INTRO(5) FreeBSD Manual (File Formats) INTRO(5) PORTUPGRADE(1) FreeBSD Manual (General Commands) PORTUPGRADE(1) Whether the entry is associated with the base OS or ports, etc., should be noted in the body of the entry, under a separate standard, by those who care. (The History section might be OK for it, but I think a new section is needed for info like that and especially for bug reporting info.) 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?ivu1ivpw5z.1iv_-_>