winsup/doc: Convert cygwin-api function documentation to refentry elements

Convert cygwin-api from using a sect2 element to using a refentry element for
each function.  This makes it possible to generate manpage-style output for
those elements.

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

Also:

Remove pointless and incorrect date

Move introductory paragraph from the first section to the start of the chapter

Add a funcsynopsisinfo element with the header file to be included to each
function prototype

Remove extern "C" which doesn't process into all formats successfully

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

	* cygwin-api.xml: Move introductory paragraph here.
	* logon-funcs.xml: Convert from using a sect2 element to using a
	refentry element for each function.
	* misc-funcs.xml: Ditto.
	* path.xml: Ditto.

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

1 files changed, 49 insertions, 10 deletions

diff --git a/winsup/doc/logon-funcs.xml b/winsup/doc/logon-funcs.xml
index 9e32ad626..084b0c798 100644
--- a/winsup/doc/logon-funcs.xml
+++ b/winsup/doc/logon-funcs.xml
@@ -5,52 +5,91 @@
 <sect1 id="func-cygwin-login">
 <title>Helper functions to change user context</title>
 
-<sect2 id="func-cygwin-logon_user">
-<title>cygwin_logon_user</title>
+<refentry id="func-cygwin-logon_user">
+  <refmeta>
+    <refentrytitle>cygwin_logon_user</refentrytitle>
+    <manvolnum>3</manvolnum>
+    <refmiscinfo class="manual">Cygwin API Reference</refmiscinfo>
+  </refmeta>
 
-<funcsynopsis><funcprototype>
-<funcdef>extern "C" HANDLE
+  <refnamediv>
+    <refname>cygwin_logon_user</refname>
+  </refnamediv>
+
+  <refsynopsisdiv>
+<funcsynopsis>
+<funcsynopsisinfo>
+#include &lt;sys/cygwin.h&gt;
+</funcsynopsisinfo>
+<funcprototype>
+<funcdef>HANDLE
 <function>cygwin_logon_user</function></funcdef>
 <paramdef>const struct passwd *<parameter>passwd_entry</parameter></paramdef>
 <paramdef>const char *<parameter>password</parameter></paramdef>
 </funcprototype></funcsynopsis>
+  </refsynopsisdiv>
 
+  <refsect1>
+    <title>Description</title>
 <para>Given a pointer to a passwd entry of a user and a cleartext password,
 returns a HANDLE to an impersonation token for this user which can be used
 in a subsequent call to <function>cygwin_set_impersonation_token</function>
 to impersonate that user.  This function can only be called from a process
 which has the required NT user rights to perform a logon.</para>
+  </refsect1>
 
+  <refsect1>
+    <title>See also</title>
 <para>See also the chapter
 <ulink url="../cygwin-ug-net/ntsec.html#ntsec-setuid-overview">Switching the user context</ulink>
 in the Cygwin User's guide.</para>
 
 <para>See also <link linkend="func-cygwin-set-impersonation-token">cygwin_set_impersonation_token</link></para>
+  </refsect1>
+</refentry>
 
-</sect2>
+<refentry id="func-cygwin-set-impersonation-token">
+  <refmeta>
+    <refentrytitle>cygwin_set_impersonation_token</refentrytitle>
+    <manvolnum>3</manvolnum>
+    <refmiscinfo class="manual">Cygwin API Reference</refmiscinfo>
+  </refmeta>
 
-<sect2 id="func-cygwin-set-impersonation-token">
-<title>cygwin_set_impersonation_token</title>
+  <refnamediv>
+    <refname>cygwin_set_impersonation_token</refname>
+  </refnamediv>
 
-<funcsynopsis><funcprototype>
-<funcdef>extern "C" void
+  <refsynopsisdiv>
+<funcsynopsis>
+<funcsynopsisinfo>
+#include &lt;sys/cygwin.h&gt;
+</funcsynopsisinfo>
+<funcprototype>
+<funcdef>void
 <function>cygwin_set_impersonation_token</function></funcdef>
 <paramdef>const HANDLE <parameter>token</parameter></paramdef>
 </funcprototype></funcsynopsis>
+  </refsynopsisdiv>
 
+  <refsect1>
+    <title>Description</title>
 <para>Use this function to enable the token given as parameter as
 impersonation token for the next call to <function>setuid</function> or
 <function>seteuid</function>.  Use
 <function>cygwin_set_impersonation_token</function> together with
 <function>cygwin_logon_user</function> to impersonate users using
 password authentication.</para>
+  </refsect1>
 
+  <refsect1>
+    <title>See also</title>
 <para>See also the chapter
 <ulink url="../cygwin-ug-net/ntsec.html#ntsec-setuid-overview">Switching the user context</ulink>
 in the Cygwin User's guide.</para>
 
 <para>See also <link linkend="func-cygwin-logon_user">cygwin_logon_user</link></para>
+  </refsect1>
 
-</sect2>
+</refentry>
 
 </sect1>