From owner-freebsd-doc@FreeBSD.ORG Mon May 19 12:38:07 2003 Return-Path: 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 A311637B401; Mon, 19 May 2003 12:38:07 -0700 (PDT) Received: from pittgoth.com (14.zlnp1.xdsl.nauticom.net [209.195.149.111]) by mx1.FreeBSD.org (Postfix) with ESMTP id BC0EF43F85; Mon, 19 May 2003 12:38:06 -0700 (PDT) (envelope-from trhodes@FreeBSD.org) Received: from mobile.pittgoth.com (acs-24-154-229-196.zoominternet.net [24.154.229.196]) by pittgoth.com (8.12.9/8.12.9) with SMTP id h4JJc5ka012124; Mon, 19 May 2003 15:38:05 -0400 (EDT) (envelope-from trhodes@FreeBSD.org) Date: Mon, 19 May 2003 15:30:48 -0400 From: Tom Rhodes To: Ceri Davies Message-Id: <20030519153048.51f20a06.trhodes@FreeBSD.org> In-Reply-To: <20030519192255.GB74434@submonkey.net> References: <20030519192255.GB74434@submonkey.net> X-Mailer: Sylpheed version 0.8.10claws (GTK+ 1.2.10; i386-portbld-freebsd5.1) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit cc: doc@FreeBSD.org Subject: Re: Application and command names in elements X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project <freebsd-doc.freebsd.org> List-Unsubscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-doc>, <mailto:freebsd-doc-request@freebsd.org?subject=unsubscribe> List-Archive: <http://lists.freebsd.org/pipermail/freebsd-doc> List-Post: <mailto:freebsd-doc@freebsd.org> List-Help: <mailto:freebsd-doc-request@freebsd.org?subject=help> List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-doc>, <mailto:freebsd-doc-request@freebsd.org?subject=subscribe> X-List-Received-Date: Mon, 19 May 2003 19:38:07 -0000 On Mon, 19 May 2003 20:22:55 +0100 Ceri Davies <ceri@freebsd.org> wrote: > > I've been taking a high level look at getting all the <title> elements in > the handbook ready for the 3rd edition (well, glimpse has been doing all > the hard work so far), and I'm very tempted to religiously wrap all application > and command names in the appropriate markup. > > Would anyone care to talk me out of it? > I'd like to chime in here if you do not mind. While I was thinking about this just last night, a question arose as to which is more appropriate: <command> or manual page entities. <command>, and &man.REF;, to me, are ambiguous. For instance, we can wrap the following in either command or &man entities: By using the &man.ssh.1; utility for remote network connections, you reduce the risk of password theft. By using the <command>ssh</command> utility for remote network connections, you reduce the risk of password theft. Perhaps we should standardize this some way. We have the screen for examples. Perhaps for commands where we do not need the screen tag, we can use the markup: Use <command>cvsup -g -L 2 src</command> to remove the graphic dependency on X11. Then we can use screen for, say, a series of commands which generate output. There seems to be mixed usage of the command and manual page entities. My attempt here was merely to keep it one way, or the other. Perhaps I'm thinking too much... -- Tom Rhodes