ibatis-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Brandon Goodin" <brandon.goo...@gmail.com>
Subject Re: New iBATIS Documentation Format
Date Wed, 04 Oct 2006 15:59:05 GMT
I think the escaping is about all XXE is offering. The reason I say that is
that we will likely be storing our images in a url location. I don't think
we will be embedding images into docbook. That gets a little hard to manage
when trying to transform to different presentation mediums. XXE will
generate all the different formats. But the last time i used it... it was
not as customizable as writing the xsl myself.

I think the clear thing here is that we are going to use DocBook. If people
want to use XXE then fine. If they want to handcode it... then fine. Since
ALL documentation solutions seems to be nasty, let's just get started with
one of these and be on with whatever flavor of pain we like best. I can't
believe documentation is a bigger discussion than writing code. Maybe we
should just do like Ruby and put all of our documentation in the JavaDoc.

Brandon

On 10/4/06, Larry Meadors <lmeadors@apache.org> wrote:
>
> I guess that is another +1 for XXE - it escapes all that crap. Just
> paste the code and you are done.
>
> Larry
>
>
> On 10/4/06, Clinton Begin <clinton.begin@gmail.com> wrote:
> > The biggest thing for me is the embedded XML within the docs.  Because
> > iBATIS has a  lot of XML of its own, it becomes a real pain when we have
> to
> > start typing hundreds of &lt;select&gt; everywhere...
> >
> > Cheers,
> >
> >
> > On 10/4/06, Larry Meadors <lmeadors@apache.org> wrote:
> > > Nope, I think you have all you *need*, but XXE also gives you tools
> > > for things like inserting images and stuff that a text-based editor
> > > won't (but after you do one, you won't need that), and is more WYSIWYG
> > > than eclipse will be, so it may be faster to edit and see the
> > > structure more clearly.
> > >
> > > Nothing earth-shattering, but some niceties nonetheless.
> > >
> > > I also agree that the markup should just be content, and the style
> > > should be applied with XSL later.
> > >
> > > IMO, that is another fundamental difference between using OO and an
> > > XML editor: OO implies structure based on style; XML implies style
> > > based on structure.
> > >
> > > Larry
> > >
> > >
> > > On 10/4/06, Brandon Goodin <brandon.goodin@gmail.com> wrote:
> > > > personally, I would rather use my IDE which already does XML editing
> > > > according to a schema and tells me when i'm doing something goofy.
> Also,
> > the
> > > > docbook is a base markup and not a final product. So, in the end it
> only
> > > > servers to be transformed into something useful. So, I already have
> a
> > set of
> > > > tools that i use to do all that. I have an xml editor, xslt plugin,
> and
> > > > xpath plugin. That's really all i should need. Am i missing
> something?
> > > >
> > > > Brandon
> > > >
> > > >
> > > > On 10/4/06, Larry Meadors <lmeadors@apache.org> wrote:
> > > > > Heheh, is this the politically correct way to say "they both
> suck"?
> > ;-)
> > > > >
> > > > > IMO, the dissonance is because they are trying to accomplish two
> very
> > > > > different things:
> > > > >
> > > > > XXE is an XML editor, not a word processor. It's goal is to make
> the
> > > > > document structure correct.
> > > > >
> > > > > OO Writer is a general purpose word processor that is intended to
> > > > > replace Word, and it happens to have a docbook writer bolted on.
> > > > >
> > > > > When I first used XXE, I found it to be really cumbersome,
> too...just
> > > > > like the first time I used a real Java IDE. It tries to make sure
> you
> > > > > don't screw stuff up (structurally), so you can't do whatever you
> want
> > > > > wherever you want to - it forces you to play by the docbook rules.
> > > > > It's a pain, but once you get used to it, it'll be like the
> difference
> > > > > between using an IDE and notepad for editing Java source. With
> > > > > notepad, you can put anything anywhere, right or wrong, but it's
> not
> > > > > cumbersome at all. ;-)
> > > > >
> > > > > Larry
> > > > >
> > > > >
> > > > > On 10/4/06, Ted Husted < husted@apache.org> wrote:
> > > > > > On 10/4/06, Ted Husted <husted@apache.org> wrote:
> > > > > > > I'll try it again, but the last time I used XXE, I found
it
> > cumbersome
> > > > > > > and distracting. OO is at least unobstrusive.
> > > > > >
> > > > > > I flipped back and forth between them for a while, and found
> each to
> > > > > > be inadequate in different ways. I continued to be amazed at
the
> > lack
> > > > > > of  adequate tools for collaborating on technical documentation.
> > > > > >
> > > > > > -Ted.
> > > > >
> > > >
> > > >
> > >
> >
> >
>

Mime
View raw message