gconvert: Convert docs to markdown

In particular, we convert sections and lists to markdown syntax
here.

glib/gconvert.c

@@ -65,119 +65,102 @@
  * @title: Character Set Conversion
  * @short_description: convert strings between different character sets
  *
- * The g_convert() family of function wraps the functionality of iconv(). In
+ * The g_convert() family of function wraps the functionality of iconv().
- * addition to pure character set conversions, GLib has functions to deal
+ * In addition to pure character set conversions, GLib has functions to
- * with the extra complications of encodings for file names.
+ * deal with the extra complications of encodings for file names.
  *
- * <refsect2 id="file-name-encodings">
+ * ## File Name Encodings
- * <title>File Name Encodings</title>
+ *
- * <para>
+ * Historically, UNIX has not had a defined encoding for file names:
- * Historically, UNIX has not had a defined encoding for file
+ * a file name is valid as long as it does not have path separators
- * names:  a file name is valid as long as it does not have path
+ * in it ("/"). However, displaying file names may require conversion:
- * separators in it ("/").  However, displaying file names may
+ * from the character set in which they were created, to the character
- * require conversion:  from the character set in which they were
+ * set in which the application operates. Consider the Spanish file name
- * created, to the character set in which the application
+ * "Presentaci&oacute;n.sxi". If the application which created it uses
- * operates.  Consider the Spanish file name
+ * ISO-8859-1 for its encoding,
- * "<filename>Presentaci&oacute;n.sxi</filename>".  If the
+ * <programlisting>
- * application which created it uses ISO-8859-1 for its encoding,
- * </para>
- * <programlisting id="filename-iso8859-1">
  * Character:  P  r  e  s  e  n  t  a  c  i  &oacute;  n  .  s  x  i
  * Hex code:   50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69
  * </programlisting>
- * <para>
  * However, if the application use UTF-8, the actual file name on
  * disk would look like this:
- * </para>
  * <programlisting id="filename-utf-8">
  * Character:  P  r  e  s  e  n  t  a  c  i  &oacute;     n  .  s  x  i
  * Hex code:   50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
  * </programlisting>
- * <para>
+ * Glib uses UTF-8 for its strings, and GUI toolkits like GTK+ that use
- * Glib uses UTF-8 for its strings, and GUI toolkits like GTK+
+ * Glib do the same thing. If you get a file name from the file system,
- * that use Glib do the same thing.  If you get a file name from
+ * for example, from readdir() or from g_dir_read_name(), and you wish
- * the file system, for example, from readdir(3) or from g_dir_read_name(),
+ * to display the file name to the user, you  will need to convert it
- * and you wish to display the file name to the user, you
+ * into UTF-8. The opposite case is when the user types the name of a
- * will need to convert it into UTF-8. The opposite case is when the
+ * file he wishes to save: the toolkit will give you that string in
- * user types the name of a file he wishes to save: the toolkit will
+ * UTF-8 encoding, and you will need to convert it to the character
- * give you that string in UTF-8 encoding, and you will need to convert
+ * set used for file names before you can create the file with open()
- * it to the character set used for file names before you can create the
+ * or fopen().
- * file with open() or fopen().
+ *
- * </para>
- * <para>
  * By default, Glib assumes that file names on disk are in UTF-8
- * encoding.  This is a valid assumption for file systems which
+ * encoding. This is a valid assumption for file systems which
- * were created relatively recently:  most applications use UTF-8
+ * were created relatively recently: most applications use UTF-8
  * encoding for their strings, and that is also what they use for
- * the file names they create.  However, older file systems may
+ * the file names they create. However, older file systems may
  * still contain file names created in "older" encodings, such as
  * ISO-8859-1. In this case, for compatibility reasons, you may
  * want to instruct Glib to use that particular encoding for file
- * names rather than UTF-8.  You can do this by specifying the
+ * names rather than UTF-8. You can do this by specifying the
  * encoding for file names in the <link
  * linkend="G_FILENAME_ENCODING"><envar>G_FILENAME_ENCODING</envar></link>
- * environment variable.  For example, if your installation uses
+ * environment variable. For example, if your installation uses
  * ISO-8859-1 for file names, you can put this in your
  * <filename>~/.profile</filename>:
- * </para>
  * <programlisting>
  * export G_FILENAME_ENCODING=ISO-8859-1
  * </programlisting>
- * <para>
  * Glib provides the functions g_filename_to_utf8() and
- * g_filename_from_utf8() to perform the necessary conversions. These
+ * g_filename_from_utf8() to perform the necessary conversions.
- * functions convert file names from the encoding specified in
+ * These functions convert file names from the encoding specified
- * <envar>G_FILENAME_ENCODING</envar> to UTF-8 and vice-versa.
+ * in <envar>G_FILENAME_ENCODING</envar> to UTF-8 and vice-versa.
  * <xref linkend="file-name-encodings-diagram"/> illustrates how
  * these functions are used to convert between UTF-8 and the
  * encoding for file names in the file system.
- * </para>
+ *
  * <figure id="file-name-encodings-diagram">
  * <title>Conversion between File Name Encodings</title>
  * <graphic fileref="file-name-encodings.png" format="PNG"/>
  * </figure>
- * <refsect3 id="file-name-encodings-checklist">
+ *
- * <title>Checklist for Application Writers</title>
+ * ## Checklist for Application Writers
- * <para>
+ *
  * This section is a practical summary of the detailed
- * description above.  You can use this as a checklist of
+ 
  * things to do to make sure your applications process file
  * name encodings correctly.
- * </para>
+ * 
- * <orderedlist>
+ * 1. If you get a file name from the file system from a function
- * <listitem><para>
+ *    such as readdir() or gtk_file_chooser_get_filename(), you do
- * If you get a file name from the file system from a function
+ *    not need to do any conversion to pass that file name to
- * such as readdir(3) or gtk_file_chooser_get_filename(),
+ *    functions like open(), rename(), or fopen() -- those are "raw"
- * you do not need to do any conversion to pass that
+ *    file names which the file system understands.
- * file name to functions like open(2), rename(2), or
+ *
- * fopen(3) &mdash; those are "raw" file names which the file
+ * 2. If you need to display a file name, convert it to UTF-8 first
- * system understands.
+ *    by using g_filename_to_utf8(). If conversion fails, display a
- * </para></listitem>
+ *    string like "Unknown file name". Do not convert this string back
- * <listitem><para>
+ *    into the encoding used for file names if you wish to pass it to
- * If you need to display a file name, convert it to UTF-8 first by
+ *    the file system; use the original file name instead.
- * using g_filename_to_utf8(). If conversion fails, display a string like
+ *
- * "Unknown file name". Do not convert this string back into the encoding
+ *    For example, the document window of a word processor could display
- * used for file names if you wish to pass it to the file system; use the
+ *    "Unknown file name" in its title bar but still let the user save
- * original file name instead.
+ *    the file, as it would keep the raw file name internally. This can
- * For example, the document window of a word processor could display
+ *    happen if the user has not set the <envar>G_FILENAME_ENCODING</envar>
- * "Unknown file name" in its title bar but still let the user save the
+ *    environment variable even though he has files whose names are not
- * file, as it would keep the raw file name internally. This can happen
+ *    encoded in UTF-8.
- * if the user has not set the <envar>G_FILENAME_ENCODING</envar>
+ *
- * environment variable even though he has files whose names are not
+ * 3. If your user interface lets the user type a file name for saving
- * encoded in UTF-8.
+ *    or renaming, convert it to the encoding used for file names in
- * </para></listitem>
+ *    the file system by using g_filename_from_utf8(). Pass the converted
- * <listitem><para>
+ *    file name to functions like fopen(). If conversion fails, ask the
- * If your user interface lets the user type a file name for saving or
+ *    user to enter a different file name. This can happen if the user
- * renaming, convert it to the encoding used for file names in the file
+ *    types Japanese characters when <envar>G_FILENAME_ENCODING</envar>
- * system by using g_filename_from_utf8(). Pass the converted file name
+ *    is set to <literal>ISO-8859-1</literal>, for example.
- * to functions like fopen(3). If conversion fails, ask the user to enter
- * a different file name. This can happen if the user types Japanese
- * characters when <envar>G_FILENAME_ENCODING</envar> is set to
- * <literal>ISO-8859-1</literal>, for example.
- * </para></listitem>
- * </orderedlist>
- * </refsect3>
- * </refsect2>
  */
 
 /* We try to terminate strings in unknown charsets with this many zero bytes