httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ian Clatworthy <>
Subject Re: [STATUS] ADP (Wed 13-Aug-1997 11:43 MET DST)
Date Wed, 13 Aug 1997 11:29:18 GMT

On Wed, 13 Aug 1997, Ralf S. Engelschall wrote:

> STATUS of the Apache Documentation Project (ADP)
> ================================================
>     o Decision on the used markup tool:
>           - Simple Document Format (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.
Strictly speaking, SDF isn't a successor of POD: it started life
before POD did (to my knowledge) and has been recently enhanced
to make it easy for POD authors to migrate to it if and when they
need something more powerful.

>             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)
I've started work on the requested enhancements and hope to have
direct LaTeX output available in a few days. Work has been busy and
we've had relatives staying for most of the last week, so my free
time has been limited. As I discussed with Ralf via email before I
joined the mailing list, if you guys do decide to go with SDF, I'm
happy to support you as best I can by delivering the functionality
you need (within reason) as soon as I can.

> 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.
In SDF, change bars are typically added like this:

!block changed
This paragraph has been
changed since the last release.

At the moment, this is only supported for PostScript generated via
FrameMaker. My boss has been bugging me to support HTML, but I'm
yet to decide on the best way. (Using colored table cells is one
possiblility, but it has its drawbacks.) When I know a bit more
about LaTeX, I'll add change bar support for it.

> 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. 
This is a good principle provided it isn't taken too far. For example,
it isn't uncommon for paper documents to have a fancy title page
followed by copyrights, etc., but translating this directly to HTML
is less than optimal as online readers usually want quick access to
the table of contents. SDF gets around this by using the build_title
macro like this:

  !define DOC_NAME "Apache Handbook"

This generates a fancy cover page for PostScript and a concise title
for HTML.

Other than that (feature), the main difference between PostScript and
HTML generated by SDF is that the HTML doesn't yet have section numbering.
This is number 1 on my boss' list (he's a heavy user of SDF) for fixes
so this should be fixed before long. :-)

Ian Clatworthy (

View raw message