Date: Fri, 14 Mar 2003 08:11:17 -0800 From: "Bruce A. Mah" <bmah@FreeBSD.ORG> To: Lucky Green <shamrock@cypherpunks.to> Cc: "'Hiroki Sato'" <hrs@eos.ocn.ne.jp>, doc@FreeBSD.ORG Subject: Re: <citerefentry> vs. &man.command.section Message-ID: <20030314161117.GB29924@intruder.bmah.org> In-Reply-To: <00aa01c2e8c5$d079cdc0$6601a8c0@VAIO650> References: <20030313.025224.98423896.hrs@eos.ocn.ne.jp> <00aa01c2e8c5$d079cdc0$6601a8c0@VAIO650>
index | next in thread | previous in thread | raw e-mail
[-- Attachment #1 --] If memory serves me right, Lucky Green wrote: > Hiroki Sato wrote: > > shamrock> 2) Is it required that every time a FreeBSD command is > > shamrock> mentioned the command _must_ be surrounded by the <command> > > shamrock> tags? I have explanatory text paragraphs in which gbde is > > shamrock> mentioned multiple times and having all these bold > > instances > > shamrock> of gbde in the same paragraph looks strange to me > > (in the html > > shamrock> output). > > > > Hmmm, could you please show an example? > > First of all, sorry for the mental typo. I meant to say <application>, > not <command>. > > Here is an example of some text that I wrote that I believe may be too > cluttered with bold face terms when rendered as HTML: (or PDF or...) > <sect2> > <title>Compatibility issues</title> > <para>&man.sysinstall.8; is incompatible with > <application>gbde</application>-encrypted devices. All > <application>gbde</application> devices must be detached from the kernel > before launching <application>sysinstall</application> or > <application>sysinstall</application> will crash during its initial > probing for devices. To detach the <application>gbde</application> > device used in our example, use the following command: > </para> > <screen>&prompt.root; <userinput>gbde detach /dev/ad4s1c.bde</userinput> > </screen> > </sect2> Hmmm. I'm not real happy with the above markup either. If it was me, I would have done the markup like this: <sect2> <title>Compatibility issues</title> <para>&man.sysinstall.8; is incompatible with &man.gbde.4;-encrypted devices. All &man.gbde.4; devices must be detached from the kernel before launching &man.sysinstall.8; or &man.sysinstall.8; will crash during its initial probing for devices. To detach the &man.gbde.4; device used in our example, use the following command: </para> <screen>&prompt.root; <userinput>gbde detach /dev/ad4s1c.bde</userinput> </screen> </sect2> That's still a little repetitive, but better than before. (Note that the original author might have written this before the gbde(4) manpage was added to the tree.) I generally use the <application></application> elements when referring to a software package as a whole and manpage entities when referring to specific executables. The FDP Primer (look for "In-line Elements") has a pretty good example of this: http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/sgml-markup-docbook.html Bruce. [-- Attachment #2 --] -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.1 (FreeBSD) iD8DBQE+cf8l2MoxcVugUsMRAgU3AJwKDpgwPHWKwfXQ08pO4n4RKfdybwCcDZfU qxbnIBz6cQQYjPOF4mBEVq0= =sbZl -----END PGP SIGNATURE-----home | help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20030314161117.GB29924>