Mailing List Archive

I'd also like to see Reply-To: the list.

Dean

On Thu, 7 Aug 1997, Rodent of Unusual Size wrote:

> Brian (I know you're here!)..
>
> I'd like to propose that this list be set up so that the $SENDER is
> the list address ("apache-docs"), the way NH is but JSDK isn't. I
> find it makes sorting through what I want to read in what order much
> simpler than trying to check the "to" or "cc" lines.
>
> Any objections?
>
> #ken :-)}
>

On Thu, 7 Aug 1997, Rodent of Unusual Size wrote:
>> I'd like to propose that this list be set up so that the $SENDER is
>> the list address ("apache-docs"), the way NH is but JSDK isn't. I
>> find it makes sorting through what I want to read in what order much
>> simpler than trying to check the "to" or "cc" lines.

I presume you mean the "Sender:" header? It's already set to
apache-docs-owner@apache.org; did you want something different?

At 12:05 PM 8/7/97 -0700, Dean Gaudet wrote:
>I'd also like to see Reply-To: the list.

I''ve added it.

Brian


--=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=--
"Why not?" - TL brian@organic.com - hyperreal.org - apache.org

On Thu, 7 Aug 1997, Rodent of Unusual Size wrote:

> I'd like to propose that this list be set up so that the $SENDER is
> the list address ("apache-docs"), the way NH is but JSDK isn't. I
> find it makes sorting through what I want to read in what order much
> simpler than trying to check the "to" or "cc" lines.

Second that...

Ok, this is my view on the topic of ADP (feel free to yell and
argue). I have a short list of topics which I personally would like to
see in the documentation. It is by no means complete and i can resend it
to this list if necessary. The documentation should be provided in the
HTML format (I think so anyways), just because most of the people
are familiar with it. Providing a good template for the web page is
essential.

NOTE: Some people may argue that HTML is not a best format and I
agree, so personally I do not care about the format per se, except that
the only requirement is that there are tools to convert that format to
HTML.

Now, there are a bunch of freeware tools out there to convert
HTML to a number of different formats. My thoughts on the matter are:
- use HTML as a base and reference on the website
- provide a single converted PostScript and PDF docs
-this is useful for downloading and printing whole docs
- provide .HLP files via HTML->RTF converter.
- then all we need is some .HPJ files and we got windows docs.
Additional format maybe added later on if people are requesting them, but
the above should be bare minimum.

Regarding general setup
- every page should have a link to searchable contents
- multiple cross-referencing of topics
- table of contents
- tools (distributed with docs) to automatically
regenerate documentations.
- some form of style guide for writing the docs

Plan:
- everyone come up with a single page setup and put it on some
web page where people can try it out and pick the best one.
- negotiate a table of contents
- write tools for automatic generation of docs
- write docs
- ideally this would be a multicycle process, where
an "editor(s)" check contents before approval.
- due to the everchanging nature of the server, it would
be futile to write docs on new stuff, therefore we should
start with stable (unlikely to change) topics, like :
- CGI, SSI, etc.

I got some inspiring ideas of documentation for commercial webservers, so
if you have time, take a look at :
http://www.roxen.com/documentation/manuals/challenger/
http://website.ora.com/wspro/wsapi/html/
http://www.aolserver.com/server/docs/2.0/html/

All opinions are my own and you are free to disagree with them.
Stanley.

In article <Pine.GSO.3.95q.970807162157.4137B-100000@csa> you wrote:

>[...]
> The documentation should be provided in the
> HTML format (I think so anyways), just because most of the people
> are familiar with it. Providing a good template for the web page is
> essential.

Hmmmm... I disagree with this, because although everyone is familiar with HTML
you cannot easily create both TXT and Postscript from it. And even if it
works, it's a bad hack. What we really need is a meta-language from which we
can generate in batch the other formats. SGML and the LinuxDOC-DTD in
conjunction with SGML-Tools is such an approach. And, of course, the source is
very similar to HTML, so everyone should be happy with the markup language.

The other point is SDF: It is much simpler then SGML or HTML and also provides
really good output formats. And at least the Perl hackers like it because it
is like POD. Ok, its a totally different approach and away from HTML, but ok
for a meta-language.

> NOTE: Some people may argue that HTML is not a best format and I
> agree, so personally I do not care about the format per se, except that
> the only requirement is that there are tools to convert that format to
> HTML.

Yes, but thats not all: We really need HTML _AND_ Postscript. Only HTML is not
enough.

> Now, there are a bunch of freeware tools out there to convert
> HTML to a number of different formats. My thoughts on the matter are:
> - use HTML as a base and reference on the website
> - provide a single converted PostScript and PDF docs
> -this is useful for downloading and printing whole docs
> - provide .HLP files via HTML->RTF converter.
> - then all we need is some .HPJ files and we got windows docs.
> Additional format maybe added later on if people are requesting them, but
> the above should be bare minimum.

Here SDF would be nice, because it already provides ASCII, HTML, Postscript
_AND_ Windows Help File Format.

> Regarding general setup
> - every page should have a link to searchable contents
> - multiple cross-referencing of topics
> - table of contents

Provided by both SGML-Tools and SDF.

> - tools (distributed with docs) to automatically
> regenerate documentations.

Fine with SGML-Tools and SDF.

> - some form of style guide for writing the docs

Can be minimal because all bells and whistles (header, footer) etc. are
generated, the table of contents is given (after discussion!) and the SGML
approach is a pure markup approach with only a few markup tags. So, the only
required style guide would be how to structure the sections of the handbook,
etc. But this can be minimal.

> Plan:
> - everyone come up with a single page setup and put it on some
> web page where people can try it out and pick the best one.

Leads to a webdesigner fight who creates the coolest webpage. And because
HTML is only one of our target formats this should be not needed. The goal is
more this: The handbook should look as similar as it can in all formats.
SGML-Tools with my post-processing filters is nic here: The HTML looks nearly
the same as the Postscript printed on paper.

> - negotiate a table of contents

Already put on STATUS and should be discussed after we have choosen the
language/tool.

> - write tools for automatic generation of docs

Good Makefiles can be enough, I think.

> - write docs
> - ideally this would be a multicycle process, where
> an "editor(s)" check contents before approval.
> - due to the everchanging nature of the server, it would
> be futile to write docs on new stuff, therefore we should
> start with stable (unlikely to change) topics, like :
> - CGI, SSI, etc.

+1. Good idea. But we have at least to incorporate the 90% of the current
apache/htdocs/* stuff. Because the Apache Handbook should _REPLACE_ this area
in the future. So at least every module and every config directive should be
documented in the handbook.

>[...]

Greetings,
Ralf S. Engelschall
rse@engelschall.com
www.engelschall.com

> NOTE: Some people may argue that HTML is not a best format and I
> agree, so personally I do not care about the format per se, except that
> the only requirement is that there are tools to convert that format to
> HTML.

We'll probably need to tweak the design of the HTML pages and I think it
would be a good idea to be able to do that without changing hundreds of
source files. That is:

source + templates => HTML
=> Windows docs
=> Postscript => PDF
=> paper
...

"source" could be HTML. However, even if it is, the source HTML won't
look much like the output HTML. The source should be well supported by
tools that convert it to whatever we want and easy to revise, while the
output HTML might have Netscape tags, tables used for layout, or other
impure stuff that makes it look good in a browser but isn't easy to
edit or convert to another format.

Anyway it looks like some people have gotten further along than us using
SGML as the source, so I'd like to read what they've done before
commenting further.

__Brian__

SGML source has the advantage that there are many tools that understand it
... and convert it to every format under the sun.

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.

Dean


On Thu, 7 Aug 1997, Brian Slesinsky wrote:

>
> > NOTE: Some people may argue that HTML is not a best format and I
> > agree, so personally I do not care about the format per se, except that
> > the only requirement is that there are tools to convert that format to
> > HTML.
>
> We'll probably need to tweak the design of the HTML pages and I think it
> would be a good idea to be able to do that without changing hundreds of
> source files. That is:
>
> source + templates => HTML
> => Windows docs
> => Postscript => PDF
> => paper
> ...
>
> "source" could be HTML. However, even if it is, the source HTML won't
> look much like the output HTML. The source should be well supported by
> tools that convert it to whatever we want and easy to revise, while the
> output HTML might have Netscape tags, tables used for layout, or other
> impure stuff that makes it look good in a browser but isn't easy to
> edit or convert to another format.
>
> Anyway it looks like some people have gotten further along than us using
> SGML as the source, so I'd like to read what they've done before
> commenting further.
>
> __Brian__
>
>

Yes I think including windows help file format as one of our necessary
targets is a good thing. I don't think ASCII is necessary at all. I
would be happy with: HTML, Postscript, and .HLP. PDF would be wonderful
too, but I've always been confused by the commercial/non-commercial
aspects of PDF ...

Dean

On Thu, 7 Aug 1997, Stanley Gambarin wrote:

>
>
> On Thu, 7 Aug 1997, Ralf S. Engelschall wrote:
>
> >
> > Here SDF would be nice, because it already provides ASCII, HTML, Postscript
> > _AND_ Windows Help File Format.
> >
> Unless SGML provides some straightforward tools to convert to
> Windows Help File Format (.hlp), I would go with SDF, as I would like to
> once again emphasize the importance of the Win32 platforms, for which
> docs are to be provided. As for page layout, I am more concerned with
> the content than with what lagnuage is used, so if you give me a good
> template, I will provide the content (regardless of SGML, SDF, HTML, etc).
>
> +1 on good template and using SDF
> (unless SGML provides easy way to generate hlp files, then
> +1 on good template and SGML).
> Stanley.
>
>
>

On Thu, 7 Aug 1997, Ralf S. Engelschall wrote:

>
> Here SDF would be nice, because it already provides ASCII, HTML, Postscript
> _AND_ Windows Help File Format.
>
Unless SGML provides some straightforward tools to convert to
Windows Help File Format (.hlp), I would go with SDF, as I would like to
once again emphasize the importance of the Win32 platforms, for which
docs are to be provided. As for page layout, I am more concerned with
the content than with what lagnuage is used, so if you give me a good
template, I will provide the content (regardless of SGML, SDF, HTML, etc).

+1 on good template and using SDF
(unless SGML provides easy way to generate hlp files, then
+1 on good template and SGML).
Stanley.

> 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.

CVS already represents changes, so it seems like change bars could be
generated using 'cvs diff' somehow. The main drawback would be that
anyone who wanted to print change bars would have to have both versions in
their CVS repository.

Another way would be to include the previous version of the documentation
in the distribution, and use 'diff'.

The output from 'diff' isn't perfect but I don't think editing change bars
by hand would be much fun.

_____________________________________________________________________
Brian Slesinsky www.wired.com/staff/bslesins

On Thu, 7 Aug 1997, Dean Gaudet wrote:

> Yes I think including windows help file format as one of our necessary
> targets is a good thing. I don't think ASCII is necessary at all. I
> would be happy with: HTML, Postscript, and .HLP. PDF would be wonderful
> too, but I've always been confused by the commercial/non-commercial
> aspects of PDF ...

Another format that hasn't been mentioned yet, but that I
think would be a 'good thing' is man format. It would be
nice on occaison to be able to 'man apachemod' or somesuch.

-Mark

Make a script, take the output of diff, find all the lines with '>'s in
front of them, then mark those with a changebar. The biggest trick is
that since the line breaks will be different, we need a way in the markup
to say "start left margin bar here" and "stop left margin bar here" that
aren't overly picky about where they go in relation to other things.

I think you would have to do it at that level, since trying to do it in
the various forms of generated documents would be even more hassle.

On Thu, 7 Aug 1997, Brian Slesinsky wrote:

>
> > 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.
>
> CVS already represents changes, so it seems like change bars could be
> generated using 'cvs diff' somehow. The main drawback would be that
> anyone who wanted to print change bars would have to have both versions in
> their CVS repository.
>
> Another way would be to include the previous version of the documentation
> in the distribution, and use 'diff'.
>
> The output from 'diff' isn't perfect but I don't think editing change bars
> by hand would be much fun.
>
> _____________________________________________________________________
> Brian Slesinsky www.wired.com/staff/bslesins
>

I would be completely happy if only the postscript output was annotated.

Dean

On Fri, 8 Aug 1997, Marc Slemko wrote:

> Make a script, take the output of diff, find all the lines with '>'s in
> front of them, then mark those with a changebar. The biggest trick is
> that since the line breaks will be different, we need a way in the markup
> to say "start left margin bar here" and "stop left margin bar here" that
> aren't overly picky about where they go in relation to other things.
>
> I think you would have to do it at that level, since trying to do it in
> the various forms of generated documents would be even more hassle.
>
> On Thu, 7 Aug 1997, Brian Slesinsky wrote:
>
> >
> > > 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.
> >
> > CVS already represents changes, so it seems like change bars could be
> > generated using 'cvs diff' somehow. The main drawback would be that
> > anyone who wanted to print change bars would have to have both versions in
> > their CVS repository.
> >
> > Another way would be to include the previous version of the documentation
> > in the distribution, and use 'diff'.
> >
> > The output from 'diff' isn't perfect but I don't think editing change bars
> > by hand would be much fun.
> >
> > _____________________________________________________________________
> > Brian Slesinsky www.wired.com/staff/bslesins
> >
>
>