Date: Sat, 27 Dec 2008 23:43:20 +0100 From: Gabor PALI <pgj@FreeBSD.org> To: Giorgos Keramidas <keramida@ceid.upatras.gr> Cc: Rene Ladan <rene@freebsd.org>, freebsd-doc@freebsd.org Subject: Re: [RFC] A Handbook Section on Updating the Documentation Set Message-ID: <4956AF88.2030502@FreeBSD.org> In-Reply-To: <87prjdl1zm.fsf@kobe.laptop> References: <4956903C.5060405@FreeBSD.org> <87sko9wda1.fsf@kobe.laptop> <495696F1.7080207@freebsd.org> <87d4fdpb46.fsf@kobe.laptop> <87prjdl1zm.fsf@kobe.laptop>
next in thread | previous in thread | raw e-mail | index | archive | help
Giorgos Keramidas wrote: >> On Sat, 27 Dec 2008 21:58:25 +0100, Rene Ladan <rene@freebsd.org> wrote: >>> Indeed, but my tag changes seem to be lost. Maybe I am too picky :) Reasons are explained below: - Some text have changed in the patch and got fixed meanwhile. > It is a > good idea to avoid using a specific CVSup server in the docs, because > users will tend to copy/paste the name of the server and won't > necessarily bother picking the right one for their setup. On the other > hand, having examples that one can copy and paste is nice too; it avoids > the need for a lengthy explanation of what cvsup"N"."country" means, and > we have servers that don't match the country-based pattern. - I assumed that readers are able to replace cvsup with csup and pick a server for themselves, so there is no more explanation needed. > If we change to a <replaceable> template name, then we should update the > text before the commands too, and we should add a link to the Handbook > section that lists the CVSup servers. A pointer to: > > <link linkend="cvsup-mirrors">the list of CVSup mirrors</link> > > should suffice for that. Yep, we can add it. > - <screen>&prompt.root; <userinput>rsync -rltvz <replaceable>docsnap.sk.FreeBSD.org</replaceable>::docsnap <replaceable>/usr/share/doc</replaceable></userinput></screen> > + <screen>&prompt.root; <userinput>rsync -rltvz <hostname>docsnap.sk.FreeBSD.org</hostname>::docsnap <filename class="directory">/usr/share/doc</filename></userinput></screen> > > This one is ok. We don't have many docsnap servers, so <hostname> is > probably fine here. If we start mirroring docsnap files in multiple > places, and there are several to choose, we may have to revert to the > <replaceable> element, but for now <hostname> is fine :) I marked up the hostname and the target directory with <replaceable> because they could be changed by the user. Of course, there is only one Docsnap server at the moment; I simply tried to follow the markup traditions (see FDP Primer, 4.2.5.12 [1]). If we want to make it non-replaceable (as no more Docsnap servers), then I suggest to omit <hostname> and <filename> elements (see FDP Primer, 4.2.4.8 [1]). Cheers, :g [1] http://www.freebsd.org/doc/en/books/fdp-primer/sgml-markup-docbook.html#AEN1810
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?4956AF88.2030502>