winsup/doc: Convert utils.xml to using refentry elements

Convert utils.xml from using a sect2 element to using a refentry element for
each utility program.  This makes it possible to generate manpage-style output
for those elements.

Note that the chunked html now generates a page for each utility, rather than
one containing all utilities.

A small customization to TOC generation for HTML and PDF is needed to ensure
that it appears as before, containing an entry for each utility command.

Future work: synopsis and options sections could use more detailed markup than
just wrapping the whole thing in <screen>

2015-06-12  Jon Turney  <jon.turney@dronecode.org.uk>

	* utils.xml : Convert from using a sect2 element to using a
	refentry element for each utility program.
	* cygwin.xsl: Customize autotoc to include refentries.
	* fo.xsl: Ditto.

Signed-off-by: Jon TURNEY <jon.turney@dronecode.org.uk>

winsup/doc/ChangeLog

@@ -1,3 +1,10 @@
+2015-06-12  Jon Turney  <jon.turney@dronecode.org.uk>
+
+	* utils.xml : Convert from using a sect2 element to using a
+	refentry element for each utility program.
+	* cygwin.xsl: Customize autotoc to include refentries.
+	* fo.xsl: Ditto.
+
 2015-06-12  Jon Turney  <jon.turney@dronecode.org.uk>
 
 	* Makefile.in (cygwin-ug-net/cygwin-ug-net-nochunks.html.gz):

winsup/doc/cygwin.xsl

@@ -10,4 +10,17 @@
 <xsl:param name="root.filename" select="@id" />
 <xsl:param name="toc.section.depth" select="4" />
 
+<!-- autotoc.xsl customization to make refentry in sect1 appear in toc -->
+<xsl:template match="sect1" mode="toc">
+  <xsl:param name="toc-context" select="."/>
+  <xsl:call-template name="subtoc">
+    <xsl:with-param name="toc-context" select="$toc-context"/>
+    <xsl:with-param name="nodes" select="sect2|refentry
+                                         |bridgehead[$bridgehead.in.toc != 0]"/>
+  </xsl:call-template>
+</xsl:template>
+
+<!-- suppress refentry in toc being annotated with refpurpose -->
+<xsl:param name="annotate.toc" select="0" />
+
 </xsl:stylesheet>

winsup/doc/fo.xsl

@@ -29,4 +29,40 @@
 	<!-- Inform the DocBook stylesheets that it's safe to use FOP
 	     specific extensions. -->
 	<xsl:param name="fop1.extensions" select="1"/>
+
+	<!-- autotoc.xsl customization to make refentry in sect1 appear in toc -->
+<xsl:template match="sect1" mode="toc">
+  <xsl:param name="toc-context" select="."/>
+
+  <xsl:variable name="id">
+    <xsl:call-template name="object.id"/>
+  </xsl:variable>
+
+  <xsl:variable name="cid">
+    <xsl:call-template name="object.id">
+      <xsl:with-param name="object" select="$toc-context"/>
+    </xsl:call-template>
+  </xsl:variable>
+
+  <xsl:call-template name="toc.line">
+    <xsl:with-param name="toc-context" select="$toc-context"/>
+  </xsl:call-template>
+
+  <xsl:variable name="depth.from.context" select="count(ancestor::*)-count($toc-context/ancestor::*)"/>
+
+  <xsl:if test="$toc.section.depth > 1
+                and $toc.max.depth > $depth.from.context">
+    <fo:block id="toc.{$cid}.{$id}">
+      <xsl:attribute name="margin-{$direction.align.start}">
+        <xsl:call-template name="set.toc.indent"/>
+      </xsl:attribute>
+
+      <xsl:apply-templates select="refentry|sect2|qandaset[$qanda.in.toc != 0]"
+                           mode="toc">
+        <xsl:with-param name="toc-context" select="$toc-context"/>
+      </xsl:apply-templates>
+    </fo:block>
+  </xsl:if>
+</xsl:template>
+
 </xsl:stylesheet>