[RFC] A Handbook Section on Updating the Documentation Set

[Giorgos Keramidas]

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
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?