httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Vincent de Lau" <vinc...@delau.nl>
Subject RE: Re: 2.0/manual/howto/htaccess.html etc.
Date Fri, 02 Aug 2002 00:44:31 GMT
> -----Original Message-----
> From: Michael.Schroepl@telekurs.de [mailto:Michael.Schroepl@telekurs.de]
> Sent: Friday, August 02, 2002 12:55 AM
> To: docs@httpd.apache.org; docs@httpd.apache.org
> Subject: Re: Re: 2.0/manual/howto/htaccess.html etc.

> Anyway, I never really understood the difference between a
> "howto" article like "howto/cgi.html" and a non-howto article
> like "content-negotiation.html"; all I know is that "on the right
> side of the start page there are most of those valuable concept
> articles that one should have read first of all, especially
> before ever reading any of the directive descriptions".

IMHO, a how to document is a document that describes (in a step-by-step way)
HOW TO achieve a certain task. There might be some necessary explaining of
the used techniques, but there should be pointers to other documents for the
more advanced documentation.

So you might have a "HOW-TO set up a virtual host" that describes which
lines should be added to http.conf with a short explanation and pointers to
mod/core.html#virtualhost and bind.html. HOW-TO have the bad habit of
including more explanations and non-default behaviour during it's lifetime.

> One of the XML to HTML generation freaks might possibly
> write some lines about whether adding auto-generated parts
> relating to _more_ than one document into each HTML output
> file would be possible using the current transformation
> tools - the information in question is now distributed over
> XML files and even directories and would have to be fetched
> automatically, can any XML tool do that?

Put it in XML and XSLT can transform it to HTML (basically). On off the
things XSLT can't do is get a directory listing (one off the reasons we have
allmodules.xml in mod/). Maybe we should create a similar type of document
for the rest of the documentation, but with 'sitemap' information as well.

Example:
<sitemap>
  ...
  <group mainpage="all" topbar="no"><!-- creates a subsection on the
mainpage, with all documents in it -->
   <name>HOW-TO's</name>
   <file type="index" href="howto/index.xml />
   <file type="document" href="howto/auth.xml />
   ...
  </group>
  ...
  <group mainpage="all" topbar="no">
  <name>Reference Manual</name>
    ...
    <group mainpage="indexonly" topbar="allindex"><!-- creates an item on
the mainpage and include all indexes on the topbar -->
      <name>Modules</name>
      <file type="index" href="mod/index.xml" />
      <file type="altindex" href="mod/directives.xml" />
      ...
    </group>
    ...
  </group>
  ...
</sitemap>

This wouldn't allow for context navigation, but I think the current
<related> structure gives you enough (and even closer) context.

> Regards, Michael
>
> (aware of the very futuristic aspects of this posting)

If XSLT supported IDREFS more easy, I would propose to add a keywords
attribute in. Then you could locate pages with matching keywords. I think
XSLT 2 (Proposed Recommendation) is going to provide this, but before XSLT
parsers have implemented this...

Vincent de Lau
 vincent@delau.nl


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org


Mime
View raw message