Re: automatic generation of quickref.html

I have an additional remark about translation.

If you look the code of tidylib, all the strings that are translatable are
all contained in the localize.c file. In a bad way, I think for some reason
I will probably explain in another mail. (in short, localize.c contains code
and strings + there is no way to make a multilingual tidy program).

Whatever, all the translations and translatable strings are contained
in that single file. So that, if, for example, somebody wants to 
translate tidy.
It is quite easy. He just need to change that file. I think that the 
description
should follow the same principle.

Place your code in a new file. But the strings in localize.c.

Also, I have additional request: please add an API for tidyLib
to get help for one parameter only for allowing UI program
using tidylib to show help about one parameter in a tooltip for example.

Thanks by advance,

Marc

Arnaud Desitter wrote:

> 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
> _______________________________________________
> Tidy-develop mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/tidy-develop
>
>



-------------------------------------------------------
This SF.net email is sponsored by Microsoft Mobile & Embedded DevCon 2005
Attend MEDC 2005 May 9-12 in Vegas. Learn more about the latest Windows
Embedded(r) & Windows Mobile(tm) platforms, applications & content.  Register
by 3/29 & save $300 http://ads.osdn.com/?ad_id=6883&alloc_id=15149&op=click