[htdig-dev] Re: splitting attrs.html

[Ted Stresen-R. <ted...@ma...>]

Lachlan et al:

Thank you for the excellent reply. I will use defaults.xml as the master 
document for generating the indidvidual attributes pages.

Geoff? Gilles? Any opinion on moving the documentation to dynamically 
generated files using PHP? If so, I would suggest we procede as follows:

- In general terms, recreate the php.net documentation interface (which 
allows you to do such things as http://www.php.net/mysql_fetch_assoc, 
and be taken directly to the documentation for that function).

This is accomplished by using a custom 404 error page (written in PHP, 
in their case). Specifically, the 404 page carries out the following 
steps:

1) Parses the REQUEST_URI looking for a single entry following the host 
name.

2)
IF A SINGLE ITEM IS FOUND FOLLOWING THE HOST NAME...
- The 404 page looks for a match between the item and an entry in 
defaults.xml

- IF A MATCH IS FOUND IN DEFAULTS.XML...
     - The user is redirected to a new attributes page (just one 
document) with a query string with the attribute name as the parameter. 
This varies from php.net's method, but I find it easier to manage one 
file rather than hundreds...
     - The new attributes page looks up the query string parameter in 
defaults.xml and extracts the documentation and we're done.

- IF A MATCH IS NOT FOUND IN DEFAULTS.XML...
     - PHP executes a query against the htdig system using the single 
item as a search term and the results are displayed, with a message 
indicating that although the page they were seeking could not be found, 
many others exist that may be of use.

IF MORE THAN A SINGLE ITEM IS FOUND FOLLOWING THE HOST NAME...
- We have a choice: present a basic Page Not Found message or execute a 
query against htdig using everything following the host name as the 
search terms. I tend to vote for the first option as the state of AI 
hasn't quite reached a point where the second option is really helpful.

In addition to creating a dynamic interface into the documentation, I 
would maintain the current design so the documentation could be browsed 
as well.

If this is something the htdig development team would like to see, I'll 
do it and post my efforts to my own web site for review.

Ted Stresen-Reuter
http://www.tedmasterweb.com/
also, check out http://dev.susansexton.com/htdig/

On Thursday, January 9, 2003, at 07:00  AM, Lachlan Andrew wrote:

> On Thursday 09 January 2003 10:30, Ted Stresen-Reuter wrote:
>> I've reviewed, briefly, both files mentioned. I'm not sure what their
>> purpose is in terms of the whole project. [deleted] Why is there
>> both a defaults.cc and defaults.xml document?
>
> Their purpose is to be a central place where the options, default
> values and documentation are all given, both for the executables to
> use and for people to read.  So far,  defaults.cc  has been that
> central place, but this has the drawback of bloating the executable
> with all of the descriptions, which aren't used.  Brian White has
> written some scripts to produce both a bare-bones  defaults.cc  and
> attrs.html et al. from  defaults.xml  (and to generate  defaults.xml
> from the current  defaults.cc).  Once these have passed the test of
> time,  defaults.xml  will become the authoritative file.
>
>
>
------------------------------------------------------------------------------------
Homepage: http://www.tedmasterweb.com/
My JavaScript Window Management Tool: http://www.tedmasterweb.com/wmo/