STATUS of the Apache Documentation Project (ADP)
================================================
The current ADP Team:
---------------------
(Just jump up and say you want to contribute!)
Ralf S. Engelschall <rse@engelschall.com> (coordinator)
Stanley Gambarin <stanleyg@cs.bu.edu>
Christopher Huber <chrish@wired.com>
Brian Slesinsky <bslesins@wired.com>
Mark A. Imbriaco <mark@itribe.net>
Ken Coar <coar@decus.org>
Julie Petersen <juliep@atomicvision.com>
Goal of the project:
--------------------
(Feel free to fix me)
1. Write an Apache Handbook which includes a reference of all config
directives and modules in addition to a complete reference of the general
functionality of Apache and the developer guidelines.
Sources:
- apache/htdocs/* = http://www.apache.org/docs/
- apache-site/* = http://www.apache.org/
- apache-devsite/* = http://dev.apache.org/
Target formats:
- essential: HTML (portable online-browsing)
- essential: Postscript (printing to paper)
- nice: Windows Help File Format (online-browsing on Windows)
- optional: plain ASCII (for Vi-readers ;_)
- optional: PDF (for crunched printing source with hyperlinks).
Target readers:
- webmasters who have to install/configure Apache
- Apache developers
2. Write an Apache User Manual which is a tutorial-like description of
Apache, i.e. it summarizes typical configuration tasks and practical
solutions for the avarage user.
Sources:
- apache/htdocs/* = http://www.apache.org/docs/
- apache-site/* = http://www.apache.org/
- ApacheWeek = http://www.apacheweek.com/
- Stronghold docs = http://www.c2.net/products/stronghold/docs/
Target formats:
- essential: HTML (portable online-browsing)
- essential: Windows Help File Format (online-browsing on Windows)
- essential: Postscript (printing to paper)
- optional: plain ASCII (for Vi-readers ;_)
- optional: PDF (for crunched printing source with hyperlinks).
Target readers:
- advanced users who work under Apache
- avarage webmasters who have to configure Apache
2. Write an Apache FAQ which includes questions & answers of any
topics interested to the impatient reader.
Sources:
- apache/htdocs/manual/misc/FAQ =
http://www.apache.org/docs/manual/misc/FAQ
- ApacheWeek tutorials = http://www.apacheweek.com/
Target formats:
- esstential: news.answers-ready message-digest TXT format (for USENET!!)
- esstential: HTML (portable online-browsing)
- nice: Windows Help File Format (online-browsing on Windows)
- nice: Postscript (printing to paper)
- optional: plain ASCII (for Vi-readers ;_)
- optional: PDF (for crunched printing source with hyperlinks).
Current state:
--------------
I've started to write an initial skeleton for the handbook by the use of
SGML-Tools. This was done to be sure SGML-Tools really is an acceptable
approach. But we are not sure, because SDF is also an alternative. Current
test handbook can be found on http://www.apache.org/~rse/.
Current Points of Discussion:
-----------------------------
(Feel free to add your votes and ideas!)
o Decision on the used markup tool:
=================================
Status: SGMLTools with LinuxDOC-DTD worked
fine for the initial handbook skeleton
and is also used for Linux HOWTOs and
FreeBSD Handbook.
But SDF is an alternative!
Options:
- linuxdoc-sgml 1.5
ftp://sunsite.unc.edu/pub/Linux/...
=> The predecessor of SGMLTools
Votes: RSE -1 (because obsolete)
- FreeBSD's sgmlfmt
ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/...
=> Based on linuxdoc-sgml 1.4/1.5 with
enhancements.
Votes: RSE -1 (because SGMLTools is still better)
- SGMLTools 0.99.14
http://web.inter.NL.net/users/C.deGroot/sgmltools/
=> Provides an SGML-based approach and can
directly generate HTML, TXT and TeX (->Postscript).
Easy syntax because very related to HTML which
every contributor already knows.
Votes: RSE +1 (because currently best tool for SGML approach)
Stanley Gambarin +1 (if and only if .hlp can be
created, too with this approach)
- Perl's Plain Old Document (POD) Format
perl5.004_01.tar.gz:pod/pod2html
=>
Votes: RSE -0 (because not powerful enough: images, etc.)
- Simple Document Format (SDF)
http://www.mincom.com/mtr/sdf/
=> Successor of POD. Leads to very compact source
(especially for lists) in contrast to the SGML approaches.
Works really nice and can be enhanced to fit out needs.
Very easy syntax (similar to POD), but not related
to HTML.
Votes: RSE +1 iff(!) the author Ian Clatworthy
enhances SDF in the following ways:
1. all of our needed features possible
with all of our needed output formats
2. output format Postscript directly
creatable via TeX as the postprocessor
instead of FrameMaker or WinWord.
Ian says he tries to do this enhancements
until the end of the next week. We should
give him a chance!
[.Wed Aug 13: Still waiting for a response
of Ian Clatworthy !!]
Stanley Gambarin +1 (if there is no way to
generate .hlp with SGMLTools)
- eXtensible Markup Language (XML)
(one starting point: http://www.textuality.com/xml/)
=> Alternative to SGML, because some kind of
subset of SGML. Easier then SGML. But
1. When using a easy DTD, SGML is easy too.
2. There are currently not good enough tools for XML.
There are only some precessors/parsers but no
really powerful backends.
3. Currently not a final standard, while SGML is.
Votes: RSE -0 because needs a few years more to be acceptable
- ...???ANY MORE???...
o Decision how to work on ADP as a group
======================================
Status: A CVS area apache-docs can be easily created,
so every contributor can at least grab the stuff via
Anonymous-CVS (when done in the near future) to grab the latest
release. Changes are sent to apache-docs@apache.org (similar to
patches to new-httpd@apache.org) and are committed by the
coordinator.
Options:
- CVS area apache-docs
=> Good approach because we already maintain
our stuff in CVS and CVS provides good change histories,
etc.
Votes: RSE +1
- ...???ANY MORE??...
o Decision about the Table Of Contents
====================================
Status: As a start we should take Stanley Gambarin's toc idea and
enhance/modify it by doing votes and suggestions. The list was
posted by him to new-httpd and will be reposted by me when we
have votes for the above to points.
Sources we should consider:
- apache-site CVS area = http://www.apache.org/
- apache-devsite CVS area = http://dev.apache.org/
- ApacheWeek tutorials: http://www.apacheweek.com/
- Stronghold docs: http://www.c2.net/products/stronghold/docs/
o Decision about how to split up the work in the team
===================================================
!! This can be started when we have discussed the Table
Of Contents and are sure we have one to start with !!
Some ideas and wishes:
----------------------
Dean Gaudet:
One big feature I want are those handy bars down the left side of the page
beside lines which have been modified since the last revision. This would
be extremely nice for users upgrading between versions of the software.
Doing this in html is probably very difficult ... I know you can whack
together something that would look this way as *output*, but it's probably
not easy to manipulate.
BUT: I would be completely happy if only the postscript output was annotated.
Ralf S. Engelschall:
I really want the output formats look as similar as it is possible, i.e.
the HTML online version should look as close to the Postscript version as
it is possible.
Ken:
The FAQ needs to be news.answers-ready.
Brian Slesinsky:
Since 2.0 won't be backward compatible there will need to be some
incentive to upgrade. Perhaps one way to do that is to write good API
docs for 2.0 and leave 1.x (mostly) undocumented? :-)
On the other hand, if there's a compatibility layer, the 1.x API docs
could describe only the calls that are supported by it, so people who
write to the documented interface are covered. I think module writers
would use that API when possible so their modules can work with both 1.x
and 2.0.
In any case it sounds like the API docs will have to be closely
coordinated with the 2.0 effort.
Ralf S. Engelschall
rse@engelschall.com
www.engelschall.com
================================================
The current ADP Team:
---------------------
(Just jump up and say you want to contribute!)
Ralf S. Engelschall <rse@engelschall.com> (coordinator)
Stanley Gambarin <stanleyg@cs.bu.edu>
Christopher Huber <chrish@wired.com>
Brian Slesinsky <bslesins@wired.com>
Mark A. Imbriaco <mark@itribe.net>
Ken Coar <coar@decus.org>
Julie Petersen <juliep@atomicvision.com>
Goal of the project:
--------------------
(Feel free to fix me)
1. Write an Apache Handbook which includes a reference of all config
directives and modules in addition to a complete reference of the general
functionality of Apache and the developer guidelines.
Sources:
- apache/htdocs/* = http://www.apache.org/docs/
- apache-site/* = http://www.apache.org/
- apache-devsite/* = http://dev.apache.org/
Target formats:
- essential: HTML (portable online-browsing)
- essential: Postscript (printing to paper)
- nice: Windows Help File Format (online-browsing on Windows)
- optional: plain ASCII (for Vi-readers ;_)
- optional: PDF (for crunched printing source with hyperlinks).
Target readers:
- webmasters who have to install/configure Apache
- Apache developers
2. Write an Apache User Manual which is a tutorial-like description of
Apache, i.e. it summarizes typical configuration tasks and practical
solutions for the avarage user.
Sources:
- apache/htdocs/* = http://www.apache.org/docs/
- apache-site/* = http://www.apache.org/
- ApacheWeek = http://www.apacheweek.com/
- Stronghold docs = http://www.c2.net/products/stronghold/docs/
Target formats:
- essential: HTML (portable online-browsing)
- essential: Windows Help File Format (online-browsing on Windows)
- essential: Postscript (printing to paper)
- optional: plain ASCII (for Vi-readers ;_)
- optional: PDF (for crunched printing source with hyperlinks).
Target readers:
- advanced users who work under Apache
- avarage webmasters who have to configure Apache
2. Write an Apache FAQ which includes questions & answers of any
topics interested to the impatient reader.
Sources:
- apache/htdocs/manual/misc/FAQ =
http://www.apache.org/docs/manual/misc/FAQ
- ApacheWeek tutorials = http://www.apacheweek.com/
Target formats:
- esstential: news.answers-ready message-digest TXT format (for USENET!!)
- esstential: HTML (portable online-browsing)
- nice: Windows Help File Format (online-browsing on Windows)
- nice: Postscript (printing to paper)
- optional: plain ASCII (for Vi-readers ;_)
- optional: PDF (for crunched printing source with hyperlinks).
Current state:
--------------
I've started to write an initial skeleton for the handbook by the use of
SGML-Tools. This was done to be sure SGML-Tools really is an acceptable
approach. But we are not sure, because SDF is also an alternative. Current
test handbook can be found on http://www.apache.org/~rse/.
Current Points of Discussion:
-----------------------------
(Feel free to add your votes and ideas!)
o Decision on the used markup tool:
=================================
Status: SGMLTools with LinuxDOC-DTD worked
fine for the initial handbook skeleton
and is also used for Linux HOWTOs and
FreeBSD Handbook.
But SDF is an alternative!
Options:
- linuxdoc-sgml 1.5
ftp://sunsite.unc.edu/pub/Linux/...
=> The predecessor of SGMLTools
Votes: RSE -1 (because obsolete)
- FreeBSD's sgmlfmt
ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/...
=> Based on linuxdoc-sgml 1.4/1.5 with
enhancements.
Votes: RSE -1 (because SGMLTools is still better)
- SGMLTools 0.99.14
http://web.inter.NL.net/users/C.deGroot/sgmltools/
=> Provides an SGML-based approach and can
directly generate HTML, TXT and TeX (->Postscript).
Easy syntax because very related to HTML which
every contributor already knows.
Votes: RSE +1 (because currently best tool for SGML approach)
Stanley Gambarin +1 (if and only if .hlp can be
created, too with this approach)
- Perl's Plain Old Document (POD) Format
perl5.004_01.tar.gz:pod/pod2html
=>
Votes: RSE -0 (because not powerful enough: images, etc.)
- Simple Document Format (SDF)
http://www.mincom.com/mtr/sdf/
=> Successor of POD. Leads to very compact source
(especially for lists) in contrast to the SGML approaches.
Works really nice and can be enhanced to fit out needs.
Very easy syntax (similar to POD), but not related
to HTML.
Votes: RSE +1 iff(!) the author Ian Clatworthy
enhances SDF in the following ways:
1. all of our needed features possible
with all of our needed output formats
2. output format Postscript directly
creatable via TeX as the postprocessor
instead of FrameMaker or WinWord.
Ian says he tries to do this enhancements
until the end of the next week. We should
give him a chance!
[.Wed Aug 13: Still waiting for a response
of Ian Clatworthy !!]
Stanley Gambarin +1 (if there is no way to
generate .hlp with SGMLTools)
- eXtensible Markup Language (XML)
(one starting point: http://www.textuality.com/xml/)
=> Alternative to SGML, because some kind of
subset of SGML. Easier then SGML. But
1. When using a easy DTD, SGML is easy too.
2. There are currently not good enough tools for XML.
There are only some precessors/parsers but no
really powerful backends.
3. Currently not a final standard, while SGML is.
Votes: RSE -0 because needs a few years more to be acceptable
- ...???ANY MORE???...
o Decision how to work on ADP as a group
======================================
Status: A CVS area apache-docs can be easily created,
so every contributor can at least grab the stuff via
Anonymous-CVS (when done in the near future) to grab the latest
release. Changes are sent to apache-docs@apache.org (similar to
patches to new-httpd@apache.org) and are committed by the
coordinator.
Options:
- CVS area apache-docs
=> Good approach because we already maintain
our stuff in CVS and CVS provides good change histories,
etc.
Votes: RSE +1
- ...???ANY MORE??...
o Decision about the Table Of Contents
====================================
Status: As a start we should take Stanley Gambarin's toc idea and
enhance/modify it by doing votes and suggestions. The list was
posted by him to new-httpd and will be reposted by me when we
have votes for the above to points.
Sources we should consider:
- apache-site CVS area = http://www.apache.org/
- apache-devsite CVS area = http://dev.apache.org/
- ApacheWeek tutorials: http://www.apacheweek.com/
- Stronghold docs: http://www.c2.net/products/stronghold/docs/
o Decision about how to split up the work in the team
===================================================
!! This can be started when we have discussed the Table
Of Contents and are sure we have one to start with !!
Some ideas and wishes:
----------------------
Dean Gaudet:
One big feature I want are those handy bars down the left side of the page
beside lines which have been modified since the last revision. This would
be extremely nice for users upgrading between versions of the software.
Doing this in html is probably very difficult ... I know you can whack
together something that would look this way as *output*, but it's probably
not easy to manipulate.
BUT: I would be completely happy if only the postscript output was annotated.
Ralf S. Engelschall:
I really want the output formats look as similar as it is possible, i.e.
the HTML online version should look as close to the Postscript version as
it is possible.
Ken:
The FAQ needs to be news.answers-ready.
Brian Slesinsky:
Since 2.0 won't be backward compatible there will need to be some
incentive to upgrade. Perhaps one way to do that is to write good API
docs for 2.0 and leave 1.x (mostly) undocumented? :-)
On the other hand, if there's a compatibility layer, the 1.x API docs
could describe only the calls that are supported by it, so people who
write to the documented interface are covered. I think module writers
would use that API when possible so their modules can work with both 1.x
and 2.0.
In any case it sounds like the API docs will have to be closely
coordinated with the 2.0 effort.
Ralf S. Engelschall
rse@engelschall.com
www.engelschall.com