Date: Sat, 27 Dec 2008 23:52:45 +0200 From: Giorgos Keramidas <keramida@ceid.upatras.gr> To: Rene Ladan <rene@freebsd.org> Cc: Gabor PALI <pgj@freebsd.org>, freebsd-doc@freebsd.org Subject: Re: [RFC] A Handbook Section on Updating the Documentation Set Message-ID: <87prjdl1zm.fsf@kobe.laptop> In-Reply-To: <87d4fdpb46.fsf@kobe.laptop> (Giorgos Keramidas's message of "Sat, 27 Dec 2008 23:22:01 %2B0200") References: <4956903C.5060405@FreeBSD.org> <87sko9wda1.fsf@kobe.laptop> <495696F1.7080207@freebsd.org> <87d4fdpb46.fsf@kobe.laptop>
next in thread | previous in thread | raw e-mail | index | archive | help
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 we have servers that don't match the country-based pattern. 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. - <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 :) Are there any other tag changes that I missed?
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?87prjdl1zm.fsf>