[RFC] A Handbook Section on Updating the Documentation Set
frank at shute.org.uk
Wed Jan 7 06:54:10 UTC 2009
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:
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 :(
Contact info: http://www.shute.org.uk/misc/contact.html
More information about the freebsd-doc