[Bf-docboard] Re: Editing process and tools

[Eric Oberlander]

on 12/4/04 11:17 pm, Jasper Mine at jaspermine@earthlink.net wrote:

> Mr. Oberlander,
> 
> Hello, I'm writing some docs for Blender3d.  An article on helping with
> the Documentation.  Think you could answer a question or two?
> 
> How are you accessing the data which is the manual?
> How are you editing it?
> How are you submitting the data?
> 
> I see you are active in this task and could give me a little insight on
> your process and tools. I am familiar how to do this, just wondering
> your method.
> 
> Thanks,
> jsplifer

Hi

My task is a narrow one, in that I don't create any new documents, I just
sub-edit documents that are already in the CVS repository. The short
explanation is this:

I checkout a working copy of the Manual onto my local Debian based system.

I build an html version of the manual using docbook, and view the results
with a web browser (Konqueror in my case).

I look for typos, spelling errors, broken links, whatever, and then edit my
local copy of the XML file with a plain text editor (i.e. Kate or Kwrite).

I then rebuild the html docbook to make sure it compiles OK, and look for
more errors. I repeat that until I think I've done enough, and I then do a
diff between my working copy and the copy in CVS, to see what's changed.

When I'm happy with the result, I commit the changes to CVS.

In more detail, the instructions on how to checkout a working copy of CVS
can be found on the Blender website at:

http://projects.blender.org/cvsx/?group_id=7

To find out the 'modulename' you need to use, browse the CVS Repository:
http://projects.blender.org/viewcvs/viewcvs.cgi/?cvsroot=docboard

You should find 'BlenderManual2.32'

There are some useful things you can do while browsing the CVS. For
instance, you can view changes between versions graphically:

http://projects.blender.org/viewcvs/viewcvs.cgi/BlenderManual2.32/PartM/curv
es_surfaces/en/section_curves.xml.diff?r1=1.1&r2=1.2&cvsroot=docboard

I built a dedicated Debian system to do this work (I have a PC with a
removable harddisk tray, so I can insert the disk when I want to work on the
project).

I used Debian because it was easy to install all the necessary docbook tools
using apt-get, but I would imagine this is easy enough on other
distributions if you know what you want to install.

On the basis that I didn't know what was needed, I installed any package
that seemed relevant. Jadetex, docbook, docbook-xml, docbook-utils,
docbook-xsl, docbook-dssl etc. I used 'apt-cache search docbook' to find
likely looking packages.

I kept on adding packages until the command 'docbook2html -o html
BlenderManual2en.xml' ran successfully. (You have to be in the
/BlenderManual2.32 directory when you run this command of course).

A directory is created called /html and within it you'll find a file called
'index.html'. Click on that and you should see the Manual in html format. If
the graphics images aren't shown, you have to poke around in the files to
find the expected path to the images. In my case I had to add links within
the /html directory; for instance, I used 'ln -sf ../PartM/ PartM' to get
the images for the Modelling chapter to appear.

HTH

Eric