I wish the Xdoc format kept in mind that documents could be rather large or
that it may take several 'xdoc' documents to handle a chapter rather than
just a single xdoc file. I think the 'xdoc' structure is too simple. I
might have to create a documentation.xml project to describe the
relationships of all the xdoc documents to make the PDF generation possible
(since it'll be all in a single file rather than a bunch of files). I could
also run over this to build a table of contents, menu structure, etc. as
well.
To give an idea, perhaps something like this (tags and attributes missing of
course):
<book>
<chapter intro="chapter1/intro.xml" summary="chapter1/summary.xml">
<section xml="chapter1/actions.xml" />
<section xml="chapter1/views.xml">
<section xml="chapter1/jsp.xml" />
<section xml="chapter1/xslt.xml" />
</section>
</chapter>
</book>
At least this format would maintain the relationships between the files in a
central location and we could generate menus and next/previous page links
based on this information. The only drawback to this approach is that it's
more work.
With the 'xdoc' format, the main problem we will definately face is
controlling and managing the depth of sections and subsections (even with a
documentation.xml file described above).
For instance, let's say we have an 'xdoc' file that contains a bunch of
sections and subsections - so the document could be said to represent a
chapter in the documentation. Now, let's say a few of those subsections get
really big, so we'll sub-subsections (which I'm not sure the xdoc format
supports, but I'm assuming it does). As far as I can tell, the best
solution would be to 'pull up' the <section> blocks into their own 'xdoc'
documents and rename the first <subsection> tags to <section> for each of
the new documents. Then you'd have to update the documentation.xml to
describe this changes in the relationships. We must do this or the HTML
pages will become unporportionized. This isn't desirable since it's a good
practice is to keep HTML pages short and have multiple pages - it just makes
it easier on the reader.
I guess the point I'm trying to make is that the 'xdoc' approach seems like
a lot of maintance to me whenever we need to add or delete content - kind of
like a b* tree works. After writing 500 pages this year alone, I know
sections that were planned to be short actually kept growing after every
review period or even during the first draft. It's very normal to find new
stuff to talk about or to clarify. Eventually, you notice that what should
have been a single page has now become a couple of pages with a small
hierarchy of its own. This wasn't due to poor planning either. Books are
always planned at the chapter level first and then refined to a very
specific chapter organizational level before anything is even written.
Needless to say, this restructuring is easy to do in word or even a text
file; not so easy to do with xdoc. This bothers me a bit. I think a
document should be completely self-describing and the format should be a
good fit if the manual is 10 pages or 2000 pages. Perhaps it's more concern
than is really needed. I know how to solve these issues, but the solution
doesn't require xdoc (but it will look a lot like it) and some people might
not like that. I guess I'm just looking for people's thoughts. When I saw
the xdoc format, I knew what the problems were and how to solve them, I just
want to keep the main people involved and to communicate the problems we
might have if we go with xdoc.
Regards,
Ken
----- Original Message -----
From: "Bill Burton" <[EMAIL PROTECTED]>
To: <[EMAIL PROTECTED]>
Sent: Thursday, December 12, 2002 12:09 PM
Subject: Re: [OS-webwork] xbook
Hello,
Aslak Hellesøy wrote:
> xbook looks like something else.
Yes.
> xdoc is a proprietary xml format invented by jakarta. it's kind of plain
> xhtml with some extra tags (section, source...) to mark sections ans
source
> sections.
>
> details are here:
>
> http://jakarta.apache.org/site/jakarta-site-tags.html
This is a good overview of what the xdoc XML looks like.
You can check out the Jakarta CVS site2 module, which includes Anakia
and what you need to build any xdoc. See
http://jakarta.apache.org/site/jakarta-site2.html.
> i think there are only two tools that can transform xdoc documents to
human
> readable documents:
>
> o anakia (part of velocity). it transforms to docs with a look similar to
> the link above.
> o maven. it transforms to docs like on the maven site itself. it can also
> transform them to pdf.
DVSL (http://jakarta.apache.org/velocity/dvsl/index.html). Grab the
latest version and then run the Ant build.xml to DVSL's docs which are
in xdoc format. The included stylesheet renders output similar to the
Anakia stylesheets used for the Jakarta sites. See
http://cvs.apache.org/viewcvs/jakarta-velocity-dvsl/src/stylesheets/site.dvs
l?rev=1.4&content-type=text/vnd.viewcvs-markup.
Since you seem to understand XSLT, DVSL will make more sense to you.
Although it hasn't been released yet, it's been stable for a number of
months.
There is also an XSLT stylesheet included with the Jakarta CVS site2
module (above) that renders similar output to the Jakarta sites which
will be helpful to get you started in transforming xdoc XML. Here it is
in CVS
http://cvs.apache.org/viewcvs/jakarta-site2/xdocs/stylesheets/site.xsl?rev=1
.5&content-type=text/vnd.viewcvs-markup.
> it's of course possible to roll your own xslt to transform xdoc documents.
> it's also possible to use anakia (or maven) and tweak the stylesheets they
> provide. neither of anakia/maven use xslt stylesheets, but velocity to do
> the actual transformation.
I looked through the Maven CVS and then of some projects using Maven but
wasn't able to find exactly what it's using to perform the xdoc
transformation. I did find some DVSL related info but I couldn't tell
if it was using that or something else.
Maven seems to be a rather comprehensive toolset for documenting and
building projects.
-Bill
>
> aslak
>
> -----Original Message-----
> From: [EMAIL PROTECTED]
> [mailto:[EMAIL PROTECTED]]On Behalf Of Ken
> Egervari [eXtremePHP]
> Sent: 12. desember 2002 14:05
> To: [EMAIL PROTECTED]
> Subject: [OS-webwork] xbook
>
>
> I've searched around google and this is the xdoc implementation that I
> found:
>
> http://www.justobjects.org/xbook/
>
> This is the one, correct?
-------------------------------------------------------
This sf.net email is sponsored by:
With Great Power, Comes Great Responsibility
Learn to use your power at OSDN's High Performance Computing Channel
http://hpc.devchannel.org/
_______________________________________________
Opensymphony-webwork mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork
-------------------------------------------------------
This sf.net email is sponsored by:
With Great Power, Comes Great Responsibility
Learn to use your power at OSDN's High Performance Computing Channel
http://hpc.devchannel.org/
_______________________________________________
Opensymphony-webwork mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork
