You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@httpd.apache.org by Raymond S Brand <rs...@gate.net> on 2000/08/23 18:38:41 UTC
Re: [PATCH] Second try: External Apache tutorials and
mod/index.htmlreorg
OK, some feedback.
The patch to htdocs/manual/mod/index.html, although useful in its own right,
eliminates a useful index of modules sorted by module name.
I recommend not accepting that patch as is.
Raymond S Brand
Joshua Slive wrote:
>
> Okay, I'm going to try this one again too.
>
> I see at least a couple possible reasons why my doc patches are being
> ignored:
>
> 1. The people who have commit access don't like them, or think that they
> are not very important.
> 2. Nobody with commit access is reading the docs list, or has time
> to deal with submitted patches.
>
> In any case, the exercise seems rather pointless if patches get no
> feedback at all. I'm not trying to be snotty. I'm just trying to see if
> I am wasting my time contributing here. Please let me know.
>
> --
> Joshua Slive
> slive@finance.commerce.ubc.ca
> http://finance.commerce.ubc.ca/~slive/
> Phone: (604) 822-1871
>
> ---------- Forwarded message ----------
> Date: Sat, 19 Aug 2000 15:09:13 -0700 (PDT)
> From: Joshua Slive <sl...@finance.commerce.ubc.ca>
> Reply-To: apache-docs@apache.org
> To: apache-docs@apache.org
> Subject: [PATCH] External Apache tutorials
>
> I am submitting a new file for the docs which consists of links to (mostly
> external) tutorials. This is meant to help alleviate the steep learning
> curve and lack of task-oriented material in the current apache docs by
> leveraging some of the great material that is out there on the web, and
> putting it in an easily accessible place for newcomers.
>
> There are a few concerns with using external linked material:
> 1. We need to be careful to check the accuracy of the docs.
> 2. Some of these links will obviously grow stale over time,
> so some maintenance will be needed.
> 3. Some sites may not like being "deep-linked" in this way. (No permission
> was requested.)
>
> Overall, I think the advantages outweigh these concerns.
>
> Attached is a draft document which can be dropped into htdocs/manual/misc
> and a patch to htdocs/manual/index.html to reference it.
>
> --
> Joshua Slive
> slive@finance.commerce.ubc.ca
> http://finance.commerce.ubc.ca/~slive/
> Phone: (604) 822-1871
>
> --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
> Name: index-html-diff.txt
> index-html-diff.txt Type: Plain Text (TEXT/PLAIN)
> Encoding: BASE64
>
> Name: tutorials.html
> tutorials.html Type: Hypertext Markup Language (TEXT/HTML)
> Encoding: BASE64
>
> Name: index-html-diff.txt
> index-html-diff.txt Type: Plain Text (TEXT/plain)
> Encoding: BASE64
Re: [PATCH] Second try: External Apache tutorials and
mod/index.htmlreorg
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
Rob Stewart wrote:
>
> Please put me off your mailing list.
You can remove yourself from it by sending an empty
message to apache-docs-unsubscribe@apache.org.
--
#ken P-)}
Ken Coar <http://Golux.Com/coar/>
Apache Software Foundation <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed" <http://ApacheUnleashed.Com/>
Re: [PATCH] Second try: External Apache tutorials and mod/index.htmlreorg
Posted by Rob Stewart <ro...@hdlc.com>.
Please put me off your mailing list.
----- Original Message -----
From: Raymond S Brand <rs...@gate.net>
To: <ap...@apache.org>
Sent: Wednesday, August 23, 2000 9:38 AM
Subject: Re: [PATCH] Second try: External Apache tutorials and
mod/index.htmlreorg
> OK, some feedback.
>
> The patch to htdocs/manual/mod/index.html, although useful in its own
right,
> eliminates a useful index of modules sorted by module name.
>
> I recommend not accepting that patch as is.
>
>
> Raymond S Brand
>
>
> Joshua Slive wrote:
> >
> > Okay, I'm going to try this one again too.
> >
> > I see at least a couple possible reasons why my doc patches are being
> > ignored:
> >
> > 1. The people who have commit access don't like them, or think that they
> > are not very important.
> > 2. Nobody with commit access is reading the docs list, or has time
> > to deal with submitted patches.
> >
> > In any case, the exercise seems rather pointless if patches get no
> > feedback at all. I'm not trying to be snotty. I'm just trying to see
if
> > I am wasting my time contributing here. Please let me know.
> >
> > --
> > Joshua Slive
> > slive@finance.commerce.ubc.ca
> > http://finance.commerce.ubc.ca/~slive/
> > Phone: (604) 822-1871
> >
> > ---------- Forwarded message ----------
> > Date: Sat, 19 Aug 2000 15:09:13 -0700 (PDT)
> > From: Joshua Slive <sl...@finance.commerce.ubc.ca>
> > Reply-To: apache-docs@apache.org
> > To: apache-docs@apache.org
> > Subject: [PATCH] External Apache tutorials
> >
> > I am submitting a new file for the docs which consists of links to
(mostly
> > external) tutorials. This is meant to help alleviate the steep learning
> > curve and lack of task-oriented material in the current apache docs by
> > leveraging some of the great material that is out there on the web, and
> > putting it in an easily accessible place for newcomers.
> >
> > There are a few concerns with using external linked material:
> > 1. We need to be careful to check the accuracy of the docs.
> > 2. Some of these links will obviously grow stale over time,
> > so some maintenance will be needed.
> > 3. Some sites may not like being "deep-linked" in this way. (No
permission
> > was requested.)
> >
> > Overall, I think the advantages outweigh these concerns.
> >
> > Attached is a draft document which can be dropped into
htdocs/manual/misc
> > and a patch to htdocs/manual/index.html to reference it.
> >
> > --
> > Joshua Slive
> > slive@finance.commerce.ubc.ca
> > http://finance.commerce.ubc.ca/~slive/
> > Phone: (604) 822-1871
> >
>
--------------------------------------------------------------------------
----------------------------------------------------------------------------
--------------------------------------------------
> > Name: index-html-diff.txt
> > index-html-diff.txt Type: Plain Text (TEXT/PLAIN)
> > Encoding: BASE64
> >
> > Name: tutorials.html
> > tutorials.html Type: Hypertext Markup Language (TEXT/HTML)
> > Encoding: BASE64
> >
> > Name: index-html-diff.txt
> > index-html-diff.txt Type: Plain Text (TEXT/plain)
> > Encoding: BASE64
>
Re: [PATCH] Second try: External Apache tutorials and
mod/index.htmlreorg
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
Raymond S Brand wrote:
>
> The patch to htdocs/manual/mod/index.html, although useful in its
> own right, eliminates a useful index of modules sorted by module
> name.
>
> I recommend not accepting that patch as is.
How about having two sections on the page, one ordered functionally
and one lexically?
--
#ken P-)}
Ken Coar <http://Golux.Com/coar/>
Apache Software Foundation <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed" <http://ApacheUnleashed.Com/>
Re: [PATCH] Second try: External Apache tutorials and
mod/index.htmlreorg
Posted by Raymond S Brand <rs...@gate.net>.
Rodent of Unusual Size wrote:
>
> Raymond S Brand wrote:
> >
> > If this index is going to go into the docs, then I suggest that it
> > and the existing alphabetical module list both have links from the
> > "top" index page.
>
> So are we leaning toward separate pages? One ordered lexically
> (the current version) and one functionally?
Yes.
> > And to be> complete, you should also create another directive
> > index that categorizes the individual directives like you did
> > the modules, and link the two directive indexes off the "top"
> > index page.
>
> A good idea, but a lot more work. :-)
That's why I didn't volunteer :-)
> One problem with keeping separate lists is that there will
> be a tendency for them to fall out of sync. We could do
> some neat single-data-source things if we could use PHP or
> the like, but we have to stay with basic HTML and some SSI
> because of the mirrors and release packaging.
Could definitely be a problem but the "many eyes" approach should
keep it mostly under control.
<Fair_Warning "What follows is an idea I have no time to implement>
An alternative to some form of dynamic content is build the directive
index pages and module index pages statically from a set of source
files.
Basic setup:
Create a doc source directory and populate it with a file
for each module.
Each module file contains the module name, short description,
list of functional areas, long description, and the
list of implemented directives in some parse-able
structure.
Each implemented directive in the list contains the directive
name, attributes, description, etc. in some parse-able
structure.
Build process:
A program loops through the files in the doc source directory
producing the static HTML doc pages. The program
should get run as part of the build process and could
also be run when creating the source tarballs.
Nice advantage:
Documentation for non ASF modules can be included in the end-users
doc tree easily.
</Fair_Warning>
Raymond S Brand
Re: [PATCH] Second try: External Apache tutorials and
mod/index.htmlreorg
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
Raymond S Brand wrote:
>
> If this index is going to go into the docs, then I suggest that it
> and the existing alphabetical module list both have links from the
> "top" index page.
So are we leaning toward separate pages? One ordered lexically
(the current version) and one functionally?
> And to be> complete, you should also create another directive
> index that categorizes the individual directives like you did
> the modules, and link the two directive indexes off the "top"
> index page.
A good idea, but a lot more work. :-)
One problem with keeping separate lists is that there will
be a tendency for them to fall out of sync. We could do
some neat single-data-source things if we could use PHP or
the like, but we have to stay with basic HTML and some SSI
because of the mirrors and release packaging.
--
#ken P-)}
Ken Coar <http://Golux.Com/coar/>
Apache Software Foundation <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed" <http://ApacheUnleashed.Com/>
Re: [PATCH] Second try: External Apache tutorials and mod/index.htmlreorg
Posted by Joshua Slive <sl...@finance.commerce.ubc.ca>.
On Wed, 23 Aug 2000, Raymond S Brand wrote:
> Who should the docs be optimal for? The "first time user" or the "regular user"?
> I do not believe that the answer should be for the "first time user"; after all,
> they probably want/need a tutorial, not the reference manual.
>
> Yes, with the, currently, small number of modules, it's easy enough to just look
> through the list to find the module you need but what happens when the number of
> modules is not so small. Don't assume that all browsers have reasonable search
> facilities.
>
> If this index is going to go into the docs, then I suggest that it and the existing
> alphabetical module list both have links from the "top" index page. And to be
> complete, you should also create another directive index that categorizes the
> individual directives like you did the modules, and link the two directive
> indexes off the "top" index page.
Whatever. I gave my opinion, but I don't have strong feelings either way.
The main reason I did not retain the alphabetic index in my patch is that
I was trying to limit future maintenance work.
Re the Directives index, I also thought about that. My opinion is that it
would be very difficult to do a good job of it. Besides, by categorizing
the modules page you already get most of the way there, since the modules
themselves each index the directives that they contain. The only real
exception is the core "module" which contains a bunch of relatively
unrelated directives. It would probably be useful to add a categorized
index inside mod/core.html. Maybe I will do that someday if my patches
are ever committed ;-)
--
Joshua Slive
slive@finance.commerce.ubc.ca
http://finance.commerce.ubc.ca/~slive/
Phone: (604) 822-1871
Re: [PATCH] Second try: External Apache tutorials and
mod/index.htmlreorg
Posted by Raymond S Brand <rs...@gate.net>.
Who should the docs be optimal for? The "first time user" or the "regular user"?
I do not believe that the answer should be for the "first time user"; after all,
they probably want/need a tutorial, not the reference manual.
Yes, with the, currently, small number of modules, it's easy enough to just look
through the list to find the module you need but what happens when the number of
modules is not so small. Don't assume that all browsers have reasonable search
facilities.
If this index is going to go into the docs, then I suggest that it and the existing
alphabetical module list both have links from the "top" index page. And to be
complete, you should also create another directive index that categorizes the
individual directives like you did the modules, and link the two directive
indexes off the "top" index page.
Raymond S Brand
My suggestion is to have
Joshua Slive wrote:
>
> On Wed, 23 Aug 2000, Raymond S Brand wrote:
>
> > OK, some feedback.
> >
> > The patch to htdocs/manual/mod/index.html, although useful in its own right,
> > eliminates a useful index of modules sorted by module name.
> >
> > I recommend not accepting that patch as is.
> >
>
> That is reasonable. As I stated in my original email for this patch, I
> did consider this and my opinion is that this patch shouldn't really slow
> down somebody looking for a specific module (by name) by more that a
> couple seconds. (Worst case scenario: hit the alt/ctrl-f in netscape and
> type your module name.) However, if others disagree, I would still
> suggest making this version the default "modules" page because it is in
> the structure that is most useful for a first-time user of the docs. The
> alphabetic index could then be linked to this page just as the alphabetic
> list of directives is. The "expert" users that would be looking for the
> alphabetic index would be expert enough to be able to make the extra click
> to find it.
>
> --
> Joshua Slive
> slive@finance.commerce.ubc.ca
> http://finance.commerce.ubc.ca/~slive/
> Phone: (604) 822-1871
Re: [PATCH] Second try: External Apache tutorials and mod/index.htmlreorg
Posted by Ask Bjoern Hansen <as...@valueclick.com>.
On Wed, 23 Aug 2000, Joshua Slive wrote:
> > OK, some feedback.
> >
> > The patch to htdocs/manual/mod/index.html, although useful in its own right,
> > eliminates a useful index of modules sorted by module name.
> >
> > I recommend not accepting that patch as is.
I think I disagree.
For people not knowing what they are doing the patch will be a big
help in educating them. For people knowing what they are doing it
won't be hard to find the module if the blocks are ordered after
request stage.
- ask
--
ask bjoern hansen - <http://www.netcetera.dk/~ask/>
more than 70M impressions per day, <http://valueclick.com>
Re: [PATCH] Second try: External Apache tutorials and mod/index.htmlreorg
Posted by Joshua Slive <sl...@finance.commerce.ubc.ca>.
On Wed, 23 Aug 2000, Raymond S Brand wrote:
> OK, some feedback.
>
> The patch to htdocs/manual/mod/index.html, although useful in its own right,
> eliminates a useful index of modules sorted by module name.
>
> I recommend not accepting that patch as is.
>
That is reasonable. As I stated in my original email for this patch, I
did consider this and my opinion is that this patch shouldn't really slow
down somebody looking for a specific module (by name) by more that a
couple seconds. (Worst case scenario: hit the alt/ctrl-f in netscape and
type your module name.) However, if others disagree, I would still
suggest making this version the default "modules" page because it is in
the structure that is most useful for a first-time user of the docs. The
alphabetic index could then be linked to this page just as the alphabetic
list of directives is. The "expert" users that would be looking for the
alphabetic index would be expert enough to be able to make the extra click
to find it.
--
Joshua Slive
slive@finance.commerce.ubc.ca
http://finance.commerce.ubc.ca/~slive/
Phone: (604) 822-1871