You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@httpd.apache.org by Joshua Slive <jo...@slive.ca> on 2002/02/14 02:37:17 UTC
xml module docs (it happened)
I just committed the first go at an xml transformation system for the
module docs. I should have mentioned in the commit message that I didn't
invent all this myself. The inspiration and much of the code comes from
jakarta-site2, and mainly Jon Stevens and Craig McClanahan.
The documentation for the new system is at
http://httpd.apache.org/docs-project/docsformat.html
Note that, although we do need a full-blown xml transformation system to
create the html docs for final distribution, you don't need one just to
view or work on the docs. For example, view
http://httpd.apache.org/docs-2.0/mod/mod_setenvif.xml
in any recent browser, and you should see the transformed xml with
stylesheet applied.
So, now I could use some help. In particular, each of the module docs
needs to be converted to the new format. This shouldn't be too difficult,
because Rich and others have already done the work of making all the docs
xhtml. All you need to do is grab mod_something.html, and using
mod_setenvif.xml as an example, plus the docs referenced above, change
it into the new format. This is a great job for anyone out there looking
for something to do. You don't need commit access; just post to the
mailing list telling us what you're working on.
Also, feel free to hack on the manual.xsl and other build files. What I
did certainly qualifies as a hack job. The XSL stuff might look
intimidating, but it only takes a little time to figure out what is going
on. (And a google search for "xsl reference" or "xsl tutorial" will find
plenty of good stuff.)
Joshua. (Always the optimist.)
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: xml module docs (it happened)
Posted by Astrid Keßler <ke...@kess-net.de>.
Hi Joshua,
> The documentation for the new system is at
> http://httpd.apache.org/docs-project/docsformat.html
why didn't you post this one or two weeks earlier? :-)
I'm trying the german translation (version 2 only) and have now to
restructure all the documents already done. Not if these were so
much. ;-)
(When ready with a couple of them giving you and the other german
natural speakers the possibility to check the quality, I'll post my
translation here.)
But I'm working top-down. And when converting for example index.html
I have some difficulty to choose the correct element. Are there also
examples for non modul documentiation pages?
Kess
E-Mail: kess@kess-net.de
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: xml module docs (it happened)
Posted by Rich Bowen <rb...@rcbowen.com>.
On Sat, 16 Feb 2002, Rich Bowen wrote:
> I started on mod_include, which now seems like a rather aggressive one
> to start with, as it is kinda big. But I'll try to get it working.
FTR, I think I did indeed bite off too much for a first try. I'm trying
mod_info as my first go, and then I'll move on to bigger things.
--
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
Re: xml module docs (it happened)
Posted by Joshua Slive <jo...@slive.ca>.
On Sat, 16 Feb 2002, Rich Bowen wrote:
> The only think that I have run into so far is <pre>, which was not
> listed in your list of xhtml tags I can use, but is used in a lot of
> examples for formatting. Is <example> automatically a preformatted
> environment?
I was being a little evasive on that one. <example> is deliberately NOT
preformatted. In general, rendering seems to work much better when we
avoid using <pre> sections. It prevents lots of problems with page-flow,
and makes stylesheets easier. However, <pre> is used extensively in the
docs, and can save a bunch of time. So, feel free to use <example><pre>
... </pre></example> if you need to.
Perhaps I should add a list of "discouraged but allowed" tags. The main
goal here is not to make things too difficult.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: xml module docs (it happened)
Posted by Joshua Slive <jo...@slive.ca>.
On Sat, 16 Feb 2002, Rich Bowen wrote:
>
> Adding a text/xml mime type for .xsl files corrects the problem.
>
Yep, I forgot about that. That is what httpd.apache.org sends.
Perhaps I should doc this somewhere.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: xml module docs (it happened)
Posted by Rich Bowen <rb...@rcbowen.com>.
On Sat, 16 Feb 2002, Rich Bowen wrote:
> On Sat, 16 Feb 2002, Joshua Slive wrote:
>
> >
> > On Sat, 16 Feb 2002, Rich Bowen wrote:
> >
> > > On Wed, 13 Feb 2002, Joshua Slive wrote:
> > > > http://httpd.apache.org/docs-2.0/mod/mod_setenvif.xml
> > > While this looks great loading off of httpd.apache.org, it looks like
> > > crap when loaded off of my laptop. Is there some configuration change
> > > that needs to be made, such as a mime-type setting, to get this to
> > > format correctly? I am at the moment running 1.3.something on my laptop.
> > > Is that likely to be the source of the problem?
> >
> > Hmmm... httpd.apache.org is sending it as text/xml. Can you see what your
> > laptop is doing?
>
> text/xml for the xml file itself. What about the xsl file?
Adding a text/xml mime type for .xsl files corrects the problem.
--
Rich Bowen - rbowen@rcbowen.com
... and another brother out of his mind, and another brother out at New
York (not the same, though it might appear so)
Somebody's Luggage (Charles Dickens)
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: xml module docs (it happened)
Posted by Rich Bowen <rb...@rcbowen.com>.
On Sat, 16 Feb 2002, Joshua Slive wrote:
>
> On Sat, 16 Feb 2002, Rich Bowen wrote:
>
> > On Wed, 13 Feb 2002, Joshua Slive wrote:
> > > http://httpd.apache.org/docs-2.0/mod/mod_setenvif.xml
> > While this looks great loading off of httpd.apache.org, it looks like
> > crap when loaded off of my laptop. Is there some configuration change
> > that needs to be made, such as a mime-type setting, to get this to
> > format correctly? I am at the moment running 1.3.something on my laptop.
> > Is that likely to be the source of the problem?
>
> Hmmm... httpd.apache.org is sending it as text/xml. Can you see what your
> laptop is doing?
text/xml for the xml file itself. What about the xsl file?
> > I started on mod_include, which now seems like a rather aggressive one
> > to start with, as it is kinda big. But I'll try to get it working.
>
> Yes, it is a bigger project than I imagined. But it certainly does not
> need to be done all at once. We can convert files over the course of
> several months. Some of the fun stuff (like automatic generation of index
> pages) won't work until all the modules are done, of course.
>
> If you see things about the xml format that don't make sense, please let
> me know. It is easy enough to change now, but will of course be harder
> later (though certainly not impossible).
>
> For example, I know that we probably should have tags for <replaceable>,
> instead of using <em> for things like <em>filename</em>, but I didn't
> bother. Another one is inline example. Anyway, other opinions are
> welcome.
The only think that I have run into so far is <pre>, which was not
listed in your list of xhtml tags I can use, but is used in a lot of
examples for formatting. Is <example> automatically a preformatted
environment?
--
And everyone said, "If we only live,
We too will go to sea in a Sieve -
To the hills of the Chankly Bore!"
(The Jumblies, by Edward Lear)
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: xml module docs (it happened)
Posted by Joshua Slive <jo...@slive.ca>.
On Sat, 16 Feb 2002, Rich Bowen wrote:
> On Wed, 13 Feb 2002, Joshua Slive wrote:
> > http://httpd.apache.org/docs-2.0/mod/mod_setenvif.xml
> While this looks great loading off of httpd.apache.org, it looks like
> crap when loaded off of my laptop. Is there some configuration change
> that needs to be made, such as a mime-type setting, to get this to
> format correctly? I am at the moment running 1.3.something on my laptop.
> Is that likely to be the source of the problem?
Hmmm... httpd.apache.org is sending it as text/xml. Can you see what your
laptop is doing?
> I started on mod_include, which now seems like a rather aggressive one
> to start with, as it is kinda big. But I'll try to get it working.
Yes, it is a bigger project than I imagined. But it certainly does not
need to be done all at once. We can convert files over the course of
several months. Some of the fun stuff (like automatic generation of index
pages) won't work until all the modules are done, of course.
If you see things about the xml format that don't make sense, please let
me know. It is easy enough to change now, but will of course be harder
later (though certainly not impossible).
For example, I know that we probably should have tags for <replaceable>,
instead of using <em> for things like <em>filename</em>, but I didn't
bother. Another one is inline example. Anyway, other opinions are
welcome.
And please, if anyone out there is lurking and wants to help out, please
let us know.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: xml module docs (it happened)
Posted by Rich Bowen <rb...@rcbowen.com>.
On Wed, 13 Feb 2002, Joshua Slive wrote:
> Note that, although we do need a full-blown xml transformation system to
> create the html docs for final distribution, you don't need one just to
> view or work on the docs. For example, view
> http://httpd.apache.org/docs-2.0/mod/mod_setenvif.xml
> in any recent browser, and you should see the transformed xml with
> stylesheet applied.
While this looks great loading off of httpd.apache.org, it looks like
crap when loaded off of my laptop. Is there some configuration change
that needs to be made, such as a mime-type setting, to get this to
format correctly? I am at the moment running 1.3.something on my laptop.
Is that likely to be the source of the problem?
> So, now I could use some help. In particular, each of the module docs
> needs to be converted to the new format. This shouldn't be too difficult,
> because Rich and others have already done the work of making all the docs
> xhtml. All you need to do is grab mod_something.html, and using
> mod_setenvif.xml as an example, plus the docs referenced above, change
> it into the new format. This is a great job for anyone out there looking
> for something to do. You don't need commit access; just post to the
> mailing list telling us what you're working on.
I started on mod_include, which now seems like a rather aggressive one
to start with, as it is kinda big. But I'll try to get it working.
--
Rich Bowen - rbowen@rcbowen.com
Author - Apache Administrator's Guide
http://www.ApacheAdmin.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: xml module docs (it happened)
Posted by Joshua Slive <jo...@slive.ca>.
On Fri, 1 Mar 2002, Rich Bowen wrote:
> On Fri, 1 Mar 2002, Rich Bowen wrote:
>
> > On Wed, 13 Feb 2002, Joshua Slive wrote:
> >
> > > I just committed the first go at an xml transformation system for the
> > > module docs. I should have mentioned in the commit message that I didn't
> > > invent all this myself. The inspiration and much of the code comes from
> > > jakarta-site2, and mainly Jon Stevens and Craig McClanahan.
> > >
> > > The documentation for the new system is at
> > > http://httpd.apache.org/docs-project/docsformat.html
> >
> > OK, question. I create a <section></section> with a <title></title>. How
> > do I then link to that section from elsewhere in the doc? From anohter
> > doc?
>
> Next question. Can I nest sections? (Subsections)
<section id="hereiam"><title>lala</title>...
should create the appropriate <a href="#hereiam">reference</a>.
Yes, sections can be nested. Main sections get <h2> and nested ones get
<h3> at the moment.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: xml module docs (it happened)
Posted by Rich Bowen <rb...@rcbowen.com>.
On Fri, 1 Mar 2002, Rich Bowen wrote:
> On Wed, 13 Feb 2002, Joshua Slive wrote:
>
> > I just committed the first go at an xml transformation system for the
> > module docs. I should have mentioned in the commit message that I didn't
> > invent all this myself. The inspiration and much of the code comes from
> > jakarta-site2, and mainly Jon Stevens and Craig McClanahan.
> >
> > The documentation for the new system is at
> > http://httpd.apache.org/docs-project/docsformat.html
>
> OK, question. I create a <section></section> with a <title></title>. How
> do I then link to that section from elsewhere in the doc? From anohter
> doc?
Next question. Can I nest sections? (Subsections)
--
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
Re: xml module docs (it happened)
Posted by Rich Bowen <rb...@rcbowen.com>.
On Wed, 13 Feb 2002, Joshua Slive wrote:
> I just committed the first go at an xml transformation system for the
> module docs. I should have mentioned in the commit message that I didn't
> invent all this myself. The inspiration and much of the code comes from
> jakarta-site2, and mainly Jon Stevens and Craig McClanahan.
>
> The documentation for the new system is at
> http://httpd.apache.org/docs-project/docsformat.html
OK, question. I create a <section></section> with a <title></title>. How
do I then link to that section from elsewhere in the doc? From anohter
doc?
--
Rich Bowen
Apache - mod_perl - Perl - CGI
http://www.ApacheAdmin.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org