RE: automatic generation of quickref.html

Charlie wrote:
>>> You end up wanting to embed basic HTML within the documentation for
>>> each option.  Modularizing HTML is still pretty much broken.
>> 
>> What kind of HTML do you want to embed?  Something like ...
>> 
>>         <tag> tag's contents </tag>
>> 
>> ... doesn't work?  What are you trying to do?
> 
> That works - sort of.  It becomes difficult to distinguish between
> example markup (which is common and useful in a quick reference) and
> actual rendering <code>&lt;code&gt;</code>, IYSWIM.

PS.  I was just looking over your `tidyoptions.xml` sample you had attached.
I think it's pretty much perfect as it is, just add one thing: an optional
`code` element to go inside `description`.  Thus this ...

  <option class="markup">
    <name>add-xml-space</name>
    <type>Boolean</type>
    <default>no</default>
    <description>This option specifies if Tidy should add
    xml:space="preserve" to elements such as &lt;pre&gt;,
    &lt;style&gt; and &lt;script&gt; when generating XML. This
    is needed if the whitespace in such elements is to be parsed
    appropriately without having access to the DTD.
    </description>
  </option>

would become

  <option class="markup">
    <name>add-xml-space</name>
    <type>Boolean</type>
    <default>no</default>
    <description>This option specifies if Tidy should add
    <code>xml:space="preserve"</code> to elements such as
    <code>&lt;pre&gt;</code>, <code>&lt;style&gt</code>; and
    <code>&lt;script&gt</code>; when generating XML. This is
    needed if the whitespace in such elements is to be parsed
    appropriately without having access to the DTD.
    </description>
  </option>

Then for the XHTML quickref, your XSLT could copy the contents of
`description` as is, carrying `<code>...</code>` items through with it.
Thus the description above would be *rendered* in a browser something like
...

    This option specifies if Tidy should add xml:space="preserve"
    to elements such as <pre>, <style> and <script> when
    generating XML. This is needed if the whitespace in such
    elements is to be parsed appropriately without having access
    to the DTD.

... with, of course, the `<code>` items appearing styled as desired
(mono-spaced -- usually Courier-like -- by default).

For the manpage version, one way would be to run the appropriate
XSLT-to-Docbook, then use something like what Terry suggested to create the
manpage, with the resulting `<code>` items appearing highlighted, bolded,
whatever.

/Jelks



-------------------------------------------------------
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_idh82&alloc_id148&op=click