[OT] Project documentation

W

Wendy S

Well, they _are_ all Java projects... but it's OT, I know. I need to get a
handle on project documentation. Can someone toss out some options for
generating documentation? What is (or could be) behind the numbered
chapter/section/subsection format of the various PDF files (specifications
and manuals) that I download?

I have so far adopted the xml and xsl transform found in many Apache and
Jakarta projects, and that has helped tremendously for HTML documentation,
but I need to be able to hand over a document and say 'this is what I'm
building'.

Thanks,
Wendy
 
R

Ryan Stewart

Wendy S said:
Well, they _are_ all Java projects... but it's OT, I know. I need to get a
handle on project documentation. Can someone toss out some options for
generating documentation? What is (or could be) behind the numbered
chapter/section/subsection format of the various PDF files (specifications
and manuals) that I download?

I have so far adopted the xml and xsl transform found in many Apache and
Jakarta projects, and that has helped tremendously for HTML documentation,
but I need to be able to hand over a document and say 'this is what I'm
building'.
Sad to see you haven't received any replies to this. I'd like to see some
feedback on this matter too, especially as it relates to web applications.
 
W

Wendy S

Ryan Stewart said:
Sad to see you haven't received any replies to this. I'd like to see some
feedback on this matter too, especially as it relates to web applications.

I have a feeling I am not alone in the lack-of-documentation area! My
requirements are to produce PDF and HTML output from a single source, handle
the fancy numbered chapter/section/subsections, and do both table of
contents and an index. Oh, and to be something new and fun to play with. ;)

I found DocBook. I've heard of it before, but I had never used it. It's an
XML format, and there are XSL stylesheets to transform the XML into pretty
much anything.

I put together a page of resources and examples as I was working on the
XML-to-PDF part:
http://wiki.wendysmoak.com/cgi-bin/wiki.pl?DocBookToPDF

To get from XML to PDF takes two steps, first you go from .xml to .fo with
XSLT, then from .fo to .pdf with Apache FOP. The stylesheets are still
Greek to me, and I don't have a clue how FOP works, but thankfully there are
Ant tasks for everything and you just have to point them at the right files.
Once that works, transforming to HTML is trivial, you just use a different
stylesheet.

This, I suspect, is the easy part. Now I have to figure out what to put
_in_ the documentation. ;)
 
T

Tilman Bohn

In message <oMcSd.84409$bu.32392@fed1read06>,
Wendy S wrote on Sun, 20 Feb 2005 20:40:20 -0700:

[...]
I have a feeling I am not alone in the lack-of-documentation area! My
requirements are to produce PDF and HTML output from a single source, handle
the fancy numbered chapter/section/subsections, and do both table of
contents and an index. Oh, and to be something new and fun to play with. ;)

Have you looked at Maven (http://maven.apache.org/ )? I haven't found
the time to play with it myself yet, but a friend of mine swears by it
for all his builds and deployments, including generating documentation.
There seem to be loads of plugins for generating changelogs, checkstyle
reports, clover reports (test coverage), developer activity reports,
producing javadocs, jdepend metrics, unit test reports, and a host of
other stuff besides building your projects. It can create PDF, HTML and
whatnot. And finally, it generates your documentation web site.

http://maven.apache.org/reference/plugins/plugins.html
I found DocBook. I've heard of it before, but I had never used it. It's an
XML format, and there are XSL stylesheets to transform the XML into pretty
much anything.

Actually it's originally an SGML application, but as of version
<mumble> there are XML DTDs and schemata for it. In that incarnation it
is surprisingly known as DocBook XML.

Maven is supposed to be able to work with DocBook too by way of the
docbook plugin, although there is a warning about limited testing.
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

No members online now.

Forum statistics

Threads
473,744
Messages
2,569,482
Members
44,901
Latest member
Noble71S45

Latest Threads

Top