[RFC] A Handbook Section on Updating the Documentation Set

[Frank Shute]

On Tue, Jan 06, 2009 at 09:24:25PM +0200, Giorgos Keramidas wrote:
>
> On Sun, 4 Jan 2009 20:36:31 +0000, Frank Shute <frank at shute.org.uk> wrote:
> >On Sun, Jan 04, 2009 at 07:31:56PM +0200, Giorgos Keramidas wrote:
> >>On Sat, 27 Dec 2008 21:29:48 +0100, Gabor PALI <pgj at freebsd.org> wrote:
> >>> http://people.freebsd.org/~pgj/patches/2008/12/27/updating-upgrading-documentation.patch.diff
> >>
> >> Ping...  Any news about this patch?
> >
> > Hi Giorgos,
> >
> > If you remember, you asked me if I could get the page I wrote about
> > using csup to update the docs:
> >
> > http://www.shute.org.uk/misc/freebsd_uptodate.html
> >
> > into some sort of state to be incorporated into the updating section
> > of the handbook.
> 
> Hi Frank,
> 
> "Yes", and if you can review the existing patch by Gabor Pali :)

I've had a look at the patch and I like it. I wish it had existed in
the docs before!

A niggle though: 

Are the docs going to start using s/cvsup/csup/?  ATM, there's only a
note in "A.6 Using CVSup" about using csup instead of cvsup; but the
chapter on installing ports uses csup. It's all a bit inconsistent.

I think Gabor's patch should use csup & have a note about using cvsup
if you've got an OS < 6.2. As far as I can see, only developers who
want to pull the CVS files need cvsup & those with older releases...
although they can install the csup port with it's fewer dependencies.

I didn't see any errors in it otherwise & I thought it gave a nice
easy to follow guide which is what's needed.

> 
> > I've built the docs with Gabor's above patch applied & have started
> > work on rejigging that section.
> >
> > You can see how far I've got. I've only done one page (which is bound
> > to change) & largely worked on the css, so it's easier to mark-up into
> > sgml:
> >
> > http://www.shute.org.uk/freebsd/synopsis.html
> 
> Don't spend too much time tweaking the CSS style.  We don't often make
> changes in that area.

I wanted to tweak the CSS on my site so it more closely followed that
of FreeBSD. I develop my site by shamelessly copying ;)

> 
> > I've made an executive decision to change mentions of cvsup to csup
> > where appropriate since it's in base.
> 
> Rene Ladan (added to the Cc: list) wanted to write about csup too, if my
> memory does not fool me.  Gabor and Rene had a discussion about this, so
> before you spend a lot of time writing a long description of csup, maybe
> it would be a good idea to talk to Gabor and Rene.

I think my write-up on csup is largely redundant although the:

cd /usr/src
make update
cd /usr/ports
make fetchindex

stuff should be covered somewhere & I don't think it is.

> 
> I'm glad that you are willing to help with the doc updating section.  We
> can always use a bit of help with the documentation :-)

It's a pleasure :) I'll hang around on doc@ and if I can help in any
capacity I'll try and do so. 

I'm yet to read the fdp primer all the way through, so I'm a bit
useless ATM :(

> 
> Cheers,
> Giorgos
> 

Regards,

-- 

 Frank 


 Contact info: http://www.shute.org.uk/misc/contact.html