mirror of
https://gitlab.freedesktop.org/wayland/wayland.git
synced 2025-11-26 06:59:58 -05:00
doc: Refactor the build system for complete build dir docs
By structuring things differently, it becomes possible to have a complete build of the docs in the build dir, without having to install anything. Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
This commit is contained in:
Sebastian Wick
parent
59c79dee21
commit
0fd33fe1fa
38 changed files with 138 additions and 164 deletions
147
doc/publican/xsl/doxygen-to-publican.xsl
Normal file
147
doc/publican/xsl/doxygen-to-publican.xsl
Normal file
|
|
@ -0,0 +1,147 @@
|
|||
<?xml version="1.0" ?>
|
||||
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
|
||||
<xsl:output method="xml" encoding="UTF-8" indent="yes" />
|
||||
<xsl:param name="which" />
|
||||
|
||||
<xsl:template match="/">
|
||||
<xsl:apply-templates select="/doxygen/compounddef[@kind!='file' and @kind!='dir']" />
|
||||
|
||||
<section id="{$which}-Functions">
|
||||
<title>Functions</title>
|
||||
<para />
|
||||
<variablelist>
|
||||
<xsl:apply-templates select="/doxygen/compounddef[@kind='file']/sectiondef/memberdef" />
|
||||
</variablelist>
|
||||
</section>
|
||||
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="parameteritem">
|
||||
<varlistentry>
|
||||
<term>
|
||||
<xsl:apply-templates select="parameternamelist/parametername"/>
|
||||
</term>
|
||||
<listitem>
|
||||
<simpara><xsl:apply-templates select="parameterdescription"/></simpara>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="parameterlist">
|
||||
<xsl:if test="parameteritem">
|
||||
<variablelist>
|
||||
<xsl:apply-templates select="parameteritem" />
|
||||
</variablelist>
|
||||
</xsl:if>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="ref">
|
||||
<link linkend="{$which}-{@refid}"><xsl:value-of select="." /></link>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="simplesect[@kind='return']">
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>Returns:</term>
|
||||
<listitem>
|
||||
<simpara><xsl:apply-templates /></simpara>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="simplesect[@kind='see']">
|
||||
See also: <xsl:apply-templates />
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="simplesect[@kind='since']">
|
||||
Since: <xsl:apply-templates />
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="simplesect[@kind='note']">
|
||||
<emphasis>Note: <xsl:apply-templates /></emphasis>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="sp">
|
||||
<xsl:text> </xsl:text>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="programlisting">
|
||||
<programlisting><xsl:apply-templates /></programlisting>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="itemizedlist">
|
||||
<itemizedlist><xsl:apply-templates select="listitem" /></itemizedlist>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="listitem">
|
||||
<listitem><simpara><xsl:apply-templates /></simpara></listitem>
|
||||
</xsl:template>
|
||||
|
||||
<!-- stops cross-references in the section titles -->
|
||||
<xsl:template match="briefdescription">
|
||||
<xsl:value-of select="." />
|
||||
</xsl:template>
|
||||
|
||||
<!-- this opens a para for each detaileddescription/para. I could not find a
|
||||
way to extract the right text for the description from the
|
||||
source otherwise. Downside: we can't use para for return value, "see
|
||||
also", etc. because they're already inside a para. So they're lists.
|
||||
|
||||
It also means we don't control the order of when something is added to
|
||||
the output, it matches the input file
|
||||
-->
|
||||
<xsl:template match="detaileddescription/para">
|
||||
<para><xsl:apply-templates /></para>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="detaileddescription">
|
||||
<xsl:apply-templates select="para" />
|
||||
</xsl:template>
|
||||
|
||||
<!-- methods -->
|
||||
<xsl:template match="memberdef" >
|
||||
<xsl:if test="@kind = 'function' and @static = 'no' and @prot = 'public' or
|
||||
@kind !='function' and normalize-space(briefdescription) != ''">
|
||||
<varlistentry id="{$which}-{@id}">
|
||||
<term>
|
||||
<xsl:value-of select="name"/>
|
||||
<xsl:if test="normalize-space(briefdescription) != ''">
|
||||
- <xsl:apply-templates select="briefdescription" />
|
||||
</xsl:if>
|
||||
</term>
|
||||
<listitem>
|
||||
<synopsis>
|
||||
<xsl:apply-templates select="definition"/><xsl:apply-templates select="argsstring"/>
|
||||
</synopsis>
|
||||
<xsl:apply-templates select="detaileddescription" />
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</xsl:if>
|
||||
</xsl:template>
|
||||
|
||||
<!-- classes -->
|
||||
<xsl:template match="compounddef" >
|
||||
<section id="{$which}-{@id}">
|
||||
<title>
|
||||
<xsl:value-of select="compoundname" />
|
||||
<xsl:if test="normalize-space(briefdescription) != ''">
|
||||
- <xsl:apply-templates select="briefdescription" />
|
||||
</xsl:if>
|
||||
</title>
|
||||
<xsl:choose>
|
||||
<xsl:when test="normalize-space(detaileddescription) != ''">
|
||||
<xsl:apply-templates select="detaileddescription" />
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<para />
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
<xsl:if test="sectiondef/memberdef[@kind='function' and @static='no']">
|
||||
<variablelist>
|
||||
<xsl:apply-templates select="sectiondef/memberdef" />
|
||||
</variablelist>
|
||||
</xsl:if>
|
||||
</section>
|
||||
</xsl:template>
|
||||
</xsl:stylesheet>
|
||||
64
doc/publican/xsl/merge-mapcoords.xsl
Normal file
64
doc/publican/xsl/merge-mapcoords.xsl
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
|
||||
<xsl:param name="basedir"/>
|
||||
<xsl:output method="xml" encoding="utf-8" indent="yes"/>
|
||||
<!-- -->
|
||||
<!-- Template for the root so we can add a DOCTYPE -->
|
||||
<xsl:template match="/">
|
||||
<xsl:text disable-output-escaping="yes"><![CDATA[<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
||||
<!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
|
||||
%BOOK_ENTITIES;
|
||||
]>
|
||||
]]></xsl:text>
|
||||
<xsl:apply-templates select="@*|node()"/>
|
||||
</xsl:template>
|
||||
<!-- -->
|
||||
<xsl:template match="@*|node()">
|
||||
<xsl:copy>
|
||||
<xsl:apply-templates select="@*|node()"/>
|
||||
</xsl:copy>
|
||||
</xsl:template>
|
||||
<!-- -->
|
||||
<!-- suppress existing image map areas -->
|
||||
<xsl:template match="area"/>
|
||||
<!-- -->
|
||||
<xsl:template match="areaspec[area][name(..)='imageobjectco']">
|
||||
<xsl:element name="areaspec">
|
||||
<xsl:apply-templates select="@*"/>
|
||||
<xsl:text>
</xsl:text>
|
||||
<xsl:variable name="pngfile" select="../imageobject/imagedata/@fileref"/>
|
||||
<xsl:variable name="mapfile" select="concat(substring($pngfile, 1, string-length($pngfile)-3), 'map')"/>
|
||||
<xsl:variable name="maproot" select="document(concat($basedir, '/', $mapfile))"/>
|
||||
<!-- -->
|
||||
<!-- now emit the needed areas -->
|
||||
<xsl:for-each select="area">
|
||||
<xsl:variable name="anchor" select="."/>
|
||||
<xsl:variable name="other" select="($maproot)//area[@href=($anchor)/@x_steal]"/>
|
||||
<xsl:choose>
|
||||
<xsl:when test="$other">
|
||||
<xsl:text>	 </xsl:text>
|
||||
<xsl:element name="area">
|
||||
<xsl:attribute name="id">
|
||||
<xsl:value-of select="@id"/>
|
||||
</xsl:attribute>
|
||||
<xsl:attribute name="linkends">
|
||||
<xsl:value-of select="@linkends"/>
|
||||
</xsl:attribute>
|
||||
<xsl:attribute name="coords">
|
||||
<xsl:value-of select="($other)/@coords"/>
|
||||
</xsl:attribute>
|
||||
</xsl:element>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:text>	 </xsl:text>
|
||||
<xsl:comment>
|
||||
<xsl:value-of select="concat('Warning: unable to locate area tagged ', ($anchor)/@x_steal)"/>
|
||||
</xsl:comment>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
<xsl:text>
</xsl:text>
|
||||
</xsl:for-each>
|
||||
<!-- -->
|
||||
<xsl:text>	 </xsl:text>
|
||||
</xsl:element>
|
||||
</xsl:template>
|
||||
</xsl:stylesheet>
|
||||
51
doc/publican/xsl/protocol-interfaces-to-docbook.xsl
Normal file
51
doc/publican/xsl/protocol-interfaces-to-docbook.xsl
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
<?xml version="1.0" ?>
|
||||
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
|
||||
<xsl:output method="xml" encoding="UTF-8" indent="yes" />
|
||||
|
||||
<xsl:template match="/">
|
||||
<!-- insert docbook's DOCTYPE blurb -->
|
||||
<xsl:text disable-output-escaping = "yes"><![CDATA[
|
||||
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
||||
<!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
|
||||
%BOOK_ENTITIES;
|
||||
]>
|
||||
]]></xsl:text>
|
||||
|
||||
<section id="sect-Protocol-Interfaces">
|
||||
<title>Interfaces</title>
|
||||
<para>
|
||||
The protocol includes several interfaces which are used for
|
||||
interacting with the server. Each interface provides requests,
|
||||
events, and errors (which are really just special events) as described
|
||||
above. Specific compositor implementations may have their own
|
||||
interfaces provided as extensions, but there are several which are
|
||||
always expected to be present.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Core interfaces:
|
||||
<variablelist>
|
||||
<xsl:apply-templates select="protocol/interface" />
|
||||
</variablelist>
|
||||
</para>
|
||||
</section>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Interfaces summary -->
|
||||
<xsl:template match="interface" >
|
||||
<varlistentry>
|
||||
<term>
|
||||
<link linkend="protocol-spec-{@name}">
|
||||
<xsl:value-of select="@name" />
|
||||
</link>
|
||||
</term>
|
||||
<listitem>
|
||||
<simpara>
|
||||
<xsl:value-of select="description/@summary" />
|
||||
</simpara>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</xsl:template>
|
||||
|
||||
</xsl:stylesheet>
|
||||
<!-- vim: set expandtab shiftwidth=2: -->
|
||||
223
doc/publican/xsl/protocol-to-docbook.xsl
Normal file
223
doc/publican/xsl/protocol-to-docbook.xsl
Normal file
|
|
@ -0,0 +1,223 @@
|
|||
<?xml version="1.0" ?>
|
||||
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
|
||||
<xsl:output method="xml" encoding="UTF-8" indent="yes" />
|
||||
|
||||
<xsl:template match="/">
|
||||
<!-- insert docbook's DOCTYPE blurb -->
|
||||
<xsl:text disable-output-escaping = "yes"><![CDATA[
|
||||
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
||||
<!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
|
||||
%BOOK_ENTITIES;
|
||||
]>
|
||||
]]></xsl:text>
|
||||
|
||||
<appendix id="appe-Wayland-Protocol">
|
||||
<title>Wayland Protocol Specification</title>
|
||||
<xsl:apply-templates select="protocol/copyright" />
|
||||
|
||||
<xsl:apply-templates select="protocol/interface" />
|
||||
</appendix>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Break text blocks separated by two new lines into paragraphs -->
|
||||
<xsl:template name="break">
|
||||
<xsl:param name="text" />
|
||||
<xsl:param name="linebreak" select="' '" />
|
||||
<xsl:choose>
|
||||
<xsl:when test="contains($text,$linebreak)">
|
||||
<para>
|
||||
<xsl:value-of select="substring-before($text,$linebreak)" />
|
||||
</para>
|
||||
<xsl:call-template name="break">
|
||||
<xsl:with-param name="text" select="substring-after($text,$linebreak)" />
|
||||
</xsl:call-template>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<para><xsl:value-of select="$text" /></para>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Copyright blurb -->
|
||||
<xsl:template match="copyright">
|
||||
<para>
|
||||
<literallayout>
|
||||
<xsl:value-of select="." disable-output-escaping="yes"/>
|
||||
</literallayout>
|
||||
</para>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Interface descriptions -->
|
||||
<xsl:template match="interface" >
|
||||
<section id="protocol-spec-{@name}">
|
||||
<title>
|
||||
<xsl:value-of select="@name" />
|
||||
<!-- only show summary if it exists -->
|
||||
<xsl:if test="description/@summary">
|
||||
- <xsl:value-of select="description/@summary" />
|
||||
</xsl:if>
|
||||
</title>
|
||||
<xsl:call-template name="break">
|
||||
<xsl:with-param name="text" select="description" />
|
||||
</xsl:call-template>
|
||||
<xsl:if test="request">
|
||||
<section>
|
||||
<title>Requests provided by <xsl:value-of select="@name" /></title>
|
||||
<xsl:apply-templates select="request" />
|
||||
</section>
|
||||
</xsl:if>
|
||||
<xsl:if test="event">
|
||||
<section>
|
||||
<title>Events provided by <xsl:value-of select="@name" /></title>
|
||||
<xsl:apply-templates select="event" />
|
||||
</section>
|
||||
</xsl:if>
|
||||
<xsl:if test="enum">
|
||||
<section>
|
||||
<title>Enums provided by <xsl:value-of select="@name" /></title>
|
||||
<xsl:apply-templates select="enum" />
|
||||
</section>
|
||||
</xsl:if>
|
||||
</section>
|
||||
</xsl:template>
|
||||
|
||||
<!-- table contents for enum values -->
|
||||
<xsl:template match="entry">
|
||||
<varlistentry>
|
||||
<term><xsl:value-of select="@name"/></term>
|
||||
<listitem>
|
||||
<simpara>
|
||||
<xsl:value-of select="@value"/>
|
||||
<xsl:if test="@summary" >
|
||||
- <xsl:value-of select="@summary"/>
|
||||
</xsl:if>
|
||||
</simpara>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</xsl:template>
|
||||
|
||||
<!-- table contents for request/event arguments -->
|
||||
<xsl:template match="arg">
|
||||
<varlistentry>
|
||||
<term><xsl:value-of select="@name"/></term>
|
||||
<listitem>
|
||||
<simpara>
|
||||
<xsl:value-of select="@type"/>
|
||||
<xsl:if test="@summary" >
|
||||
- <xsl:value-of select="@summary"/>
|
||||
</xsl:if>
|
||||
</simpara>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</xsl:template>
|
||||
|
||||
<!-- id arguments -->
|
||||
<xsl:template match="arg[@type='object' and @interface]">
|
||||
<varlistentry>
|
||||
<term><xsl:value-of select="@name"/></term>
|
||||
<listitem>
|
||||
<simpara>
|
||||
<link linkend="protocol-spec-{@interface}">
|
||||
<xsl:value-of select="@interface"/>
|
||||
</link>
|
||||
<xsl:if test="@summary" >
|
||||
- <xsl:value-of select="@summary"/>
|
||||
</xsl:if>
|
||||
</simpara>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</xsl:template>
|
||||
|
||||
<!-- new_id arguments -->
|
||||
<xsl:template match="arg[@type='new_id' and @interface]">
|
||||
<varlistentry>
|
||||
<term><xsl:value-of select="@name"/></term>
|
||||
<listitem>
|
||||
<simpara>
|
||||
id for the new
|
||||
<link linkend="protocol-spec-{@interface}">
|
||||
<xsl:value-of select="@interface"/>
|
||||
</link>
|
||||
<xsl:if test="@summary" >
|
||||
- <xsl:value-of select="@summary"/>
|
||||
</xsl:if>
|
||||
</simpara>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</xsl:template>
|
||||
|
||||
<!-- enum and bitfield arguments -->
|
||||
<xsl:template match="arg[@enum]">
|
||||
<varlistentry>
|
||||
<term><xsl:value-of select="@name"/></term>
|
||||
<listitem>
|
||||
<simpara>
|
||||
<xsl:choose>
|
||||
<xsl:when test="contains(@enum, '.')">
|
||||
<link linkend="protocol-spec-{substring-before(@enum, '.')}-enum-{substring-after(@enum, '.')}">
|
||||
<xsl:value-of select="substring-before(@enum, '.')"/>
|
||||
<xsl:text>::</xsl:text>
|
||||
<xsl:value-of select="substring-after(@enum, '.')"/>
|
||||
</link>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<link linkend="protocol-spec-{../../@name}-enum-{@enum}">
|
||||
<xsl:value-of select="../../@name"/>
|
||||
<xsl:text>::</xsl:text>
|
||||
<xsl:value-of select="@enum"/>
|
||||
</link>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
(<xsl:value-of select="@type"/>)
|
||||
<xsl:if test="@summary" >
|
||||
- <xsl:value-of select="@summary"/>
|
||||
</xsl:if>
|
||||
</simpara>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Request/event list -->
|
||||
<xsl:template match="request|event">
|
||||
<section id="protocol-spec-{../@name}-{name()}-{@name}">
|
||||
<title>
|
||||
<xsl:value-of select="../@name"/>::<xsl:value-of select="@name" />
|
||||
<xsl:if test="description/@summary">
|
||||
- <xsl:value-of select="description/@summary" />
|
||||
</xsl:if>
|
||||
</title>
|
||||
<para>
|
||||
<variablelist>
|
||||
<xsl:apply-templates select="arg"/>
|
||||
</variablelist>
|
||||
</para>
|
||||
<xsl:call-template name="break">
|
||||
<xsl:with-param name="text" select="description" />
|
||||
</xsl:call-template>
|
||||
</section>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Enumeration -->
|
||||
<xsl:template match="enum">
|
||||
<section id="protocol-spec-{../@name}-enum-{@name}">
|
||||
<title>
|
||||
<xsl:value-of select="../@name"/>::<xsl:value-of select="@name" />
|
||||
<xsl:if test="@bitfield">
|
||||
- bitfield
|
||||
</xsl:if>
|
||||
<xsl:if test="description/@summary">
|
||||
- <xsl:value-of select="description/@summary" />
|
||||
</xsl:if>
|
||||
</title>
|
||||
<xsl:call-template name="break">
|
||||
<xsl:with-param name="text" select="description" />
|
||||
</xsl:call-template>
|
||||
<variablelist>
|
||||
<xsl:apply-templates select="entry"/>
|
||||
</variablelist>
|
||||
</section>
|
||||
</xsl:template>
|
||||
|
||||
</xsl:stylesheet>
|
||||
|
||||
<!-- vim: set expandtab shiftwidth=2: -->
|
||||
Loading…
Add table
Add a link
Reference in a new issue