ibatis-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Richard Sullivan" <itexpert.sulli...@gmail.com>
Subject Re: New iBATIS Documentation Format
Date Tue, 03 Oct 2006 18:32:59 GMT
> I'm giving DocBook my +1.
I luvya Clinton. Any way ya wanna do it man is OK with me.

Seriously I think this is the way to go (and I really did go and print
the devguide PDF and read it on a train ;=)
I did a brief evaluation of DocBook about a year ago - just enough so
I could argue it's strengths and advocate using it in my dayjob.
Unfortunately the boss said "No! Word is the best documentation tool
ever and is soooo easy to use" so our docs still suck and all I can
offer you guys is fond foggy memories...

I found the amount of "getting started" material overwhelming and
there was a lot of outdated material out there (basically you wanna
ignore most of the DSSSL stuff and go for XSL).  There seemed to be
endless variations of DTDs/Schemas but the basic distinction was
"book" or "article" (I guess you folks want "book" for the devguide
and maybe "article" for the tutorial).

If you are running 'dose, hate 'nix and just want to kick the tires try:
They have a bunch of DOS-like command line programs ready to go. You
can just edit some example XML template using your favourite editor
and run some .bat file to convert it to pdf and HTML. Idiot proof.  I
have no idea how it did the magic but I guess it would be quite to
easy find out.

For Debian flavour Linux fans (or anyone who likes an easy to read
newbie-level article even if it is probably out of date):

I know one of my managers here actively uses docbook for some private
projects and uses http://www.xmlmind.com/xmleditor/ (freeware
edition).  I haven't tried that tool but if he can get it to work then
you guys should have no problems.

Eclipse lovers (myself included) should try this:


On 10/3/06, Clinton Begin <clinton.begin@gmail.com> wrote:
> I'm sold, at least enough to give it a shot.
> I'm giving DocBook my +1.
> What does everyone else think?
> Clinton
> On 10/3/06, Jeff Butler <jeffgbutler@gmail.com> wrote:
> >
> > For me the main advantage is that the source is plain XML so it's
> diffable.
> >
> > Another advantage is that the source can be transformed into a large
> variety of formats (PDF, HTML, Word, Eclipse Help, etc.)
> >
> > Most publishers accept DOCBOOK markup as input.  So if anyone every wanted
> to publish the developer's guide, it would be simple. (I know this is not
> really going to happen, but I think it says something that places like
> O'Reilly accept DOCBOOK)
> >
> > Jeff Butler
> >
> >
> >
> >
> >
> > On 10/3/06, Clinton Begin <clinton.begin@gmail.com > wrote:
> > >
> > > I'm going to look at DocBook again.  I'll download the XMLMind editor
> and the .NET guide (but I've heard that some people just use an IDE...no
> XMLMind necessary).
> > >
> > > But just to refresh my memory....what are the advantages of DocBook over
> OOo....?
> > >
> > > Cheers,
> > > Clinton
> > >
> > >
> >

View raw message