From owner-freebsd-doc Tue Nov 5 13: 2:10 2002 Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 2868937B401; Tue, 5 Nov 2002 13:02:09 -0800 (PST) Received: from rwcrmhc52.attbi.com (rwcrmhc52.attbi.com [216.148.227.88]) by mx1.FreeBSD.org (Postfix) with ESMTP id 9E2FF43E6E; Tue, 5 Nov 2002 13:02:08 -0800 (PST) (envelope-from swear@attbi.com) Received: from localhost.localdomain ([12.242.158.67]) by rwcrmhc52.attbi.com (InterMail vM.4.01.03.27 201-229-121-127-20010626) with ESMTP id <20021105210203.CSZP19869.rwcrmhc52.attbi.com@localhost.localdomain>; Tue, 5 Nov 2002 21:02:03 +0000 Received: from localhost.localdomain (localhost [127.0.0.1]) by localhost.localdomain (8.12.6/8.12.5) with ESMTP id gA5L2iUW092566; Tue, 5 Nov 2002 13:02:45 -0800 (PST) (envelope-from swear@attbi.com) Received: (from jojo@localhost) by localhost.localdomain (8.12.6/8.12.5/Submit) id gA5L2Whk092563; Tue, 5 Nov 2002 13:02:32 -0800 (PST) (envelope-from swear@attbi.com) X-Authentication-Warning: localhost.localdomain: jojo set sender to swear@attbi.com using -f To: "FreeBSD LIST" Cc: "Giorgos Keramidas" , "Peter Leftwich" , "DaleCo Help Desk" , freebsd-doc@FreeBSD.ORG Subject: Manual title standards (was: man 1 eject) References: <20021104183704.C39772@welearn.com.au> <20021105020032.I87446-100000@earl-grey.cloud9.net> <20021105141249.GH573@gray.sea.gr> <050201c284e3$1b3f4890$fa00a8c0@DaleCoportable> From: swear@attbi.com (Gary W. Swearingen) Date: 05 Nov 2002 13:02:32 -0800 In-Reply-To: <050201c284e3$1b3f4890$fa00a8c0@DaleCoportable> Message-ID: Lines: 47 User-Agent: Gnus/5.0808 (Gnus v5.8.8) XEmacs/21.1 (Cuyahoga Valley) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii 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 "DaleCo Help Desk" 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