Message ID | 1418182431-65427-1-git-send-email-spitzak@gmail.com |
---|---|
State | Changes Requested |
Headers | show |
diff --git a/doc/publican/doxygen-to-publican.xsl b/doc/publican/doxygen-to-publican.xsl index 47bdc5a..5adbfa6 100644 --- a/doc/publican/doxygen-to-publican.xsl +++ b/doc/publican/doxygen-to-publican.xsl @@ -37,20 +37,16 @@ </para> <xsl:if test="/doxygen/compounddef[@kind='class']"> - <para> - <variablelist> - <xsl:apply-templates select="/doxygen/compounddef" /> - </variablelist> - </para> + <variablelist> + <xsl:apply-templates select="/doxygen/compounddef" /> + </variablelist> </xsl:if> <para>Methods for the respective classes.</para> - <para> <variablelist> - <xsl:apply-templates select="/doxygen/compounddef/sectiondef/memberdef" /> + <xsl:apply-templates select="/doxygen/compounddef/sectiondef/memberdef" /> </variablelist> - </para> </appendix> </xsl:template> @@ -60,7 +56,7 @@ <xsl:apply-templates select="parameternamelist/parametername"/> </term> <listitem> - <xsl:apply-templates select="parameterdescription"/> + <simpara><xsl:apply-templates select="parameterdescription"/></simpara> </listitem> </varlistentry> </xsl:template> @@ -74,7 +70,7 @@ </xsl:template> <xsl:template match="ref"> - <link linkend="{@refid}"><xsl:value-of select="." /></link> + <link linkend="{$which}{@refid}"><xsl:value-of select="." /></link> </xsl:template> <xsl:template match="simplesect[@kind='return']"> @@ -82,22 +78,18 @@ <varlistentry> <term>Returns:</term> <listitem> - <xsl:apply-templates /> + <simpara><xsl:apply-templates /></simpara> </listitem> </varlistentry> </variablelist> </xsl:template> <xsl:template match="simplesect[@kind='see']"> - <para> - See also: <xsl:apply-templates /> - </para> + See also: <xsl:apply-templates /> </xsl:template> <xsl:template match="simplesect[@kind='since']"> - <para> - Since: <xsl:apply-templates /> - </para> + Since: <xsl:apply-templates /> </xsl:template> <xsl:template match="simplesect[@kind='note']"> @@ -131,7 +123,7 @@ <!-- methods --> <xsl:template match="memberdef" > <xsl:if test="@kind = 'function' and @static = 'no'"> - <varlistentry id="{@id}"> + <varlistentry id="{$which}{@id}"> <term> <xsl:value-of select="name"/> <xsl:if test="normalize-space(briefdescription) != ''"> @@ -139,21 +131,19 @@ </xsl:if> </term> <listitem> - <para> - <synopsis> - <xsl:apply-templates select="definition"/><xsl:apply-templates select="argsstring"/> - </synopsis> - </para> + <synopsis> + <xsl:apply-templates select="definition"/><xsl:apply-templates select="argsstring"/> + </synopsis> <xsl:apply-templates select="detaileddescription" /> </listitem> </varlistentry> - </xsl:if> + </xsl:if> </xsl:template> <!-- classes --> <xsl:template match="compounddef" > - <xsl:if test="@kind = 'class'"> - <varlistentry id="{@id}"> + <xsl:if test="@kind = 'class'"> + <varlistentry id="{$which}{@id}"> <term> <xsl:value-of select="compoundname" /> <xsl:if test="normalize-space(briefdescription) != ''"> @@ -165,6 +155,6 @@ <xsl:apply-templates select="detaileddescription" /> </listitem> </varlistentry> - </xsl:if> + </xsl:if> </xsl:template> </xsl:stylesheet> diff --git a/doc/publican/protocol-interfaces-to-docbook.xsl b/doc/publican/protocol-interfaces-to-docbook.xsl index fb1a816..57b3139 100644 --- a/doc/publican/protocol-interfaces-to-docbook.xsl +++ b/doc/publican/protocol-interfaces-to-docbook.xsl @@ -37,11 +37,13 @@ <term> <link linkend="protocol-spec-interface-{@name}"> <xsl:value-of select="@name" /> - <xsl:if test="description/@summary"> - - <xsl:value-of select="description/@summary" /> - </xsl:if> </link> </term> + <listitem> + <simpara> + <xsl:value-of select="description/@summary" /> + </simpara> + </listitem> </varlistentry> </xsl:template> diff --git a/doc/publican/protocol-to-docbook.xsl b/doc/publican/protocol-to-docbook.xsl index 443228d..5eee0fe 100644 --- a/doc/publican/protocol-to-docbook.xsl +++ b/doc/publican/protocol-to-docbook.xsl @@ -88,17 +88,17 @@ <varlistentry> <term><xsl:value-of select="@name"/></term> <listitem> + <simpara> <xsl:if test="name() = 'arg'" > - <para>Type: <xsl:value-of select="@type"/></para> + Type: <xsl:value-of select="@type"/> </xsl:if> <xsl:if test="name() = 'entry'" > - <para>Value: <xsl:value-of select="@value"/></para> + Value: <xsl:value-of select="@value"/> </xsl:if> <xsl:if test="@summary" > - <para> - <xsl:value-of select="@summary"/> - </para> + <xsl:value-of select="@summary"/> </xsl:if> + </simpara> </listitem> </varlistentry> </xsl:template>
On Tue, Dec 09, 2014 at 07:33:51PM -0800, Bill Spitzak wrote: > This removes all the validation errors except for missing link > targets. You can test this by removing the --skip-validation > from doc/publican/Makefile.am. > > Main changes are to add <simpara> to lists, remove some extra > <para> commands, and prefix all the id's so that collisions > between libclient and libserver are avoided. I had to look up what a <simpara> was. Still not entirely certain what the point of it vs. <para>, but if it gets rid of validation errors, +1 to that. I suppose it must solve some layout issues. Sounds like places where we are using <para> for regular text we should rather be using <simpara>. > The remaining errors are due to missing links, due to it not > copying doxygen's output for struct, union, and a macro. Turning > on HIDE_UNDOC in wayland.doxygen.in fixes a lot of these but > not all of them. > > PS: it would be useful if somebody who actually knows something > about xslt would come up with a way to translate a block of text > makde of <para> commands unchanged, but add <para> around plain > text. Most of the difficulty is that doxygen's output is rather > inconsistent here. Jon Cruz, are you listening? ;-) Anyway, the changes all look good to me. Reviewed-by: Bryce Harrington <bryce@osg.samsung.com> > --- > doc/publican/doxygen-to-publican.xsl | 44 +++++++++-------------- > doc/publican/protocol-interfaces-to-docbook.xsl | 8 +++-- > doc/publican/protocol-to-docbook.xsl | 10 +++--- > 3 files changed, 27 insertions(+), 35 deletions(-) > > diff --git a/doc/publican/doxygen-to-publican.xsl b/doc/publican/doxygen-to-publican.xsl > index 47bdc5a..5adbfa6 100644 > --- a/doc/publican/doxygen-to-publican.xsl > +++ b/doc/publican/doxygen-to-publican.xsl > @@ -37,20 +37,16 @@ > </para> > > <xsl:if test="/doxygen/compounddef[@kind='class']"> > - <para> > - <variablelist> > - <xsl:apply-templates select="/doxygen/compounddef" /> > - </variablelist> > - </para> > + <variablelist> > + <xsl:apply-templates select="/doxygen/compounddef" /> > + </variablelist> > </xsl:if> > > <para>Methods for the respective classes.</para> > > - <para> > <variablelist> > - <xsl:apply-templates select="/doxygen/compounddef/sectiondef/memberdef" /> > + <xsl:apply-templates select="/doxygen/compounddef/sectiondef/memberdef" /> > </variablelist> > - </para> > </appendix> > </xsl:template> > > @@ -60,7 +56,7 @@ > <xsl:apply-templates select="parameternamelist/parametername"/> > </term> > <listitem> > - <xsl:apply-templates select="parameterdescription"/> > + <simpara><xsl:apply-templates select="parameterdescription"/></simpara> > </listitem> > </varlistentry> > </xsl:template> > @@ -74,7 +70,7 @@ > </xsl:template> > > <xsl:template match="ref"> > - <link linkend="{@refid}"><xsl:value-of select="." /></link> > + <link linkend="{$which}{@refid}"><xsl:value-of select="." /></link> > </xsl:template> > > <xsl:template match="simplesect[@kind='return']"> > @@ -82,22 +78,18 @@ > <varlistentry> > <term>Returns:</term> > <listitem> > - <xsl:apply-templates /> > + <simpara><xsl:apply-templates /></simpara> > </listitem> > </varlistentry> > </variablelist> > </xsl:template> > > <xsl:template match="simplesect[@kind='see']"> > - <para> > - See also: <xsl:apply-templates /> > - </para> > + See also: <xsl:apply-templates /> > </xsl:template> > > <xsl:template match="simplesect[@kind='since']"> > - <para> > - Since: <xsl:apply-templates /> > - </para> > + Since: <xsl:apply-templates /> > </xsl:template> > > <xsl:template match="simplesect[@kind='note']"> > @@ -131,7 +123,7 @@ > <!-- methods --> > <xsl:template match="memberdef" > > <xsl:if test="@kind = 'function' and @static = 'no'"> > - <varlistentry id="{@id}"> > + <varlistentry id="{$which}{@id}"> > <term> > <xsl:value-of select="name"/> > <xsl:if test="normalize-space(briefdescription) != ''"> > @@ -139,21 +131,19 @@ > </xsl:if> > </term> > <listitem> > - <para> > - <synopsis> > - <xsl:apply-templates select="definition"/><xsl:apply-templates select="argsstring"/> > - </synopsis> > - </para> > + <synopsis> > + <xsl:apply-templates select="definition"/><xsl:apply-templates select="argsstring"/> > + </synopsis> > <xsl:apply-templates select="detaileddescription" /> > </listitem> > </varlistentry> > - </xsl:if> > + </xsl:if> > </xsl:template> > > <!-- classes --> > <xsl:template match="compounddef" > > - <xsl:if test="@kind = 'class'"> > - <varlistentry id="{@id}"> > + <xsl:if test="@kind = 'class'"> > + <varlistentry id="{$which}{@id}"> > <term> > <xsl:value-of select="compoundname" /> > <xsl:if test="normalize-space(briefdescription) != ''"> > @@ -165,6 +155,6 @@ > <xsl:apply-templates select="detaileddescription" /> > </listitem> > </varlistentry> > - </xsl:if> > + </xsl:if> > </xsl:template> > </xsl:stylesheet> > diff --git a/doc/publican/protocol-interfaces-to-docbook.xsl b/doc/publican/protocol-interfaces-to-docbook.xsl > index fb1a816..57b3139 100644 > --- a/doc/publican/protocol-interfaces-to-docbook.xsl > +++ b/doc/publican/protocol-interfaces-to-docbook.xsl > @@ -37,11 +37,13 @@ > <term> > <link linkend="protocol-spec-interface-{@name}"> > <xsl:value-of select="@name" /> > - <xsl:if test="description/@summary"> > - - <xsl:value-of select="description/@summary" /> > - </xsl:if> > </link> > </term> > + <listitem> > + <simpara> > + <xsl:value-of select="description/@summary" /> > + </simpara> > + </listitem> > </varlistentry> > </xsl:template> > > diff --git a/doc/publican/protocol-to-docbook.xsl b/doc/publican/protocol-to-docbook.xsl > index 443228d..5eee0fe 100644 > --- a/doc/publican/protocol-to-docbook.xsl > +++ b/doc/publican/protocol-to-docbook.xsl > @@ -88,17 +88,17 @@ > <varlistentry> > <term><xsl:value-of select="@name"/></term> > <listitem> > + <simpara> > <xsl:if test="name() = 'arg'" > > - <para>Type: <xsl:value-of select="@type"/></para> > + Type: <xsl:value-of select="@type"/> > </xsl:if> > <xsl:if test="name() = 'entry'" > > - <para>Value: <xsl:value-of select="@value"/></para> > + Value: <xsl:value-of select="@value"/> > </xsl:if> > <xsl:if test="@summary" > > - <para> > - <xsl:value-of select="@summary"/> > - </para> > + <xsl:value-of select="@summary"/> > </xsl:if> > + </simpara> > </listitem> > </varlistentry> > </xsl:template> > -- > 1.7.9.5 > > _______________________________________________ > wayland-devel mailing list > wayland-devel@lists.freedesktop.org > http://lists.freedesktop.org/mailman/listinfo/wayland-devel
On 12/10/2014 04:53 PM, Bryce Harrington wrote: > I had to look up what a <simpara> was. Still not entirely certain what > the point of it vs. <para>, but if it gets rid of validation errors, +1 > to that. I suppose it must solve some layout issues. > > Sounds like places where we are using <para> for regular text we should > rather be using <simpara>. It seems to avoid putting a blank line before and after it, which I think make the variable lists look a lot nicer. <para> avoids the validation errors too, but put a lot of whitespace in the output. I found it from the validation error message, which lists all the commands allowed at that point. I don't think it should be used in regular text, use <para> there.
On 12/09/2014 07:33 PM, Bill Spitzak wrote: > > PS: it would be useful if somebody who actually knows something > about xslt would come up with a way to translate a block of text > makde of <para> commands unchanged, but add <para> around plain > text. Most of the difficulty is that doxygen's output is rather > inconsistent here. Unfortunately, that sounds like it could be me. ;-) I'm currently in the middle of trying to get a reasonable xslt to inject image map areas into the docbook XML. Once that's set I can poke at this <para> issue.
On Wed, 10 Dec 2014 16:53:01 -0800 Bryce Harrington <bryce@osg.samsung.com> wrote: > On Tue, Dec 09, 2014 at 07:33:51PM -0800, Bill Spitzak wrote: > > This removes all the validation errors except for missing link > > targets. You can test this by removing the --skip-validation > > from doc/publican/Makefile.am. > > > > Main changes are to add <simpara> to lists, remove some extra > > <para> commands, and prefix all the id's so that collisions > > between libclient and libserver are avoided. > > I had to look up what a <simpara> was. Still not entirely certain what > the point of it vs. <para>, but if it gets rid of validation errors, +1 > to that. I suppose it must solve some layout issues. > > Sounds like places where we are using <para> for regular text we should > rather be using <simpara>. > > > The remaining errors are due to missing links, due to it not > > copying doxygen's output for struct, union, and a macro. Turning > > on HIDE_UNDOC in wayland.doxygen.in fixes a lot of these but > > not all of them. > > > > PS: it would be useful if somebody who actually knows something > > about xslt would come up with a way to translate a block of text > > makde of <para> commands unchanged, but add <para> around plain > > text. Most of the difficulty is that doxygen's output is rather > > inconsistent here. > > Jon Cruz, are you listening? ;-) > > Anyway, the changes all look good to me. > > Reviewed-by: Bryce Harrington <bryce@osg.samsung.com> The changes to Chapter 4 are nice. The changes to Appendix A seem to be lacking somewhat, we get things like: callback_data Type: uintrequest-specific data for the wl_callback There should be some separation between the type and the explanation. There used to be <p> tags, but now there is nothing. In Appendices B and C I did not notice any breakage. Could you revise this patch to fix that one issue? I think this patch does too many things in one go, the para changes are not related for the id namespacing, are they? Thanks, pq > > > --- > > doc/publican/doxygen-to-publican.xsl | 44 +++++++++-------------- > > doc/publican/protocol-interfaces-to-docbook.xsl | 8 +++-- > > doc/publican/protocol-to-docbook.xsl | 10 +++--- > > 3 files changed, 27 insertions(+), 35 deletions(-)