From owner-freebsd-doc@FreeBSD.ORG Mon May 19 14:14:56 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 27DD837B401; Mon, 19 May 2003 14:14:56 -0700 (PDT) Received: from abigail.blackend.org (blackend.org [212.11.35.229]) by mx1.FreeBSD.org (Postfix) with ESMTP id B131343F75; Mon, 19 May 2003 14:14:54 -0700 (PDT) (envelope-from marc@blackend.org) Received: from nosferatu.blackend.org (nosferatu.blackend.org [192.168.10.205]) by abigail.blackend.org (8.12.3/8.12.3) with ESMTP id h4JJxKgp012434; Mon, 19 May 2003 21:59:20 +0200 (CEST) (envelope-from marc@abigail.blackend.org) Received: from nosferatu.blackend.org (localhost [127.0.0.1]) h4JJxPkd001792; Mon, 19 May 2003 21:59:25 +0200 (CEST) (envelope-from marc@nosferatu.blackend.org) Received: (from marc@localhost) by nosferatu.blackend.org (8.12.9/8.12.9/Submit) id h4JJxPWa001791; Mon, 19 May 2003 21:59:25 +0200 (CEST) (envelope-from marc) Date: Mon, 19 May 2003 21:59:25 +0200 From: Marc Fonvieille To: Tom Rhodes Message-ID: <20030519195925.GC571@nosferatu.blackend.org> References: <20030519192255.GB74434@submonkey.net> <20030519153048.51f20a06.trhodes@FreeBSD.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20030519153048.51f20a06.trhodes@FreeBSD.org> User-Agent: Mutt/1.4i X-Useless-Header: blackend.org X-Operating-System: FreeBSD 5.1-BETA cc: Ceri Davies 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 21:14:56 -0000 On Mon, May 19, 2003 at 03:30:48PM -0400, Tom Rhodes wrote: > > 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. > In this case the manual page entity seems a better choice: - on the online version it let the reader to read the manual page via the link generated. - on both online and printed versions, it gives an info about the manual page section > 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. I agree, <screen></screen> should be used for that and for multiple lines commands. > There seems to be mixed usage of the command and manual page entities. [...] When we have the choice between <command></command> and manual page for a command name (just the name, not a command with parameters) the manual page entity should be used. Marc