Tools for maintaining OpenJPA documentation

[Kevin Sutter <kw...@gmail.com>]

Just trying to start a new thread on this topic since my reply to an SVN
commit message went unanswered...  :-)

What kind of tools are being used to maintain the OpenJPA manual?  The
documentation updates that I have done have all been pretty minor, so I
haven't been too concerned with messing up the tags in the documentation xml
files.  But, some of the updates that I would like to do require some fairly
extensive changes.  I'm afraid that I just start to edit these xml files
with my favorite editor that I might get myself into a tag mess that I can't
recover from...

Since this documentation originated with the SolarMetric folks, maybe one of
them can comment on some "best practices" for updating the manual?  Or, if
other open-source developers have some input, that would be great.  I would
like to stick with our current xml format and build process, so I'm not
looking to upset the apple cart.  I just need some guidance on editting
practices.

Thanks!
Kevin

Re: Tools for maintaining OpenJPA documentation

[Patrick Linskey <pl...@gmail.com>]

> For editing docbook, I just use an text editor, and then periodically
> use the "xmllint" console application to ensure that I haven't
> violated the DTD. I believe xmllint is available for all platforms,
> and I use the following command:

I believe that xmllint is part of the libxml2 package, for those of
you using Debian, Ubuntu, fink, or cygwin.

-Patrick

On 6/13/07, Marc Prud'hommeaux <mp...@apache.org> wrote:
> Kevin-
>
> Personally, I've never found an XML editing tool that had good
> support for maintaining the format and preserving the chunking style
> of our docbook, but I haven't looked again at tools in the past
> couple of years: there may have been improvements to docbook tooling
> since that time. If you do wind up researching this, I for one would
> be interested in hearing about your results.
>
> For editing docbook, I just use an text editor, and then periodically
> use the "xmllint" console application to ensure that I haven't
> violated the DTD. I believe xmllint is available for all platforms,
> and I use the following command:
>
>     xmllint --noout --valid openjpa-project/src/doc/manual/manual.xml
>
> That just validates syntax. Once I have made a major edit, you can
> just build the docs and make sure they look OK to you (you might need
> to first increase memory by setting MAVEN_OPTS=-Xmx512m):
>
>    mvn -f openjpa-project/pom.xml process-resources -Pdocbook-profile
>
> It's hardly a WYSIWYG process, but once you are comfortable with the
> docbook XML format, I've found that using a plain text editor is good
> enough.
>
>
>
> On Jun 14, 2007, at 4:22 AM, robert burrell donkin wrote:
>
> > On 6/13/07, Kevin Sutter <kw...@gmail.com> wrote:
> >>
> >> Just trying to start a new thread on this topic since my reply to
> >> an SVN
> >> commit message went unanswered...  :-)
> >>
> >> What kind of tools are being used to maintain the OpenJPA manual?
> >> The
> >> documentation updates that I have done have all been pretty minor,
> >> so I
> >> haven't been too concerned with messing up the tags in the
> >> documentation
> >> xml
> >> files.  But, some of the updates that I would like to do require some
> >> fairly
> >> extensive changes.  I'm afraid that I just start to edit these xml
> >> files
> >> with my favorite editor that I might get myself into a tag mess
> >> that I
> >> can't
> >> recover from...
> >
> >
> > is it docbook?
> >
> > if so there are editors around (eg
> > http://wiki.docbook.org/topic/DocBookAuthoringTools) but hopefully
> > someone
> > more cluefull will jump in with version details...
> >
> > - robert
>
>


-- 
Patrick Linskey
202 669 5907

Re: Tools for maintaining OpenJPA documentation

[Marc Prud'hommeaux <mp...@apache.org>]

Kevin-

Personally, I've never found an XML editing tool that had good  
support for maintaining the format and preserving the chunking style  
of our docbook, but I haven't looked again at tools in the past  
couple of years: there may have been improvements to docbook tooling  
since that time. If you do wind up researching this, I for one would  
be interested in hearing about your results.

For editing docbook, I just use an text editor, and then periodically  
use the "xmllint" console application to ensure that I haven't  
violated the DTD. I believe xmllint is available for all platforms,  
and I use the following command:

    xmllint --noout --valid openjpa-project/src/doc/manual/manual.xml

That just validates syntax. Once I have made a major edit, you can  
just build the docs and make sure they look OK to you (you might need  
to first increase memory by setting MAVEN_OPTS=-Xmx512m):

   mvn -f openjpa-project/pom.xml process-resources -Pdocbook-profile

It's hardly a WYSIWYG process, but once you are comfortable with the  
docbook XML format, I've found that using a plain text editor is good  
enough.



On Jun 14, 2007, at 4:22 AM, robert burrell donkin wrote:

> On 6/13/07, Kevin Sutter <kw...@gmail.com> wrote:
>>
>> Just trying to start a new thread on this topic since my reply to  
>> an SVN
>> commit message went unanswered...  :-)
>>
>> What kind of tools are being used to maintain the OpenJPA manual?   
>> The
>> documentation updates that I have done have all been pretty minor,  
>> so I
>> haven't been too concerned with messing up the tags in the  
>> documentation
>> xml
>> files.  But, some of the updates that I would like to do require some
>> fairly
>> extensive changes.  I'm afraid that I just start to edit these xml  
>> files
>> with my favorite editor that I might get myself into a tag mess  
>> that I
>> can't
>> recover from...
>
>
> is it docbook?
>
> if so there are editors around (eg
> http://wiki.docbook.org/topic/DocBookAuthoringTools) but hopefully  
> someone
> more cluefull will jump in with version details...
>
> - robert

Re: Tools for maintaining OpenJPA documentation

[robert burrell donkin <ro...@gmail.com>]

On 6/13/07, Kevin Sutter <kw...@gmail.com> wrote:
>
> Just trying to start a new thread on this topic since my reply to an SVN
> commit message went unanswered...  :-)
>
> What kind of tools are being used to maintain the OpenJPA manual?  The
> documentation updates that I have done have all been pretty minor, so I
> haven't been too concerned with messing up the tags in the documentation
> xml
> files.  But, some of the updates that I would like to do require some
> fairly
> extensive changes.  I'm afraid that I just start to edit these xml files
> with my favorite editor that I might get myself into a tag mess that I
> can't
> recover from...


is it docbook?

if so there are editors around (eg
http://wiki.docbook.org/topic/DocBookAuthoringTools) but hopefully someone
more cluefull will jump in with version details...

- robert