[Laszlo-checkins] r9132 - in openlaszlo/trunk/docs/src: . reference xsl
dda@openlaszlo.org
dda at openlaszlo.org
Wed May 14 05:05:19 PDT 2008
Author: dda
Date: 2008-05-14 05:05:13 -0700 (Wed, 14 May 2008)
New Revision: 9132
Added:
openlaszlo/trunk/docs/src/reference/postprocess.rb
Modified:
openlaszlo/trunk/docs/src/build.xml
openlaszlo/trunk/docs/src/reference/info.xml
openlaszlo/trunk/docs/src/xsl/js2doc2dbk.xsl
Log:
Change 20080513-dda-m by dda at lester.local on 2008-05-13 22:20:10 EDT
in /Users/clients/laszlo/src/svn/openlaszlo/trunk-doc3
for http://svn.openlaszlo.org/openlaszlo/trunk
Summary: Doc formatting fixes via ruby postprocessing
New Features:
Bugs Fixed: LPP-5942, LPP-5946
Technical Reviewer: (pending)
QA Reviewer: (pending)
Doc Reviewer: liorio (pending)
Documentation:
Release Notes:
Details:
This is not pretty but it works. At various places, we just want to inject some html,
like <b> around certain elements, and that is not always trivial to do in the docbook
XSL framework. After hours spent on various bugs, I'm ready for a hack fix.
Now, we can inject items that look like <postprocess-XXXX> and these are processed
after the doc is completed by a ruby script.
Two not-so-nice side effects:
- lots of warnings of the form:
Element postprocess-XXXX in namespace '' encountered in term, but no template matches.
- the pages put into reference/*.html will no longer be 'complete' as soon as they are
written. Until the ruby script is run (near the end of the reference doc build),
these html files will have red annotations in them.
Someday it would be nice to do this all in docbook and back this change out.
All the places where it is used are trivial to locate via:
grep '<postprocess-' docs/src/xsl/*.xsl
A clever XSL coder could probably clean these all up right quick.
Here's what it fixes:
- puts an hrule at the end of every method in the reference
- marks method parameters as bold in their table
- extends the method name grey background all the way to the right edge
- puts an hrule at the end of every section in the info-attributes.html file
and it will probably enable more fixes in the future.
Tests:
Modified: openlaszlo/trunk/docs/src/build.xml
===================================================================
--- openlaszlo/trunk/docs/src/build.xml 2008-05-14 12:03:48 UTC (rev 9131)
+++ openlaszlo/trunk/docs/src/build.xml 2008-05-14 12:05:13 UTC (rev 9132)
@@ -829,6 +829,11 @@
<arg value="--inputdir" />
<arg value="${reference.output.dir}" />
</exec>
+ <exec executable="ruby" failonerror="true">
+ <arg value="${reference.src.dir}/postprocess.rb" />
+ <arg value="--inputdir" />
+ <arg value="${reference.output.dir}" />
+ </exec>
</target>
<target name="reference.html.disclaimer" depends="init"
Modified: openlaszlo/trunk/docs/src/reference/info.xml
===================================================================
--- openlaszlo/trunk/docs/src/reference/info.xml 2008-05-14 12:03:48 UTC (rev 9131)
+++ openlaszlo/trunk/docs/src/reference/info.xml 2008-05-14 12:05:13 UTC (rev 9132)
@@ -85,6 +85,7 @@
use attributes to define a class.</p>
<!-- TODO: [2008-05-13 dda] hrule should go here and between each section -->
+<postprocess-html-hrule/>
<p><a name="types"></a>There are five kinds of attributes: </p>
<ul>
@@ -97,6 +98,7 @@
</li>
</ul>
+<postprocess-html-hrule/>
<a name="setter"></a>
<simplesect>
<h2>Attributes (with setter)</h2>
@@ -122,6 +124,7 @@
<p align="right"><ulink url="#top">More on attributes</ulink></p>
</simplesect>
+<postprocess-html-hrule/>
<a name="defaultsetter"></a>
<simplesect>
<h2>Attributes (without setter)</h2>
@@ -141,6 +144,7 @@
<p align="right"><ulink url="#top">More on attributes</ulink></p>
</simplesect>
+<postprocess-html-hrule/>
<a name="eventhandler"></a>
<simplesect>
<h2>Event Handler Attributes</h2>
@@ -156,6 +160,7 @@
<p align="right"><ulink url="#top">More on attributes</ulink></p>
</simplesect>
+<postprocess-html-hrule/>
<a name="final"></a>
<simplesect>
<h2>Final Attributes</h2>
@@ -165,6 +170,7 @@
<p align="right"><ulink url="#top">More on attributes</ulink></p>
</simplesect>
+<postprocess-html-hrule/>
<a name="readonly"></a>
<simplesect>
<h2>Read Only Attributes (Fields)</h2>
Added: openlaszlo/trunk/docs/src/reference/postprocess.rb
Property changes on: openlaszlo/trunk/docs/src/reference/postprocess.rb
___________________________________________________________________
Name: svn:mime-type
+ text/plain
Name: svn:eol-style
+ native
Modified: openlaszlo/trunk/docs/src/xsl/js2doc2dbk.xsl
===================================================================
--- openlaszlo/trunk/docs/src/xsl/js2doc2dbk.xsl 2008-05-14 12:03:48 UTC (rev 9131)
+++ openlaszlo/trunk/docs/src/xsl/js2doc2dbk.xsl 2008-05-14 12:05:13 UTC (rev 9132)
@@ -477,7 +477,7 @@
</variablelist>
</xsl:if>
</xsl:template>
-
+
<xsl:template name="describe-members-grid">
<xsl:param name="members"/>
<xsl:param name="static"/>
@@ -600,7 +600,21 @@
<xsl:value-of select="$name"/>
</primary>
</indexterm>
- <xsl:value-of select="$desc"/>
+ <!-- TODO [dda 2008-05-14] handle postprocess tags in docbook.
+ We need to inject certain HTML formatting that is hard
+ to work out in docbook/XSL in a timely manner. The
+ technique is to put a <postprocess-*> tag in place, let
+ docbook warn us about it (but leave a doctored version
+ in place), and then a ruby script, postprocess.rb, does
+ a final clean up pass by locating and replacing the
+ doctored postprocess tags.
+
+ The postprocess-methodname tag puts a grey background
+ against the method name and stretches it the entire width.
+ -->
+ <postprocess-methodname>
+ <xsl:value-of select="$desc"/>
+ </postprocess-methodname>
</term>
<listitem>
<refsect3>
@@ -633,7 +647,10 @@
<tbody>
<xsl:for-each select="function/parameter">
<row>
- <entry><xsl:attribute name="class">parametername</xsl:attribute><xsl:value-of select="@name"/></entry>
+ <!-- The postprocess-html-b tag puts a <b> tag
+ around the method name.
+ See also 'handle postprocess tags' comment. -->
+ <entry><postprocess-html-b><xsl:value-of select="@name"/></postprocess-html-b></entry>
<entry><xsl:value-of select="@type"/></entry>
<entry><xsl:value-of select="doc/text"/></entry>
</row>
@@ -666,6 +683,11 @@
</informaltable>
</refsect3>
</xsl:if>
+ <refsect3>
+ <!-- The postprocess-method-end tag puts an hrule after the method.
+ See also 'handle postprocess tags' comment. -->
+ <postprocess-method-end/>
+ </refsect3>
</listitem>
</varlistentry>
</xsl:template>
More information about the Laszlo-checkins
mailing list