httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From r..@engelschall.com (Ralf S. Engelschall)
Subject [STATUS] ADP (Thu 7-Aug-1997 23:27 MET DST)
Date Thu, 07 Aug 1997 21:27:49 GMT

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>

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

Mime
View raw message