chiark / gitweb /
Prep v239: Add support for the new 'suspend-then-hibernate' method.
[elogind.git] / man / custom-html.xsl
1 <?xml version='1.0'?> <!--*-nxml-*-->
2
3 <!--
4   SPDX-License-Identifier: LGPL-2.1+
5
6 -->
7
8 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
9
10 <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/>
11 <!--
12   - The docbook stylesheet injects empty anchor tags into generated HTML, identified by an auto-generated ID.
13   - Ask the docbook stylesheet to generate reproducible output when generating (these) ID values.
14   - This makes the output of this stylesheet reproducible across identical invocations on the same input,
15   - which is an easy and significant win for achieving reproducible builds.
16   -
17   - It may be even better to strip the empty anchors from the document output in addition to turning on consistent IDs,
18   - for this stylesheet contains its own custom ID logic (for generating permalinks) already.
19  -->
20 <xsl:param name="generate.consistent.ids" select="1"/>
21
22 <!-- translate man page references to links to html pages -->
23 <xsl:template match="citerefentry[not(@project)]">
24   <a>
25     <xsl:attribute name="href">
26       <xsl:value-of select="refentrytitle"/><xsl:text>.html#</xsl:text>
27       <xsl:value-of select="refentrytitle/@target"/>
28     </xsl:attribute>
29     <xsl:call-template name="inline.charseq"/>
30   </a>
31 </xsl:template>
32
33 <xsl:template match="citerefentry[@project='man-pages'] | citerefentry[manvolnum='2'] | citerefentry[manvolnum='4']">
34   <a>
35     <xsl:attribute name="href">
36       <xsl:text>http://man7.org/linux/man-pages/man</xsl:text>
37       <xsl:value-of select="manvolnum"/>
38       <xsl:text>/</xsl:text>
39       <xsl:value-of select="refentrytitle"/>
40       <xsl:text>.</xsl:text>
41       <xsl:value-of select="manvolnum"/>
42       <xsl:text>.html</xsl:text>
43     </xsl:attribute>
44     <xsl:call-template name="inline.charseq"/>
45   </a>
46 </xsl:template>
47
48 <xsl:template match="citerefentry[@project='die-net']">
49   <a>
50     <xsl:attribute name="href">
51       <xsl:text>http://linux.die.net/man/</xsl:text>
52       <xsl:value-of select="manvolnum"/>
53       <xsl:text>/</xsl:text>
54       <xsl:value-of select="refentrytitle"/>
55     </xsl:attribute>
56     <xsl:call-template name="inline.charseq"/>
57   </a>
58 </xsl:template>
59
60 <xsl:template match="citerefentry[@project='wireguard']">
61   <a>
62     <xsl:attribute name="href">
63       <xsl:text>https://git.zx2c4.com/WireGuard/about/src/tools/</xsl:text>
64       <xsl:value-of select="refentrytitle"/>
65       <xsl:text>.</xsl:text>
66       <xsl:value-of select="manvolnum"/>
67     </xsl:attribute>
68     <xsl:call-template name="inline.charseq"/>
69   </a>
70 </xsl:template>
71
72 <xsl:template match="citerefentry[@project='mankier']">
73   <a>
74     <xsl:attribute name="href">
75       <xsl:text>https://www.mankier.com/</xsl:text>
76       <xsl:value-of select="manvolnum"/>
77       <xsl:text>/</xsl:text>
78       <xsl:value-of select="refentrytitle"/>
79     </xsl:attribute>
80     <xsl:call-template name="inline.charseq"/>
81   </a>
82 </xsl:template>
83
84 <xsl:template match="citerefentry[@project='archlinux']">
85   <a>
86     <xsl:attribute name="href">
87       <xsl:text>https://www.archlinux.org/</xsl:text>
88       <xsl:value-of select="refentrytitle"/>
89       <xsl:text>/</xsl:text>
90       <xsl:value-of select="refentrytitle"/>
91       <xsl:text>.</xsl:text>
92       <xsl:value-of select="manvolnum"/>
93       <xsl:text>.html</xsl:text>
94     </xsl:attribute>
95     <xsl:call-template name="inline.charseq"/>
96   </a>
97 </xsl:template>
98
99 <xsl:template match="citerefentry[@project='freebsd']">
100   <a>
101     <xsl:attribute name="href">
102       <xsl:text>https://www.freebsd.org/cgi/man.cgi?</xsl:text>
103       <xsl:value-of select="refentrytitle"/>
104       <xsl:text>(</xsl:text>
105       <xsl:value-of select="manvolnum"/>
106       <xsl:text>)</xsl:text>
107     </xsl:attribute>
108     <xsl:call-template name="inline.charseq"/>
109   </a>
110 </xsl:template>
111
112 <xsl:template match="citerefentry[@project='dbus']">
113   <a>
114     <xsl:attribute name="href">
115       <xsl:text>http://dbus.freedesktop.org/doc/</xsl:text>
116       <xsl:value-of select="refentrytitle"/>
117       <xsl:text>.</xsl:text>
118       <xsl:value-of select="manvolnum"/>
119       <xsl:text>.html</xsl:text>
120     </xsl:attribute>
121     <xsl:call-template name="inline.charseq"/>
122   </a>
123 </xsl:template>
124
125 <!--
126   - helper template to do conflict resolution between various headings with the same inferred ID attribute/tag from the headerlink template
127   - this conflict resolution is necessary to prevent malformed HTML output (multiple ID attributes with the same value)
128   - and it fixes xsltproc warnings during compilation of HTML man pages
129   -
130   - A simple top-to-bottom numbering scheme is implemented for nodes with the same ID value to derive unique ID values for HTML output.
131   - It uses two parameters:
132       templateID  the proposed ID string to use which must be checked for conflicts
133       keyNode     the context node which 'produced' the given templateID.
134   -
135   - Conflicts are detected solely based on keyNode, templateID is not taken into account for that purpose.
136  -->
137 <xsl:template name="generateID">
138   <!-- node which generatedID needs to assume as the 'source' of the ID -->
139   <xsl:param name="keyNode"/>
140   <!-- suggested value for generatedID output, a contextually meaningful ID string -->
141   <xsl:param name="templateID"/>
142   <xsl:variable name="conflictSource" select="preceding::refsect1/title|preceding::refsect1/info/title|
143                                               preceding::refsect2/title|preceding::refsect2/info/title|
144                                               preceding::varlistentry/term[1]"/>
145   <xsl:variable name="conflictCount" select="count($conflictSource[. = $keyNode])"/>
146   <xsl:choose>
147     <!-- special case conflictCount = 0 to preserve compatibility with URLs generated by previous versions of this XSL stylesheet where possible -->
148     <xsl:when test="$conflictCount = 0">
149       <xsl:value-of select="$templateID"/>
150     </xsl:when>
151     <xsl:otherwise>
152       <xsl:value-of select="concat($templateID, $conflictCount)"/>
153     </xsl:otherwise>
154   </xsl:choose>
155 </xsl:template>
156
157 <!--
158   - a helper template to abstract over the structure of generated subheading + permalink HTML output
159   - It helps reduce tedious repetition and groups all actual markup output (as opposed to URL/ID logic) in a single location.
160  -->
161 <xsl:template name="permalink">
162   <xsl:param name="nodeType"/> <!-- local name of the element node to generate, e.g. 'h2' for <h2></h2> -->
163   <xsl:param name="nodeContent"/> <!-- nodeset to apply further templates to obtain the content of the subheading/term -->
164   <xsl:param name="linkTitle"/> <!-- value for title attribute of generated permalink, e.g. 'this is a permalink' -->
165
166   <!-- parameters passed to generateID template, otherwise unused. -->
167   <xsl:param name="keyNode"/>
168   <xsl:param name="templateID"/>
169
170   <!--
171     - If stable URLs with fragment markers (references to the ID) turn out not to be important:
172     - generatedID could simply take the value of generate-id(), and various other helper templates may be dropped entirely.
173     - Alternatively, if xsltproc is patched to generate reproducible generate-id() output, the same simplifications can be
174     - applied at the cost of breaking compatibility with URLs generated from output of previous versions of this stylesheet.
175    -->
176   <xsl:variable name="generatedID">
177     <xsl:call-template name="generateID">
178       <xsl:with-param name="keyNode" select="$keyNode"/>
179       <xsl:with-param name="templateID" select="$templateID"/>
180     </xsl:call-template>
181   </xsl:variable>
182
183   <xsl:element name="{$nodeType}">
184     <xsl:attribute name="id">
185       <xsl:value-of select="$generatedID"/>
186     </xsl:attribute>
187     <xsl:apply-templates select="$nodeContent"/>
188     <a class="headerlink" title="{$linkTitle}" href="#{$generatedID}">¶</a>
189   </xsl:element>
190 </xsl:template>
191
192 <!-- simple wrapper around permalink to avoid repeating common info for each level of subheading covered by the permalink logic (h2, h3) -->
193 <xsl:template name="headerlink">
194   <xsl:param name="nodeType"/>
195   <xsl:call-template name="permalink">
196     <xsl:with-param name="nodeType" select="$nodeType"/>
197     <xsl:with-param name="linkTitle" select="'Permalink to this headline'"/>
198     <xsl:with-param name="nodeContent" select="node()"/>
199     <xsl:with-param name="keyNode" select="."/>
200     <!--
201       - To retain compatibility with IDs generated by previous versions of the template, inline.charseq must be called.
202       - The purpose of that template is to generate markup (according to docbook documentation its purpose is to mark/format something as plain text).
203       - The only reason to call this template is to get the auto-generated text such as brackets ([]) before flattening it.
204      -->
205     <xsl:with-param name="templateID">
206       <xsl:call-template name="inline.charseq"/>
207     </xsl:with-param>
208   </xsl:call-template>
209 </xsl:template>
210
211 <xsl:template match="refsect1/title|refsect1/info/title">
212   <!-- the ID is output in the block.object call for refsect1 -->
213   <xsl:call-template name="headerlink">
214     <xsl:with-param name="nodeType" select="'h2'"/>
215   </xsl:call-template>
216 </xsl:template>
217
218 <xsl:template match="refsect2/title|refsect2/info/title">
219   <xsl:call-template name="headerlink">
220     <xsl:with-param name="nodeType" select="'h3'"/>
221   </xsl:call-template>
222 </xsl:template>
223
224 <xsl:template match="varlistentry">
225   <xsl:call-template name="permalink">
226     <xsl:with-param name="nodeType" select="'dt'"/>
227     <xsl:with-param name="linkTitle" select="'Permalink to this term'"/>
228     <xsl:with-param name="nodeContent" select="term"/>
229     <xsl:with-param name="keyNode" select="term[1]"/>
230     <!--
231       - To retain compatibility with IDs generated by previous versions of the template, inline.charseq must be called.
232       - The purpose of that template is to generate markup (according to docbook documentation its purpose is to mark/format something as plain text).
233       - The only reason to call this template is to get the auto-generated text such as brackets ([]) before flattening it.
234      -->
235     <xsl:with-param name="templateID">
236       <xsl:call-template name="inline.charseq">
237         <xsl:with-param name="content" select="term[1]"/>
238       </xsl:call-template>
239     </xsl:with-param>
240   </xsl:call-template>
241   <dd>
242     <xsl:apply-templates select="listitem"/>
243   </dd>
244 </xsl:template>
245
246
247 <!-- add Index link at top of page -->
248 <xsl:template name="user.header.content">
249   <style>
250     a.headerlink {
251       color: #c60f0f;
252       font-size: 0.8em;
253       padding: 0 4px 0 4px;
254       text-decoration: none;
255       visibility: hidden;
256     }
257
258     a.headerlink:hover {
259       background-color: #c60f0f;
260       color: white;
261     }
262
263     h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
264       visibility: visible;
265     }
266   </style>
267
268   <a>
269     <xsl:attribute name="href">
270       <xsl:text>index.html</xsl:text>
271     </xsl:attribute>
272     <xsl:text>Index </xsl:text>
273   </a>·
274   <a>
275     <xsl:attribute name="href">
276       <xsl:text>elogind.directives.html</xsl:text>
277     </xsl:attribute>
278     <xsl:text>Directives </xsl:text>
279   </a>
280
281   <span style="float:right">
282     <xsl:text>elogind </xsl:text>
283     <xsl:value-of select="$elogind.version"/>
284   </span>
285   <hr/>
286 </xsl:template>
287
288 <xsl:template match="literal">
289   <xsl:text>"</xsl:text>
290   <xsl:call-template name="inline.monoseq"/>
291   <xsl:text>"</xsl:text>
292 </xsl:template>
293
294 <!-- Switch things to UTF-8, ISO-8859-1 is soo yesteryear -->
295 <xsl:output method="html" encoding="UTF-8" indent="no"/>
296
297 </xsl:stylesheet>