RE: Documentation

["Noel J. Bergman" <no...@devtech.com>]

Alan,

The documentation is primarily web-based, yes.  When we take the time after
v2.1 release to look at Apache Forrest for documentation, we can use Cocoon
to generate other document formats, e.g, PDF.  I could also look at
producing a PDF of the final documentation.  The documentation for James is
all in XML files using Apache provided DTDs.  See src/xdocs in the CVS
repository.

	--- Noel


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: Documentation

["Steven J. Owens" <pu...@darksleep.com>]

On Sat, Dec 21, 2002 at 11:14:19PM -0500, Alan Gerhard wrote:
> So embarking on an old fashioned word based document is really not
> the way to go.
>
> I assume the reasoning behind this decision to use XML, etc. is to
> allow for a more collaborative environment and give greater control
> over maintenance.  What, then, would be the best way to contribute
> to the documentation efforts ?  Assume that I have no XML authoring
> tools or the like ... just a desire to give something back !!
 
     Just a suggestion from the peanut gallery;  some folks recently
put up an apache wiki at nagoya:

     http://nagoya.apache.org/wiki/apachewiki.cgi?

     I believe I actually read about the wiki here on james-user.  In
any event, wikis are an excellent tool for collaborative document
development.  I'm not sure how featureful this one is, with respect to
formatted text, but speaking as somebody who was, at one time,
professionally employed writing software manuals, the content is far
more important than the formatting.

     The next question is how you'll get from the collaboration to a
downloadable doc.  I don't have any idea on that one, other than to
either use a professional-grade tool (my first choice would tend to be
Framemaker) or use XML and pump it through Cocoon.  Since the apache
wiki is a perl script, and it apparently uses a single data directory,
it should not be a huge deal, given cooperation from the nagoya wiki
maintainers, to write a perl script (or a java program) to roll
through the appropriate data files and convert them to XML.

Steven J. Owens
puff@darksleep.com

"I'm going to make broad, sweeping generalizations and strong,
 declarative statements, because otherwise I'll be here all night and
 this document will be four times longer and much less fun to read.
 Take it all with a grain of salt." - Me at http://darksleep.com


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: Documentation

[Kenny Smith <ke...@journalscape.com>]

Hi Alan,

If you are interested in picking up an XML authoring tool, I suggest jEdit
(http://www.jedit.org/). It's a great text editor (and so much more). There
is an XML plugin that you can install (there is a menu, it's just a couple
of clicks) and that will do highlighting and validation and tag completion,
etc, etc.

I love it. :)

Kenny



--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: Documentation

[Danny Angus <da...@apache.org>]

Alan,

Look at the "xdocs" and edit them using a text editor, if you feel ambitious
you can create xslt stylesheets to convert this documentation source in to
formats other than HTML, if word is your metier try transforming the xml
into M$ xml word format.

d.


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: Documentation

["Noel J. Bergman" <no...@devtech.com>]

> i have downloaded the latest release candidate and have 'reviewed' the
> documentation (www and xdocs) - a tremendous improvement over the earlier
> version, but no surprises there (you guys have been busy!!)

Peter Goldstein deserves 90%+ of the credit for the improved documentation.
He has worked his tail off on it on a daily basis.  Documentation is one of
those thankless jobs for programmers, and I think that Peter deserves kudos
for his efforts.

With respect to continued development of the documentation, I think that we
should look at the questions and problems that users bring up online, and
use the FAQ as a sort of index.  Rather than answer most questions in-line,
I'd create more detailed tutorial pages, and refer users from the FAQ to the
more detailed tutorials.

That's my thought.  Others may think differently.  And since we have some
folks here with years of experience writing end user documentation, we
should try to benefit from their experience.

	--- Noel


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: Documentation

[Alan Gerhard <al...@GerCom.Com>]

okay -
i have downloaded the latest release candidate and have 'reviewed' the
documentation (www and xdocs) - a tremendous improvement over the earlier
version, but no surprises there (you guys have been busy!!)

i used xmlspy earlier but was not 100% satisfied so i will look at the netBeans
IDE and see what that's all about. before i go further, is there one area that
needs attention ?

alan




~-----Original Message-----
~From: Aaron Knauf [mailto:aknauf@xtra.co.nz]
~Sent: Sunday, December 22, 2002 5:33 AM
~To: James Users List
~Subject: Re: Documentation
~
~
~As far as XML authoring tools go, I use netbeans.  It has syntax
~highlighting, DTD/XSD validation, DTD generation from XML and DTDdoc
~generation (could be useful for us).
~
~In order to get PDF from JAMES xdocs, you will need to write a XSLT
~stylesheet that produces xsl:fo output.  Cocoon can then run the
~transformation on the fly then pump the xsl:fo through fop to
~produce PDF.
~
~As an alternative to Cocoon, you can just use fop directly to run the
~transformation and produce PDF.  Incidentally, fop can also
~produce RTF
~and one or two other formats.
~
~ADK
~
~Noel J. Bergman wrote:
~> Alan,
~>
~> That would be very cool!  :-)  Yes, the motivation between
~using XML is that
~> the ASF has a set of publishing tools for maintaining the
~web sites.  And
~> with a tool such as Cocoon, you can re-purpose it.
~>
~> If you checkout the XML and look it over, I think you'll get
~the hang of it.
~> I don't know if there is any documentation for the DTD, but
~I just picked it
~> up from the other documents.  And I just use my standard editor
~> (www.lugaru.com).
~>
~> 	--- Noel
~>
~>
~> --
~> To unsubscribe, e-mail:
~<ma...@jakarta.apache.org>
~> For
~additional commands, e-mail:
~<ma...@jakarta.apache.org>
~>
~>
~
~
~--
~To
~unsubscribe, e-mail:
~<ma...@jakarta.apache.org>
~For
~additional commands, e-mail:
~<ma...@jakarta.apache.org>
~


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: Documentation

[Aaron Knauf <ak...@xtra.co.nz>]

As far as XML authoring tools go, I use netbeans.  It has syntax 
highlighting, DTD/XSD validation, DTD generation from XML and DTDdoc 
generation (could be useful for us).

In order to get PDF from JAMES xdocs, you will need to write a XSLT 
stylesheet that produces xsl:fo output.  Cocoon can then run the 
transformation on the fly then pump the xsl:fo through fop to produce PDF.

As an alternative to Cocoon, you can just use fop directly to run the 
transformation and produce PDF.  Incidentally, fop can also produce RTF 
and one or two other formats.

ADK

Noel J. Bergman wrote:
> Alan,
> 
> That would be very cool!  :-)  Yes, the motivation between using XML is that
> the ASF has a set of publishing tools for maintaining the web sites.  And
> with a tool such as Cocoon, you can re-purpose it.
> 
> If you checkout the XML and look it over, I think you'll get the hang of it.
> I don't know if there is any documentation for the DTD, but I just picked it
> up from the other documents.  And I just use my standard editor
> (www.lugaru.com).
> 
> 	--- Noel
> 
> 
> --
> To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
> For additional commands, e-mail: <ma...@jakarta.apache.org>
> 
> 


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: Documentation

["Noel J. Bergman" <no...@devtech.com>]

Alan,

That would be very cool!  :-)  Yes, the motivation between using XML is that
the ASF has a set of publishing tools for maintaining the web sites.  And
with a tool such as Cocoon, you can re-purpose it.

If you checkout the XML and look it over, I think you'll get the hang of it.
I don't know if there is any documentation for the DTD, but I just picked it
up from the other documents.  And I just use my standard editor
(www.lugaru.com).

	--- Noel


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: Documentation

[Alan Gerhard <al...@GerCom.Com>]

So embarking on an old fashioned word based document is really not the way to
go.
I assume the reasoning behind this decision to use XML, etc. is to allow for a
more collaborative environment and give greater control over maintenance.

What, then, would be the best way to contribute to the documentation efforts ?
Assume that I have no XML authoring tools or the like ... just a desire to give
something back !!


Alan

~-----Original Message-----
~The documentation is primarily web-based, yes.  When we take
~the time after
~v2.1 release to look at Apache Forrest for documentation, we
~can use Cocoon
~to generate other document formats, e.g., PDF.  I could also look at
~producing a PDF of the final documentation.  The documentation
~for James is
~all in XML files using Apache provided DTDs.  See src/xdocs in the CVS
~repository.
~	--- Noel


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>