[RFC] A Handbook Section on Updating the Documentation Set

[Rene Ladan]

Gabor PALI schreef:
> Giorgos Keramidas wrote:
>>> On Sat, 27 Dec 2008 21:58:25 +0100, Rene Ladan <rene at 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)