You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by "Craig R. McClanahan" <cr...@apache.org> on 2001/08/06 22:46:22 UTC
[DOC] New Document Tree - Update
My CVS commit message bounced (>100k), but I have converted the existing
"functional specs" documents (under catalina/docs/dev/xdocs) into the new
document format. I also added Rob's initial "introduction" document so
people can see how it fits in with what we've got so far. A snapshot of
the current doc tree (new format) is:
http://jakarta.apache.org/tomcat/tomcat-4.0-doc/exp/
If you are using the jakarta-tomcat-4.0 source repository, you will also
note that I modified the way that the XSLT stylesheet is processed. The
"conventional" approach to having a "project.xml" file loaded inside the
stylesheet is just not very scalable, because the filename is interpreted
relative to where the stylesheet is, not where the related documents are.
To get around this, I modified the pages in tomcat-docs to insert the
project.xml file directly in each page:
<?xml version="1.0"?>
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document>
&project;
...
</document>
At the moment, the stylesheet being used is actually in the tomcat-docs
top-level directory (and referenced globally so that there's only one
place to make changes. Ultimately, this stylesheet should live somewhere
separately if it is going to be shared -- but there's a bug in the <style>
tag of Ant 1.3 that *always* treats the path to the stylesheet as
relative, even if you try to use an absolute one. This is supposed to be
fixed in Ant 1.4.
Craig
RE: [DOC] New Document Tree - Update
Posted by "Rob S." <rs...@home.com>.
Responding to the check-in comments (re: introduction.xml)
- There were several incomplete paragraphs at the bottom, so I took a
few liberties at completing them.
>>> Yeah it was really late and I was leaving for south florida for several
days. I actually planned on completing them, I was just looking for
feedback to make sure I was on the right track before spending the time to
do it. I certainly did not plan on adding to your workload as it decreases
the chance that any of my docs will get proofread and criticized in a timely
manner ;)
- Given the way that the overall document tree takes shape, the content
of this file needs to be reviewed.For example, the "terminology"
section will probably deserve its own page, while the rehash of the
directory structure is probably redundant with the contents of the
"README.txt" file.
>>> The directory structure rehash is only to point out the majority of the
directories that an "average"(?) user would run across in getting Tomcat
going. For a web-app developer or server admin who hasn't used it before,
knowing a bit more than what's provided in the README.txt about /webapps,
/conf (only if there's a port conflict), and /bin is probably sufficient to
get their app up and going.
Re: terminology, I guess it depends on what we shoot for. I thought that
this, like the previous directory section, would be a scaled-down chunk of a
whole glossary, only highlighting a few that should be known by everyone
right off the bat.
As if it wasn't obvious enough, I don't have any formal training or
experience in writing technical documentation. All I can do is write taking
into account things that I and the teams of people I've worked with who use
TC would/have needed at different times, as well as questions I've seen on
the -user list, and hope that it helps ;)
- r
> -----Original Message-----
> From: Craig R. McClanahan [mailto:craigmcc@apache.org]
> Sent: Monday, August 06, 2001 4:46 PM
> To: tomcat-dev@jakarta.apache.org
> Subject: [DOC] New Document Tree - Update
>
>
> My CVS commit message bounced (>100k), but I have converted the existing
> "functional specs" documents (under catalina/docs/dev/xdocs) into the new
> document format. I also added Rob's initial "introduction" document so
> people can see how it fits in with what we've got so far. A snapshot of
> the current doc tree (new format) is:
>
> http://jakarta.apache.org/tomcat/tomcat-4.0-doc/exp/
>
> If you are using the jakarta-tomcat-4.0 source repository, you will also
> note that I modified the way that the XSLT stylesheet is processed. The
> "conventional" approach to having a "project.xml" file loaded inside the
> stylesheet is just not very scalable, because the filename is interpreted
> relative to where the stylesheet is, not where the related documents are.
>
> To get around this, I modified the pages in tomcat-docs to insert the
> project.xml file directly in each page:
>
> <?xml version="1.0"?>
> <!DOCTYPE document [
> <!ENTITY project SYSTEM "project.xml">
> ]>
> <document>
>
> &project;
>
> ...
>
> </document>
>
> At the moment, the stylesheet being used is actually in the tomcat-docs
> top-level directory (and referenced globally so that there's only one
> place to make changes. Ultimately, this stylesheet should live somewhere
> separately if it is going to be shared -- but there's a bug in the <style>
> tag of Ant 1.3 that *always* treats the path to the stylesheet as
> relative, even if you try to use an absolute one. This is supposed to be
> fixed in Ant 1.4.
>
> Craig
>
>
>
RE: [DOC] New Document Tree - Update
Posted by "Rob S." <rs...@home.com>.
> I have the following (and it works):
> * No CLASSPATH at all
Check
> * $ANT_HOME/bin on my PATH (for Ant 1.3)
Check
> * In $ANT_HOME/lib, added the appropriate optional.jar file
Check (the one that's in the 1.3 dist dir)
> * In $ANT_HOME/lib, replaced the JAXP/1.0 parser (jaxp.jar and parser.jar)
> with the JAXP/1.1 files (jaxp.jar, crimson.jar, xalan.jar)
Check
Hmm... is it a problem that the parser has to see a URL there?
- r
RE: [DOC] New Document Tree - Update
Posted by "Craig R. McClanahan" <cr...@apache.org>.
On Wed, 8 Aug 2001, Rob S. wrote:
> > To get around this, I modified the pages in tomcat-docs to insert the
> > project.xml file directly in each page:
>
> I have a feeling I'm making some kind of boneheaded mistake here, but when I
> check out the new stuff and run it, I get:
>
> \tomcat-docs\build.xml:101: javax.xml.transform.TransformerException:
> java.net.MalformedURLException: no protocol: project.xml
>
> It wants a URL there, but the XML spec says that it doesn't need to - re:
> Section 4.2. f00k! Pointers anyone?
>
How is your development environment set up?
I have the following (and it works):
* No CLASSPATH at all
* $ANT_HOME/bin on my PATH (for Ant 1.3)
* In $ANT_HOME/lib, added the appropriate optional.jar file
* In $ANT_HOME/lib, replaced the JAXP/1.0 parser (jaxp.jar and parser.jar)
with the JAXP/1.1 files (jaxp.jar, crimson.jar, xalan.jar)
and it worked ok for me.
> - r
>
>
Craig
RE: [DOC] New Document Tree - Update
Posted by "Rob S." <rs...@home.com>.
> To get around this, I modified the pages in tomcat-docs to insert the
> project.xml file directly in each page:
I have a feeling I'm making some kind of boneheaded mistake here, but when I
check out the new stuff and run it, I get:
\tomcat-docs\build.xml:101: javax.xml.transform.TransformerException:
java.net.MalformedURLException: no protocol: project.xml
It wants a URL there, but the XML spec says that it doesn't need to - re:
Section 4.2. f00k! Pointers anyone?
- r