Re: automatic generation of quickref.html

Hi folks,

I try below to summarize the debate so far.

Facts:
F1 At the moment, each configuration option is stored in
tidylib and their attributes (name, value, category) can be retrieve more
or less easily using the tidylib APIs. tidy is an example of a command
line program that exploits tidylib to list these options.

F2 Currently, the description of each configuration option is
not accessible anywhere except in "quickref.html" which has not been
maintained very regularly until recently. quickref.html can be reconstructed
from tidylib except for:
- the description of each option
- a list of related option for each option

F3 Users would like a parsable output produced by "tidy". XML is
the favourite format. It is essentially "tidy -help-config" in a more 
parsable
output.

Possible improvements:
I1 To address F3, an option "-help-config-xml" is added to tidy.c.
It outputs the information of "tidy -show-config".

I2 The description and cross references of each option is stored within
tidylib. Some APIs make it possible to retrieve them. A separate driver
or a new option of the driver ("tidy.c") can reconstruct quickref.html.
This addresses the maintenance problem to a point: no option would be
totally un-documented, defaults/type/category will be correct.
The documentation of each option can be in HTML format or in text
format.
This is essentially http://tidy.sf.net/patch/1008089.

I3 If I2 is implemented, then I1 can be more ambitious and output the
description of each option.

I4 Failing to agree on I1, I2, I3 or if nobody volunteers to do the
work, or as a stop-gap, replacing htmldoc/quickref.html by
genquickref.c/tidydoc.h looks to me like a step forward rather than the
current status quo. Moreover, doing that does not preclude implementing
any of the suggestions above.

Caveats:
C1 this relates to the documentation of the configuration options, not
the option of the command-line tidy.
C2 tidy.c contains a lot of hard coded information such as the possible
values that can be extracted at run-time but are not. See genquickref.html
for an example what can be done. Likewise, finding out whether an Integer
is an AutoBool or an Enum is difficult or impossible. tidylib can be
modified. Is it desirable ?

Note that another option is to duplicate the information existing in
src/config.c in a hand-maintained XML file. I do not see any advantage
against having this file being generated except reducing the size of 
tidylib.

Opinions ? To me doing I4 now and working on I1, I2, I3 later looks
sensible.

Regards,

----- Original Message ----- 
From: "Charlie" <[email protected]>
To: "Jelks Cabaniss" <[email protected]>
Cc: <[email protected]>
Sent: Tuesday, March 22, 2005 3:47 AM
Subject: RE: [Tidy-dev] automatic generation of quickref.html


>I third the motion.  I originally generated quickref.html from an XML
> file.  The idea being you could generate a man page and quick reference
> from the same doc source.  I have attached what I think are the original
> XSLT stylesheet and XML data file.
>
> You end up wanting to embed basic HTML within the documentation for each
> option.  Modularizing HTML is still pretty much broken.  What most folks
> end up doing is embed CDATA sections, in which case the result is no good
> for man pages.
>
> ...separation of presentation and content tends to be an ideal rarely
> achieved in practice...
>
>
> At 01:16 PM 3/21/2005 -0500, Jelks Cabaniss wrote:
>>Bjoern Hoehrmann wrote:
>> >> 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.
>>
>>If it were to generate clean XHTML (with IDs for each option), that should
>>allow you to parse the output with XSLT or any other tool.
>>
>>OTOH, I agree with you that it's a good idea to have a succinct XML format
>>in place of stuff like this (from the current quickref page) ...
>>
>>     ...
>>     <tr>
>>     <td class="tabletitle" valign="top" id="write-back">write-back</td>
>>     <td class="tabletitlelink" valign="top" align="right"><a
>>href="#top">Top</a></td>
>>     </tr>
>>     <tr>
>>     <td valign="top">
>>       Type: <b>Boolean</b><br />
>>       Default: <b>no</b><br />
>>       Example: <b>y/n, yes/no, t/f, true/false, 1/0</b></td>
>>     <td align="right" valign="top">
>>     </td>
>>     </tr>
>>     <tr>
>>     <td colspan="2">This option specifies if Tidy
>>     should write back the tidied markup to the same file it read from. 
>> You
>>are
>>     advised to keep copies of important files before tidying them, as on
>>rare
>>     occasions the result may not be what you expect. </td>
>>     </tr>
>>     ...
>>
>>vs.
>>         <TidyOptions>
>>           ...
>>           <option>
>>             <name>write-back</name>
>>             <type>Boolean</type>
>>             <desc>This option specifies if Tidy should write back the
>> tidied markup to the same file it read from. You are advised to keep
>> copies of important files before tidying them, as on rare occasions the
>> result may not be what you expect.</desc>
>>           </option>
>>           ...
>>         </TidyOptions>
>>
>>I think it would be nice if the latter were generated from Tidy itself,
>>where it's all in one place.  Then you could run an XSLT on that, changing
>>with the times as necessary, and without all the presentational stuff
>>hardcoded into the C program.
>>
>>
>>/Jelks
>>
>>
>>
>>-------------------------------------------------------
>>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.
>>_______________________________________________
>>Tidy-develop mailing list
>>[email protected]
>>https://lists.sourceforge.net/lists/listinfo/tidy-develop
> 



-------------------------------------------------------
This SF.net email is sponsored by: 2005 Windows Mobile Application Contest
Submit applications for Windows Mobile(tm)-based Pocket PCs or Smartphones
for the chance to win $25,000 and application distribution. Enter today at
http://ads.osdn.com/?ad_id=6882&alloc_id=15148&op=click