Date: Sun, 28 Dec 2008 16:45:55 +0100 From: Rene Ladan <rene@freebsd.org> To: Gabor PALI <pgj@FreeBSD.org> Cc: Rene Ladan <rene@freebsd.org>, freebsd-doc@freebsd.org Subject: Re: [RFC] A Handbook Section on Updating the Documentation Set Message-ID: <49579F33.6020600@freebsd.org> In-Reply-To: <4956AF88.2030502@FreeBSD.org> References: <4956903C.5060405@FreeBSD.org> <87sko9wda1.fsf@kobe.laptop> <495696F1.7080207@freebsd.org> <87d4fdpb46.fsf@kobe.laptop> <87prjdl1zm.fsf@kobe.laptop> <4956AF88.2030502@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
Gabor PALI schreef: > 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. > Makes sense. > >> 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]). > Ok, predefined hostnames are fine with me as long as there is one. Please commit ;) Rene -- http://www.rene-ladan.nl/ GPG fingerprint = ADBC ECCD EB5F A6B4 549F 600D 8C9E 647A E564 2BFC (subkeys.pgp.net)
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?49579F33.6020600>