Mailing-List: contact dev-help@openjpa.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@openjpa.apache.org
Received-SPF: pass (herse.apache.org: domain of mprudhomapache@gmail.com
 designates 64.233.166.182 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=beta;
        h=received:mime-version:in-reply-to:references:content-type:message-id:content-transfer-encoding:from:subject:date:to:x-mailer:sender;
        b=WATYwY61xdMyUr6W4saK1tehRPAUC+zRMs5/q+BiF0Q02WK+lRtXai1hoRmiA/fBmMgVdTLvRebv5mLaZRlVWsq1oVOj1bRcx7rPb2PpcjhDf5MjF3czGWK/c2HofT/X2F1J5M4n/j8vaPk+vCHEoiVp/89dhuwusawMsX03K1M=
Mime-Version: 1.0 (Apple Message framework v752.3)
In-Reply-To: <f470f68e0706131322x30b11ea5h700ffff76cc9e678@mail.gmail.com>
References: <89c0c52c0706131300y51b07cddn9d78e26c7748d343@mail.gmail.com>
 <f470f68e0706131322x30b11ea5h700ffff76cc9e678@mail.gmail.com>
Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed
Message-Id: <067579D1-0EF8-44FB-BDBD-46A04A4DF02D@apache.org>
Content-Transfer-Encoding: 7bit
From: Marc Prud'hommeaux <mprudhom@apache.org>
Subject: Re: Tools for maintaining OpenJPA documentation
Date: Thu, 14 Jun 2007 06:47:02 +0800
To: dev@openjpa.apache.org
Sender: Marc Prud'hommeaux <mprudhomapache@gmail.com>

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 <kwsutter@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