You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@httpd.apache.org by "Ralf S. Engelschall" <rs...@engelschall.com> on 1997/08/07 23:27:49 UTC
[STATUS] ADP (Thu 7-Aug-1997 23:27 MET DST)
STATUS of the Apache Documentation Project (ADP)
================================================
The current ADP Team:
---------------------
(Just jump up and say you want to contribute!)
Ralf S. Engelschall <rs...@engelschall.com> (coordinator)
Stanley Gambarin <st...@cs.bu.edu>
Christopher Huber <ch...@wired.com>
Brian Slesinsky <bs...@wired.com>
Goal of the project:
--------------------
(Feel free to fix me)
Initial goals:
1. Create an Apache Handbook and an Apache FAQ.
which contains most of the important material
from apache/htdocs/ and apache-site.
2. Format these documents both for online browsing
(at least HTML and ASCII) and paper printing
(at least Postscript).
Further goals:
1. Integration of more informations from apache-site
and apache-devsite and ApacheWeeks tutorials.
2. Creation of a User Manual in addition to the Handbook
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 can be a 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)
- 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!
- ...???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 !!
Ralf S. Engelschall
rse@engelschall.com
www.engelschall.com
Re: documenting the stable parts
Posted by Brian Slesinsky <bs...@wired.com>.
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.
_____________________________________________________________________
Brian Slesinsky www.wired.com/staff/bslesins
Re: documenting the stable parts
Posted by Dean Gaudet <dg...@arctic.org>.
What API docs ? :/
Dean
On Thu, 7 Aug 1997, Laurel Gaddie wrote:
>
> So, are you guys planning to rewrite the API docs for 2.0?
>
> :]
>
> Laurel
>
> On Thu, 7 Aug 1997, Dean Gaudet wrote:
>
> > It's unlikely to be backwards compatible. There will likely be a mapping
> > between the interfaces, and in theory someone might be able to write a
> > compatibility layer. But 2.0 is viewed as a chance to rewrite the API to
> > deal with the problems we've found in the current version.
> >
> > 1.3 is pretty much the same as 1.2 though, with a few additions.
> >
> > Dean
> >
> > On Thu, 7 Aug 1997, Brian Slesinsky wrote:
> >
> > >
> > > Is the API interface between an Apache module and the core going to be
> > > backwards compatible in 2.0? That's the part I'm most interested in.
> > >
> > > (I thought I read somewhere that it was, but I can't find it now.)
> > >
> > > __Brian__
> > >
> > >
> >
> >
>
>
>
> .....................................................................
> Laurel J. Gaddie laurel@c2.net
> Documentation Coordinator http://www.c2.net
> C2Net Software, Inc. 510.986.8776
>
>
Re: documenting the stable parts
Posted by Laurel Gaddie <la...@c2.net>.
So, are you guys planning to rewrite the API docs for 2.0?
:]
Laurel
On Thu, 7 Aug 1997, Dean Gaudet wrote:
> It's unlikely to be backwards compatible. There will likely be a mapping
> between the interfaces, and in theory someone might be able to write a
> compatibility layer. But 2.0 is viewed as a chance to rewrite the API to
> deal with the problems we've found in the current version.
>
> 1.3 is pretty much the same as 1.2 though, with a few additions.
>
> Dean
>
> On Thu, 7 Aug 1997, Brian Slesinsky wrote:
>
> >
> > Is the API interface between an Apache module and the core going to be
> > backwards compatible in 2.0? That's the part I'm most interested in.
> >
> > (I thought I read somewhere that it was, but I can't find it now.)
> >
> > __Brian__
> >
> >
>
>
.....................................................................
Laurel J. Gaddie laurel@c2.net
Documentation Coordinator http://www.c2.net
C2Net Software, Inc. 510.986.8776
Re: documenting the stable parts
Posted by Dean Gaudet <dg...@arctic.org>.
It's unlikely to be backwards compatible. There will likely be a mapping
between the interfaces, and in theory someone might be able to write a
compatibility layer. But 2.0 is viewed as a chance to rewrite the API to
deal with the problems we've found in the current version.
1.3 is pretty much the same as 1.2 though, with a few additions.
Dean
On Thu, 7 Aug 1997, Brian Slesinsky wrote:
>
> Is the API interface between an Apache module and the core going to be
> backwards compatible in 2.0? That's the part I'm most interested in.
>
> (I thought I read somewhere that it was, but I can't find it now.)
>
> __Brian__
>
>
documenting the stable parts
Posted by Brian Slesinsky <bs...@wired.com>.
Is the API interface between an Apache module and the core going to be
backwards compatible in 2.0? That's the part I'm most interested in.
(I thought I read somewhere that it was, but I can't find it now.)
__Brian__
Re: [STATUS] ADP (Thu 7-Aug-1997 23:27 MET DST)
Posted by Stanley Gambarin <st...@cs.bu.edu>.
On Thu, 7 Aug 1997, Ralf S. Engelschall wrote:
>
> STATUS of the Apache Documentation Project (ADP)
> ================================================
>
> Goal of the project:
> --------------------
> (Feel free to fix me)
>
> Initial goals:
> 1. Create an Apache Handbook and an Apache FAQ.
> which contains most of the important material
> from apache/htdocs/ and apache-site.
I am a bit unclear of what, or more precisely who is the
Handbook targeted for: is it targeted for the users of apache (webadmins)
or is it targeted towards developers (new-httpd, outside module
developers) or someone else ?
There is a great need to separate the two, as writing the docs for
the developers is completely different from the ones for the users.
Furthermore, I disagree on you plan to port all the existing docs to the
new format. Allow me to babble for a few seconds: porting all the docs
to the new format would require an immmense effort and by the time it is
completed, almost all of it would be outdated, as 1.3 version will be most
likely released and 2.0 would be mostly incompatible with current design
(although i am note sure, i don't know if anyone is). Therefore, it would
be a good idea to start from scratch in the areas which are unlikely to
change by 2.0 timeframe, but we are still lacking now. For example, CGI
specs are unlikely to change in near years and Apache would still be
passing same variables to every CGI script (even though internal mechanism
would have changed), so complete description of how it works, what
variables are present, etc would unlikely to change and the effort would
not be wasted. I do realize there is some overlap, but I would like to
emphasize stable long-term docs first, before moving to the newer stuff.
If immeddiate (i.e. 1.3) documentation is required, then i would recommend
splitting into 2 groups and working side by side.
Ralf: if it is possible for you to setup a table of contents on some web
page, would really appreciate it, as people may want to take a look at it
and add to it, otherwise we are serializing the things-to-do, which is not
as efficient.
Stanley.