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/19 19:46:00 UTC
xml module docs
If you monitor the CVS list, you have by now noticed that we are converting
the apache module docs (ie, the reference manual part of the docs) to xml.
I just committed for the first time the xslt transformation into cvs. I did
this to assure that we don't need to maintain two sets of module docs in
2.0.
Now, to edit module docs, first check if there is both an .xml and .html
file. If there is only .html, then just edit the html as usual. If there
is an .xml file, then don't edit the .html file, because it is generated
from the .xml.
Instructions on how to deal with the .xml are here:
http://httpd.apache.org/docs-project/docsformat.html
Note that, although the final .xml file will need to be transformed to
.html, you don't need a full transformation setup to edit the docs and check
your works. Recent versions of MSIE, Mozilla, and Netscape will render the
xml directly with the xsl stylesheet if you request the .xml in your
browser.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: xml module docs
Posted by Eli Marmor <ma...@netmask.it>.
P.S.
[please don't flame - just a crazy idea that may improve the procedure
of parsing configuration directives]
The next step, may be to start (incrementally) to port modules to a new
model - where these XML files are used for the first phase of reading
directives (mainly their parsing).
Of course, the semantics and logics of applying the config directives
(after reading and parsing them), will remain the same as today.
Since a backword compatibility will be kept temporarily, this step will
not be painful. This is like ap_set_..._slot: You can always use the
less automatic way, and define your own function.
--
Eli Marmor
marmor@netmask.it
CTO, Founder
Netmask (El-Mar) Internet Technologies Ltd.
__________________________________________________________
Tel.: +972-9-766-1020 8 Yad-Harutzim St.
Fax.: +972-9-766-1314 P.O.B. 7004
Mobile: +972-50-23-7338 Kfar-Saba 44641, Israel
Re: xml module docs
Posted by Eli Marmor <ma...@netmask.it>.
P.S.
[please don't flame - just a crazy idea that may improve the procedure
of parsing configuration directives]
The next step, may be to start (incrementally) to port modules to a new
model - where these XML files are used for the first phase of reading
directives (mainly their parsing).
Of course, the semantics and logics of applying the config directives
(after reading and parsing them), will remain the same as today.
Since a backword compatibility will be kept temporarily, this step will
not be painful. This is like ap_set_..._slot: You can always use the
less automatic way, and define your own function.
--
Eli Marmor
marmor@netmask.it
CTO, Founder
Netmask (El-Mar) Internet Technologies Ltd.
__________________________________________________________
Tel.: +972-9-766-1020 8 Yad-Harutzim St.
Fax.: +972-9-766-1314 P.O.B. 7004
Mobile: +972-50-23-7338 Kfar-Saba 44641, Israel
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: xml module docs
Posted by Eli Marmor <ma...@netmask.it>.
It looks great for Apache configuration GUI developers.
Even before teaching their tool about the specific directives and their
parameters, they already have an initial automatic support.
However, it will be useless without adoption by independent module
developers (PHP, mod_perl, etc.).
Is there any way to "encourage" them to use it?
You may argue and claim that there is no chance to cause module
developers/maintainers to adopt this format, but a similar try already
succeeded: Sun succeeded to convince Java developers to use JavaDoc, so
today most of the Java sources have a (minimal) automatic
documentation.
I don't see any reason why it can't succeed in this case too.
Joshua Slive wrote:
> If you monitor the CVS list, you have by now noticed that we are converting
> the apache module docs (ie, the reference manual part of the docs) to xml.
> I just committed for the first time the xslt transformation into cvs. I did
> this to assure that we don't need to maintain two sets of module docs in
> 2.0.
>
> Now, to edit module docs, first check if there is both an .xml and .html
> file. If there is only .html, then just edit the html as usual. If there
> is an .xml file, then don't edit the .html file, because it is generated
> from the .xml.
>
> Instructions on how to deal with the .xml are here:
> http://httpd.apache.org/docs-project/docsformat.html
>
> Note that, although the final .xml file will need to be transformed to
> .html, you don't need a full transformation setup to edit the docs and check
> your works. Recent versions of MSIE, Mozilla, and Netscape will render the
> xml directly with the xsl stylesheet if you request the .xml in your
> browser.
--
Eli Marmor
marmor@netmask.it
CTO, Founder
Netmask (El-Mar) Internet Technologies Ltd.
__________________________________________________________
Tel.: +972-9-766-1020 8 Yad-Harutzim St.
Fax.: +972-9-766-1314 P.O.B. 7004
Mobile: +972-50-23-7338 Kfar-Saba 44641, Israel
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: xml module docs
Posted by Eli Marmor <ma...@netmask.it>.
It looks great for Apache configuration GUI developers.
Even before teaching their tool about the specific directives and their
parameters, they already have an initial automatic support.
However, it will be useless without adoption by independent module
developers (PHP, mod_perl, etc.).
Is there any way to "encourage" them to use it?
You may argue and claim that there is no chance to cause module
developers/maintainers to adopt this format, but a similar try already
succeeded: Sun succeeded to convince Java developers to use JavaDoc, so
today most of the Java sources have a (minimal) automatic
documentation.
I don't see any reason why it can't succeed in this case too.
Joshua Slive wrote:
> If you monitor the CVS list, you have by now noticed that we are converting
> the apache module docs (ie, the reference manual part of the docs) to xml.
> I just committed for the first time the xslt transformation into cvs. I did
> this to assure that we don't need to maintain two sets of module docs in
> 2.0.
>
> Now, to edit module docs, first check if there is both an .xml and .html
> file. If there is only .html, then just edit the html as usual. If there
> is an .xml file, then don't edit the .html file, because it is generated
> from the .xml.
>
> Instructions on how to deal with the .xml are here:
> http://httpd.apache.org/docs-project/docsformat.html
>
> Note that, although the final .xml file will need to be transformed to
> .html, you don't need a full transformation setup to edit the docs and check
> your works. Recent versions of MSIE, Mozilla, and Netscape will render the
> xml directly with the xsl stylesheet if you request the .xml in your
> browser.
--
Eli Marmor
marmor@netmask.it
CTO, Founder
Netmask (El-Mar) Internet Technologies Ltd.
__________________________________________________________
Tel.: +972-9-766-1020 8 Yad-Harutzim St.
Fax.: +972-9-766-1314 P.O.B. 7004
Mobile: +972-50-23-7338 Kfar-Saba 44641, Israel