You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@httpd.apache.org by David Shane Holden <dp...@yahoo.com> on 2002/07/25 22:06:46 UTC
[PATCH] xhtml manual
I've created a patch that gets all the .html and .html.en files in the
manual directory and subdirecties (except mod/... that'll come next) to
successfully validate against the xhtml transitionial dtd.
http://dpejesh.dnsalias.net/patch.txt
Shane
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
RE: Issues with XML / XSLT stuff
Posted by Vincent de Lau <op...@delau.nl>.
> -----Original Message-----
> From: Vincent de Lau [mailto:openoffice@delau.nl]
> Sent: Friday, July 26, 2002 10:26 PM
>
<snip>
> OK. There are two more documents that have to be changed.
>
> mod_rewrite.xml (as mentioned in my previous mailes) uses section elements
> without title.
> -> replaced section elements with blockquote's
> mod_userdir.xml.ja has a problem analogue to mod_userdir.xml
> -> added p element within summary
>
> patch is attached, but I'm not sure if it will apply to
> mod_userdir.xml.ja,
> I had to hack it to get the Japanese characters back in. (cmd.exe or
> diff.exe doesn't like them, I hope SMTP does)
Joshua, is there an issue with this patch or did it slip trough? I can
resend if necessary.
David, did you test you validate rules? Did these documents conform? They
shouldn't at the moment.
Vincent de Lau
vincent@delau.nl
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
RE: Issues with XML / XSLT stuff
Posted by Vincent de Lau <op...@delau.nl>.
> -----Original Message-----
> From: Joshua Slive [mailto:joshua@slive.ca]
> Sent: Friday, July 26, 2002 5:44 PM
>
> On Fri, 26 Jul 2002, Vincent de Lau wrote:
>
> > If my previous patch applied OK, here are two more.
>
> Great. Everything is now committed.
>
OK. There are two more documents that have to be changed.
mod_rewrite.xml (as mentioned in my previous mailes) uses section elements
without title.
-> replaced section elements with blockquote's
mod_userdir.xml.ja has a problem analogue to mod_userdir.xml
-> added p element within summary
patch is attached, but I'm not sure if it will apply to mod_userdir.xml.ja,
I had to hack it to get the Japanese characters back in. (cmd.exe or
diff.exe doesn't like them, I hope SMTP does)
Vincent
Re: Issues with XML / XSLT stuff
Posted by David Shane Holden <dp...@yahoo.com>.
Vincent de Lau wrote:
> Currently the following files are done (more or less):
> - bind.xml (submitted by David, not conforming to DTD)
The attached version should conform now.
Shane
Re: Issues with XML / XSLT stuff
Posted by Joshua Slive <jo...@slive.ca>.
On Sat, 27 Jul 2002, David Shane Holden wrote:
> Joshua Slive wrote:
> >
> > the less people will actually write docs. I know that already some people
> > are frustrated with needing a JVM/etc in order to do the transformations.
>
> I'm using Xalan-C++ which is hella better than the Java version IMO, and a
> makefile for VC nmake to burn through and transform all the files I have
> listed in it.
Actually, I think that in general the Java version is ahead of the C++
version in features and standards compliance, but I don't keep up with the
development so I may be wrong. In any case, we need to stick with the
Java version for the html transformations, because the C++ version does
very nasty things to the Japanese translation.
You can use whatever you want for your own testing/etc, but we need to
standardize on Xalan-Java for the html that gets committed to the docs.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Issues with XML / XSLT stuff
Posted by David Shane Holden <dp...@yahoo.com>.
Joshua Slive wrote:
>
> the less people will actually write docs. I know that already some people
> are frustrated with needing a JVM/etc in order to do the transformations.
I'm using Xalan-C++ which is hella better than the Java version IMO, and a
makefile for VC nmake to burn through and transform all the files I have
listed in it.
> What would be optimal is if we could get Ant/Xalan to validate as part of
> the transformation process, but I can't figure out how to make that
> happen.
Xalan should validate against the dtd if you use the -v switch.
I'm not sure if the Java version is the same.
Shane
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Issues with XML / XSLT stuff
Posted by Erik Abele <er...@codefaktor.de>.
> Von: Joshua Slive <jo...@slive.ca>
> Datum: Sat, 27 Jul 2002 08:13:24 -0700 (PDT)
> Betreff: RE: Issues with XML / XSLT stuff
>
> On Sat, 27 Jul 2002, Joshua Slive wrote:
>
>>> Can you tell I haven't been properly validating my xml ;-)
>
> What would be optimal is if we could get Ant/Xalan to validate as part of
> the transformation process, but I can't figure out how to make that
> happen.
Hi Joshua !
The xml files could easily be validated with a few changes to the build.xml
file. Just insert a new target and let the xslt-target depend on it. For
example:
<target name="validate"
description="Validate the XML source files">
<!-- Validate the root directory of the manual -->
<xmlvalidate lenient="false" failonerror="false" warn="true">
<fileset dir="../"
includes="*.xml *.xml.ja"/>
</xmlvalidate>
<!-- Validate the mod directory (.en + .ja) -->
<xmlvalidate lenient="false" failonerror="false" warn="true">
<fileset dir="../mod/"
includes="*.xml *.xml.ja"/>
</xmlvalidate>
</target>
If you're using the ant logging capabilities there will be a nice output
(even in xml). So the results of the validation/trasformation can be easily
controlled. For example call ant with the following parameters (in
build.sh):
ant -logger org.apache.tools.ant.XmlLogger \
-verbose \
-logfile buildlog.xml \
-Dant.XmlLogger.stylesheet.uri=log.xsl
(this stylesheet can be found in path_to/ant/etc/log.xsl; just copy to
manual/style)
For transforming the resulting logfile to html, you could use the following
in build.sh:
java org.apache.xalan.xslt.Process -IN buildlog.xml \
-OUT buildlog.html
If appreciated I could prepare a complete build-environment for the
validation/transformation/logging - proccess...just let me know if it would
help you.
-erik
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
RE: Issues with XML / XSLT stuff
Posted by Vincent de Lau <vi...@delau.nl>.
> -----Original Message-----
> From: Joshua Slive [mailto:joshua@slive.ca]
> Sent: Saturday, July 27, 2002 5:13 PM
>
> On Sat, 27 Jul 2002, Vincent de Lau wrote:
>
> > > Can you tell I haven't been properly validating my xml ;-)
> >
> > To busy huh? I'm using XML Spy, it warns before saving a
> invalid file or
> > dtd ;)
> > I also have a IE plugin that can validate the XML file you are
> viewing and
> > lets you view the XSLT output.
>
> Interesting. Are either of these free? Where did you find the IE plugin?
XML Spy is not free, but as 30 day evaluation is available. The IE plugins
can be found at MSDN and are free (link most likely wrapped):
http://msdn.microsoft.com/downloads/sample.asp?url=/msdn-files/027/000/543/m
sdncompositedoc.xml
>
> >
> > Questions:
> > 1. How are we going to make sure that committed files are
> valid? I expect a
> > XML rush, now that the DTD's and XSLT's are working. I've seen
> one document
> > already but that was not conforming to the DTD.
>
> The problem is that we want to make writing documentation as easy as
> possible.
trim...
> When the inevitable non-validating doc gets committed, those of us who are
> insterested can fix it.
Maybe a good thing to do: When patches are submitted, the author should tell
if the resulting doc was validated. If he didn't or can't for some reason,
somebody will have to "review" (validate) the patch before commiting. (Ala
translations, bur we asume that when the author says he validated, he did)
> > 2. What is the current status of the build system? STATUS says
> that it is
> > still not 100%. This should probably be fixed asap.
>
> I have made changes to style/build.xml which seem to be working for now.
> Unfortuantely, STATUS always seems to lag a little behind.
Hence I asked ;)
> > 3. How are we going to organise the migration for current documents?
trim...
> I suggest that you just make a quick post to the list before you start
> saying "I'm working on docs x,y,z". That way we are less likely to get
> conflicts.
Agree. Would it be usefull to post a XML STATUS message once a week?
Vincent de Lau
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
RE: Issues with XML / XSLT stuff
Posted by Joshua Slive <jo...@slive.ca>.
On Sat, 27 Jul 2002, Vincent de Lau wrote:
> > Can you tell I haven't been properly validating my xml ;-)
>
> To busy huh? I'm using XML Spy, it warns before saving a invalid file or
> dtd ;)
> I also have a IE plugin that can validate the XML file you are viewing and
> lets you view the XSLT output.
Interesting. Are either of these free? Where did you find the IE plugin?
>
> Questions:
> 1. How are we going to make sure that committed files are valid? I expect a
> XML rush, now that the DTD's and XSLT's are working. I've seen one document
> already but that was not conforming to the DTD.
The problem is that we want to make writing documentation as easy as
possible. The more barriers we throw in the way of getting things done,
the less people will actually write docs. I know that already some people
are frustrated with needing a JVM/etc in order to do the transformations.
What would be optimal is if we could get Ant/Xalan to validate as part of
the transformation process, but I can't figure out how to make that
happen.
Given that, I don't want to insist that people install more new software.
Instead, we should "recommend", but not insist on validating, and we
should make it as easy as possible by suggesting how to do it in the
relevant place: http://httpd.apache.org/docs-project/docsformat.html
When the inevitable non-validating doc gets committed, those of us who are
insterested can fix it.
> 2. What is the current status of the build system? STATUS says that it is
> still not 100%. This should probably be fixed asap.
I have made changes to style/build.xml which seem to be working for now.
Unfortuantely, STATUS always seems to lag a little behind.
> 3. How are we going to organise the migration for current documents?
>
> Currently the following files are done (more or less):
> - bind.xml (submitted by David, not conforming to DTD)
> - configuring.xml (submitted by Astrid, patched by Joshua to test DTD/XSLT)
> - env.xml (will be submitted by me in a different post)
> - filter.xml (will be submitted by me in a different post)
> - handler.xml (will be submitted by me in a different post)
I suggest that you just make a quick post to the list before you start
saying "I'm working on docs x,y,z". That way we are less likely to get
conflicts.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
RE: Issues with XML / XSLT stuff
Posted by Vincent de Lau <op...@delau.nl>.
> Can you tell I haven't been properly validating my xml ;-)
To busy huh? I'm using XML Spy, it warns before saving a invalid file or
dtd ;)
I also have a IE plugin that can validate the XML file you are viewing and
lets you view the XSLT output.
Questions:
1. How are we going to make sure that committed files are valid? I expect a
XML rush, now that the DTD's and XSLT's are working. I've seen one document
already but that was not conforming to the DTD.
2. What is the current status of the build system? STATUS says that it is
still not 100%. This should probably be fixed asap.
3. How are we going to organise the migration for current documents?
Currently the following files are done (more or less):
- bind.xml (submitted by David, not conforming to DTD)
- configuring.xml (submitted by Astrid, patched by Joshua to test DTD/XSLT)
- env.xml (will be submitted by me in a different post)
- filter.xml (will be submitted by me in a different post)
- handler.xml (will be submitted by me in a different post)
Vincent
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
RE: Issues with XML / XSLT stuff
Posted by Joshua Slive <jo...@slive.ca>.
On Fri, 26 Jul 2002, Vincent de Lau wrote:
> Discovered another problem:
>
> DTD specifies a relativepath element, XSLT and configuring.xml use
> relative-path.
>
> This patch fixes the XSLT and XML to use relativepath.
Can you tell I haven't been properly validating my xml ;-)
Patch committed, thanks.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
RE: Issues with XML / XSLT stuff
Posted by Vincent de Lau <op...@delau.nl>.
Discovered another problem:
DTD specifies a relativepath element, XSLT and configuring.xml use
relative-path.
This patch fixes the XSLT and XML to use relativepath.
Vincent de Lau
vincent@delau.nl
RE: Issues with XML / XSLT stuff
Posted by Joshua Slive <jo...@slive.ca>.
On Fri, 26 Jul 2002, Vincent de Lau wrote:
> If my previous patch applied OK, here are two more.
Great. Everything is now committed.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
RE: Issues with XML / XSLT stuff
Posted by Vincent de Lau <vi...@delau.nl>.
If my previous patch applied OK, here are two more.
> -----Original Message-----
> From: Joshua Slive [mailto:joshua@slive.ca]
> Sent: Thursday, July 25, 2002 10:46 PM
>
> On Fri, 26 Jul 2002, Vincent de Lau wrote:
>
> > DTD's
> > -----
> > section/related elements
> > The section element relies on related, which is not in common.dtd.
> > Also, in the current definition, you can have multiple
> related elements
> > within one section.
> > I propose to move the related and directivelist element to
> common.dtd and
> > change the section element to:
>
> Sounds good.
>
> > <!ELEMENT section (title, related?, (section | %blocktags;)*)>
> > This would have the following results on module docs:
> > - enforces title element, which was optional but could occur multiple
> > times
>
> I'm not sure whether or not we want to allow sections without titles. I
> guess we can ban them for now and see how it goes.
>
> > - allows related element to be used
> > I've discovered one page that will not conform after the changes:
mod_rewrite
> > uses a section element to group an image with a caption and does not
use a title element.
>
> That can be fixed.
>
see dtd_fix.patch
> >
> > XSLT
> > ----
> > general
> > common.dtd calls a template for a meta element, which does
> not exist in
> > any DTD or current XML file. Should it be removed?
>
> Yes.
>
> >
> > manualpage
> > The title in the generated page is prepended with 'Apache Module'.
> > Should we change this in 'Apache Manual:' or discard it?
> > Changing it would require an update to all the message files.
>
> Discard. My mistake, certainly.
>
see xslt_fix.patch
Vincent de Lau
vincent@delau.nl
RE: Issues with XML / XSLT stuff
Posted by Vincent de Lau <vi...@delau.nl>.
> > 3 (english) module pages are not conformant to the current DTD:
> > mod_userdir, mod_proxy and mod_echo
> > I haven't checked the Japenese yet.
This patch makes the above XML files conformant to the current DTD. Please
let me know if there are problems with the patch, I might have to
reconfigure my WinCVS setup.
Vincent de Lau
vincent@delau.nl
Re: Issues with XML / XSLT stuff
Posted by Joshua Slive <jo...@slive.ca>.
On Fri, 26 Jul 2002, Vincent de Lau wrote:
> DTD's
> -----
> section/related elements
> The section element relies on related, which is not in common.dtd.
> Also, in the current definition, you can have multiple related elements
> within one section.
> I propose to move the related and directivelist element to common.dtd and
> change the section element to:
Sounds good.
> <!ELEMENT section (title, related?, (section | %blocktags;)*)>
> This would have the following results on module docs:
> - enforces title element, which was optional but could occur multiple
> times
I'm not sure whether or not we want to allow sections without titles. I
guess we can ban them for now and see how it goes.
> - allows related element to be used
> I've discovered one page that will not conform after the changes:
> mod_rewrite
> uses a section element to group an image with a caption and does not use a
> title
> element.
That can be fixed.
>
> message files
> Would it be usefull to have these documents conforming to a DTD?
I don't think it is worth the effort. They are really just a utility
thing to make the xslt work better.
>
> XSLT
> ----
> general
> common.dtd calls a template for a meta element, which does not exist in
> any DTD or current XML file. Should it be removed?
Yes.
>
> manualpage
> The title in the generated page is prepended with 'Apache Module'.
> Should we change this in 'Apache Manual:' or discard it?
> Changing it would require an update to all the message files.
Discard. My mistake, certainly.
>
> XML
> ---
> 3 (english) module pages are not conformant to the current DTD: mod_userdir,
> mod_proxy and mod_echo
> I haven't checked the Japenese yet.
>
> If there is consensus about these issues, I'll send patches and new files to
> the list.
Sounds good.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Issues with XML / XSLT stuff
Posted by Vincent de Lau <vi...@delau.nl>.
Dear all,
I've been looking at the XML / XSLT stuff for manual pages. These are the
issues encountered so far:
DTD's
-----
section/related elements
The section element relies on related, which is not in common.dtd.
Also, in the current definition, you can have multiple related elements
within one section.
I propose to move the related and directivelist element to common.dtd and
change the section element to:
<!ELEMENT section (title, related?, (section | %blocktags;)*)>
This would have the following results on module docs:
- enforces title element, which was optional but could occur multiple
times
- allows related element to be used
I've discovered one page that will not conform after the changes:
mod_rewrite
uses a section element to group an image with a caption and does not use a
title
element.
message files
Would it be usefull to have these documents conforming to a DTD?
XSLT
----
general
common.dtd calls a template for a meta element, which does not exist in
any DTD or current XML file. Should it be removed?
manualpage
The title in the generated page is prepended with 'Apache Module'.
Should we change this in 'Apache Manual:' or discard it?
Changing it would require an update to all the message files.
XML
---
3 (english) module pages are not conformant to the current DTD: mod_userdir,
mod_proxy and mod_echo
I haven't checked the Japenese yet.
If there is consensus about these issues, I'll send patches and new files to
the list.
Vincent de Lau
vincent@delau.nl
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [PATCH] xhtml manual
Posted by David Shane Holden <dp...@yahoo.com>.
Rich Bowen wrote:
>
> Oh, I'm sorry, I completely misread your note.
>
No worries.
Shane
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [PATCH] xhtml manual
Posted by Rich Bowen <rb...@rcbowen.com>.
On Thu, 25 Jul 2002, Rich Bowen wrote:
> > From the looks of it, that's only relevant to the mod directory which is
> > why I haven't touched it yet. If I'm wrong, where's the xml files for all
> > the others?
>
> Oh, I'm sorry, I completely misread your note.
Patch reviewed and applied. Naturally, the patches to htaccess.html all
failed, because I've been working on that all day. But I'm pretty sure
it is already valid xhtml, as I have been running w3c tidy -asxml on it.
--
Nothing is perfekt. Certainly not me.
Success to failure. Just a matter of degrees.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [PATCH] xhtml manual
Posted by Rich Bowen <rb...@rcbowen.com>.
On Thu, 25 Jul 2002, David Shane Holden wrote:
>
> Rich Bowen wrote:
> > On Thu, 25 Jul 2002, David Shane Holden wrote:
> >
> >
> >>I've created a patch that gets all the .html and .html.en files in the
> >>manual directory and subdirecties (except mod/... that'll come next) to
> >>successfully validate against the xhtml transitionial dtd.
> >>
> >>http://dpejesh.dnsalias.net/patch.txt
> >
> >
> > This is appreciated, but it needs to be fixed in the xml->html coversion
> > stuff, not in the html files, because it will just get overwritten the
> > next time we do a conversion.
> >
>
> From the looks of it, that's only relevant to the mod directory which is
> why I haven't touched it yet. If I'm wrong, where's the xml files for all
> the others?
Oh, I'm sorry, I completely misread your note.
--
Pilgrim, how you journey on the road you chose
To find out where the winds die and where the stories go
--Pilgrim (Enya - A Day Without Rain)
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [PATCH] xhtml manual
Posted by Joshua Slive <jo...@slive.ca>.
On Thu, 25 Jul 2002, David Shane Holden wrote:
> From the looks of it, that's only relevant to the mod directory which is
> why I haven't touched it yet. If I'm wrong, where's the xml files for all
> the others?
You are correct. We are just starting on the rest.
I think it is probably worth committing this, since we won't have the rest
of the docs converted overnight. I'll get to it tommorrow if I can. If
anyone else has time to review and commit, please feel free.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [PATCH] xhtml manual
Posted by David Shane Holden <dp...@yahoo.com>.
Rich Bowen wrote:
> On Thu, 25 Jul 2002, David Shane Holden wrote:
>
>
>>I've created a patch that gets all the .html and .html.en files in the
>>manual directory and subdirecties (except mod/... that'll come next) to
>>successfully validate against the xhtml transitionial dtd.
>>
>>http://dpejesh.dnsalias.net/patch.txt
>
>
> This is appreciated, but it needs to be fixed in the xml->html coversion
> stuff, not in the html files, because it will just get overwritten the
> next time we do a conversion.
>
From the looks of it, that's only relevant to the mod directory which is
why I haven't touched it yet. If I'm wrong, where's the xml files for all
the others?
Shane
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [PATCH] xhtml manual
Posted by Rich Bowen <rb...@rcbowen.com>.
On Thu, 25 Jul 2002, David Shane Holden wrote:
> I've created a patch that gets all the .html and .html.en files in the
> manual directory and subdirecties (except mod/... that'll come next) to
> successfully validate against the xhtml transitionial dtd.
>
> http://dpejesh.dnsalias.net/patch.txt
This is appreciated, but it needs to be fixed in the xml->html coversion
stuff, not in the html files, because it will just get overwritten the
next time we do a conversion.
--
Who can say where the road goes
Where the day flows
Only time
--Pilgrim (Enya - A Day Without Rain)
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org