Date: Sat, 27 Dec 2008 23:32:08 +0100 From: Rene Ladan <r.c.ladan@gmail.com> To: Giorgos Keramidas <keramida@ceid.upatras.gr> Cc: Rene Ladan <rene@freebsd.org>, freebsd-doc@freebsd.org, Gabor PALI <pgj@freebsd.org> Subject: Re: [RFC] A Handbook Section on Updating the Documentation Set Message-ID: <4956ACE8.7020201@gmail.com> 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 schreef: > On Sat, 27 Dec 2008 23:22:01 +0200, Giorgos Keramidas <keramida@FreeBSD.org> wrote: >> On Sat, 27 Dec 2008 21:58:25 +0100, Rene Ladan <rene@freebsd.org> wrote: >>>>> [1] http://lists.freebsd.org/pipermail/freebsd-doc/2008-December/015099.html >>>>> [2] http://people.freebsd.org/~pgj/patches/2008/12/27/updating-upgrading-documentation.patch.diff >>>> It goes without saying that after his patience with all my comments >>>> about the patch, and the changes we made this afternoon, Gabor has my >>>> full approval for the patch :) >>> Indeed, but my tag changes seem to be lost. Maybe I am too picky :) >> I'm sorry. I will go through the tag diff and see if it's easy to merge >> them into this :) > > Hi Rene, > > Looking at the 2nd level diff from the private emails, I could see the > following tag changes: > > - <screen>&prompt.root; <userinput>cvsup -h <replaceable>cvsup10.FreeBSD.org</replaceable> -g -L 2 /usr/share/examples/cvsup/doc-supfile</userinput></screen> > + <screen>&prompt.root; <userinput>csup -h <hostname>cvsup<replaceable>N</replaceable>.<replaceable>country</replaceable>.FreeBSD.org</hostname> -L 2 /usr/share/examples/cvsup/doc-supfile</userinput></screen> > + > + <para>Here, <literal>N</literal> is a number indicating which copy > + of the server to use, and <literal>country</literal> is the > + two-letter ISO country code of a (preferably geographically > + close) country.</para> > > I can understand the reasoning behind this part of the changes. 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 It's not that long :) > we have servers that don't match the country-based pattern. > Oops, I didn't know that (I should look up the list of CVSup servers). > I think I like the "cvsup10" version, since we already mention in the > added text that cvsup is merely an example: > > so the documentation sources can be fetched from one of > the <application>CVSup</application> servers, > like <hostid>cvsup10.FreeBSD.org</hostid>, by typing:</para> > > 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. > I guess I mean this list. I must admit I only looked at the diff itself, not at the surrounding text. > - <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 :) > And maybe point to a list of docsnap servers ;) > Are there any other tag changes that I missed? > Nope. Regards, Rene -- http://www.rene-ladan.nl/ GPG fingerprint = E738 5471 D185 7013 0EE0 4FC8 3C1D 6F83 12E1 84F6 (subkeys.pgp.net)
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?4956ACE8.7020201>