[Box Backup-dev] DocProject editing setup

[Per Thomsen]

On 8/11/06 12:50 AM, E.W. Peter Jalajas wrote:
> Moving off of boxbackup mailing list to boxbackup-dev...
>
> Sorry, Per, but I just don't have any experience with xml, so I'm gonna
> need a lot more hand-holding.  Rather than quitting and running away,
> let me try a couple of baby steps.  Maybe this thread will help others
> join the doc team.
>   
I will answer your questions on the mailing list to the best of my
ability, and then take that info to the Wiki... As you said, hopefully
this will help others get over the hurdle as well...
> 1) Here's what I have for xml editors:  
>
> I'm on gnome on ubuntu dapper linux (debian).  I have screem and
> bluefish which both seem to have xml functions built in.  I'll try them
> both after we get the rest of this thing set up.  (I'm fairly
> proficient at vi/vim, if that helps. gedit has xml highlighting, fwiw.)
>   
You can certainly edit in a text editor, but the DTD (the rules that
govern the structure of a DocBook document) are complicated, and errors
in a document can be hard to find.

I am exclusively using XMLMind's XXE (Standard Edition). It is a WYSIWYG
DocBook editor, and can be downloaded here:
http://www.xmlmind.com/xmleditor/download.shtml

I highly recommend using this editor, since it takes care of all the
(highly complicated) rules of the DocBook DTD, and will only let you
create correct DocBook XML. No XML editing... The user interface looks
like a word processor.

Especially since you don't have experience with XML, I would recommend
trying XXE.

It is also the only such editor that I have found that is free.

It is written in Java, and I have not had problems running it on Linux
(FC4 and 5), Windows or Mac OSX.

> 2) Here's what I have for xsltproc and docbook:
>
> $ dpkg -l | grep xsltproc
> ii  xsltproc                               1.1.15-1ubuntu1    XSLT
> command line processor
> $ dpkg -l | grep docbook
> ii  docbook-dsssl                          1.79-3    modular DocBook
> DSSSL stylesheets, for print
> ii  docbook-utils                          0.6.14-1    Convert Docbook
> files to other formats (HTML
> ii  docbook-xml                            4.4-4    standard XML
> documentation system, for softw
> ii  docbook-xsl                            1.68.1-0.1ubuntu1   
> stylesheets for processing DocBook XML files
>
> How does that look?  1.68 looks bad per the DocProject page.  I'm not
> sure I want to start messing with a dependency hell, but I'm open to
> suggestions.  Maybe I can just stay away from man pages? 
>   

It doesn't mean that man pages won't work, they will just look quite
ugly, but can still be read. If you aren't going to be editing man-pages
don't worry about the versions for now. That said, I did install 1.69.1
on Fedora, without incident (ie. no dependency issues).
> 3) Here's what I have for stylesheets:  
>
> The DocProject page mentions getting stylesheets.  I see stylesheets in
> the listing above; do I need anything else re that?  I have no clue how
> to use them yet.
>   
The stylesheets I'm talking about are the docbook-xsl ones, so nothing
else is needed for that.
> 4) Here's what I have for subversion:
>
> I didn't have it installed, so I ran
>
> sudo apt-get install subversion
>
> and so now I have:
>
> $ dpkg -l | grep -e subversion -e svn
> ii  libnl1-pre6                            1.0~pre5+svn21-2ubuntu2   
> Library for dealing with netlink sockets
> ii  libsvn0                                1.3.1-3ubuntu1    shared
> libraries used by Subversion (aka. sv
> ii  subversion                             1.3.1-3ubuntu1    advanced
> version control system (aka. svn)
>
> The boxbackup-dev mailing list mentions transferring the svn repository
> and integrating with trac.  Do I need to do anything with that info?
>   
No. The SVN repository hasn't changed. Martin responded to most of your
SVN concerns in a separate mail.

Keep the questions coming!

Thanks,
Per

-- 
Per Reedtz Thomsen | Reedtz Consulting, LLC | F: 209 883 4119
V: 209 883 4102    |   pthomsen@reedtz.com  | C: 209 996 9561
GPG ID: 1209784F   |  Yahoo! Chat: pthomsen | AIM: pthomsen