[RFC] A Handbook Section on Updating the Documentation Set

[Rene Ladan]

Giorgos Keramidas schreef:
> On Sat, 27 Dec 2008 23:22:01 +0200, Giorgos Keramidas <keramida at FreeBSD.org> wrote:
>> On Sat, 27 Dec 2008 21:58:25 +0100, Rene Ladan <rene at 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)