[PATCH] A Handbook Section on Documentation Ports

[Gabor PALI]

Hi,

Ben Kaduk wrote:
> I appear to be a bit behind in my mail, but it looks like no one has
> commented, and this still hasn't hit the tree ...

Well, we are still waiting for Mr. Giorgos Keramidas' review :P


> I do think it's worth mentioning the documentation ports, and have
> only a couple comments on the patch itself:

Great!


>        <listitem>
>  	<para>How to keep your documentation up to date with
> -	  <application>CVSup</application><!-- and
> +	  <application>CVSup</application>, or documentation ports<!--, and
>  	  <application>Docsnap</application>-->.</para>
>        </listitem>
> 
> This doesn't seem to have made it into the HTML preview that you linked
> in your follow-up?
> In any case, the comma is probably unnecessary.

OK


> +      <para>An option to ease the process of documentation updating
> +	while still staying close to the sources, is to use the
> 
> this line is a bit awkward.  Perhaps "An easier way to update the
> documentation while still using updated sources is to use the [...]"

OK


> +      <para>Basically, this technique implements almost the same method
> +	as <application>CVSup</application> that we have already seen,
> 
> "that we have already seen" is redundant.

OK


> +	command, and compilation of the sources might be omitted as the
> +	&os; package building cluster builds packages from the
> +	documentation ports.  Thus, the user can decide to update
> +	documentation from a pre-built binary package.</para>
> 
> 
> I think it might be better to say "and compilation of the sources
> might be skipped through the use of a pre-built binary package
> provided by the &os; package-building cluster."

OK

> +	<para>If building from sources is preferred, the mandatory
> +	  documentation tools will be automatically installed as a
> 
> I would s/mandatory documentation tools/tools needed to build the documentation/

OK


> +	    <para>There is a <quote>master port</quote>, <filename
> +		role="package">misc/freebsd-doc-en</filename> where the
> 
> comma after freebsd-doc-en.

OK


> +	      English documentation only, probably the most requested
> +	      language for the majority of the users.</para>
> 
> I don't think that "probably ...users" is necessary

OK


> +	<para>To install a documentation port by source, issue the
> 
> s/by/from/

OK


> +	<para>If resources are not available for the complete build and
> +	  installation of the documentation ports, or we simply want to
> 
> This sounds a bit awkward.  "compilation" is perhaps not strictly
> correct, so maybe "the complete process of building and installing the
> documentation ports".

OK


> +	  have the documentation installed in a more convenient way,
> +	  binary packages come handy.  They can be managed as normal
> 
> s/come handy/are a convenient option/

OK


> Thanks for writing these up!

Thanks for the comments and the review :)

Here is the updated version of the patch and the HTML version:

http://people.freebsd.org/~pgj/patches/2009/04/12/documentation-ports.4.diff
http://people.freebsd.org/~pgj/patches/2009/04/12/html/updating-upgrading.html


Cheers,
:g