Re: automatic generation of quickref.html

----- Original Message ----- 
From: "Bjoern Hoehrmann" <[email protected]>
To: "Arnaud Desitter" <[email protected]>
Cc: <[email protected]>
Sent: Monday, March 21, 2005 4:17 PM
Subject: Re: [Tidy-dev] automatic generation of quickref.html


>* Arnaud Desitter wrote:
>>I would like to add an automatic generation of quickref.html.
>>Basically, this is http://tidy.sf.net/bug/1008089 (which needs to
>>be updated a tiny bit).
>
> <https://sf.net/tracker/index.php?aid=1008089&group_id=27659&atid=390965>,
> /bug/ only works for bugs, there is /feature/ for RFEs but there is no
> redirect for patches, support requests, etc.

Fair enough.

>>The idea is to have a C file (1) containing the description of each
>>option. Then, a driver (2) generates quickref.html, making sure that
>>all options are dealt with. The generated HTML is almost a copy
>>of the current quickref.html.
>
> Well, I think I am -0 on this, I quite dislike maintaining the docs in C
> files; I would prefer to have a proper XML format with the documentation
> plus a command line tool to retrieve data from Tidy and an XSLT to merge
> those.

Except that tidy is written in C and should be independent of XSLT in my
opinion.

My rationale for this change is:
- the tidy documentation is not that good. See the man page which is years 
behind.
  It would not happen if the documentation was somehow centrally managed.
- at the moment, the correctness of quickref.html is ensured by hand. Using
the documentation generator, I found that
 * some options were not documented
 * some options were is the wrong category
 * some defaults were wrong
 * the alphabetical order was not correct.
 * some APIs in tidylib were not correct (now fixed).
(I fixed all that in the current version of quickref.html)
- the initial idea was to provide some new APIs in tidylib so that tidylib 
users
could dynamically extract a description for each option. I do not claim
that I succeeded but it works, is compact and is better than nothing.
- however, in a first step, I do no suggest to push that code in tidylib. 
Just
to replace quickref.html itself.

The APIs are:
/** Return option description */
ctmbstr tidyOptGetDoc( TidyDoc tdoc, TidyOption opt )
/** Get iterator for list of links to option */
TidyIterator tidyGetOptionDocLinksList( TidyDoc tdoc, TidyOption opt )
/** Get next Option */
TidyOption tidyGetNextOptionDocLinks( TidyDoc tdoc, TidyIterator* pos )

"tidyOptGetDoc" returns a string containing an HTML description of the 
option.
"tidyGetOptionDocLinksList" and "tidyGetNextOptionDocLinks" make it possible
to access a list of cross-references for each option.

The format for the documentation itself is simple:
http://sourceforge.net/tracker/download.php?group_id=27659&atid=390965&file_id=124822&aid=1008089

So, pragmatically, I find these two files an improvement as it may help to 
have a
more up-to-date documentation in the future. I do not push to add any new
features in tidylib itself although it would be useful in my opinion.
Moreover, it will very easy to back-pedal: generate quickref.html, commit it 
and
remove the C code.

Anyway, the votes so far are:
For: 1
Against: 1

I am relatively happy to make small improvements if good ideas come.
I am extremely happy for somebody to come up with something better _and_
implement it in a reasonable time frame. Even in that case, I still think
that "genquickref" is worthwhile as a stop gap measure.

Regards,



-------------------------------------------------------
SF email is sponsored by - The IT Product Guide
Read honest & candid reviews on hundreds of IT Products from real users.
Discover which products truly live up to the hype. Start reading now.
http://ads.osdn.com/?ad_id=6595&alloc_id=14396&op=click