Documentation fixes.

* glib/giochannel.c: Documentation fixes.

        * glib/tmpl/iochannels.sgml: Document GIOFlags, fix typos.

        * glib/tmpl/conversions.sgml, glib/tmpl/unicode.sgml,
        glib/tmpl/spawn.sgml, glib/tmpl/fileutils.sgml,
        glib/tmpl/shell.sgml, glib/tmpl/windows.sgml: Add
        some missing short and long descriptions.

ChangeLog

@@ -1,3 +1,7 @@
+2001-11-15  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/giochannel.c: Documentation fixes.
+ 
 2001-11-15  Takayuki KUSANO  <AE5T-KSN@asahi-net.or.jp>
 
 	* configure.in: Added "ja" to ALL_LINGUAS.

ChangeLog.pre-2-0

@@ -1,3 +1,7 @@
+2001-11-15  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/giochannel.c: Documentation fixes.
+ 
 2001-11-15  Takayuki KUSANO  <AE5T-KSN@asahi-net.or.jp>
 
 	* configure.in: Added "ja" to ALL_LINGUAS.

ChangeLog.pre-2-10

@@ -1,3 +1,7 @@
+2001-11-15  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/giochannel.c: Documentation fixes.
+ 
 2001-11-15  Takayuki KUSANO  <AE5T-KSN@asahi-net.or.jp>
 
 	* configure.in: Added "ja" to ALL_LINGUAS.

ChangeLog.pre-2-12

@@ -1,3 +1,7 @@
+2001-11-15  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/giochannel.c: Documentation fixes.
+ 
 2001-11-15  Takayuki KUSANO  <AE5T-KSN@asahi-net.or.jp>
 
 	* configure.in: Added "ja" to ALL_LINGUAS.

ChangeLog.pre-2-2

@@ -1,3 +1,7 @@
+2001-11-15  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/giochannel.c: Documentation fixes.
+ 
 2001-11-15  Takayuki KUSANO  <AE5T-KSN@asahi-net.or.jp>
 
 	* configure.in: Added "ja" to ALL_LINGUAS.

ChangeLog.pre-2-4

@@ -1,3 +1,7 @@
+2001-11-15  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/giochannel.c: Documentation fixes.
+ 
 2001-11-15  Takayuki KUSANO  <AE5T-KSN@asahi-net.or.jp>
 
 	* configure.in: Added "ja" to ALL_LINGUAS.

ChangeLog.pre-2-6

@@ -1,3 +1,7 @@
+2001-11-15  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/giochannel.c: Documentation fixes.
+ 
 2001-11-15  Takayuki KUSANO  <AE5T-KSN@asahi-net.or.jp>
 
 	* configure.in: Added "ja" to ALL_LINGUAS.

ChangeLog.pre-2-8

@@ -1,3 +1,7 @@
+2001-11-15  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/giochannel.c: Documentation fixes.
+ 
 2001-11-15  Takayuki KUSANO  <AE5T-KSN@asahi-net.or.jp>
 
 	* configure.in: Added "ja" to ALL_LINGUAS.

docs/reference/ChangeLog

@@ -1,3 +1,12 @@
+2001-11-15  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/tmpl/iochannels.sgml: Document GIOFlags, fix typos.
+
+	* glib/tmpl/conversions.sgml, glib/tmpl/unicode.sgml,
+	glib/tmpl/spawn.sgml, glib/tmpl/fileutils.sgml,
+	glib/tmpl/shell.sgml, glib/tmpl/windows.sgml: Add
+	some missing short and long descriptions.
+
 2001-11-14  Matthias Clasen  <matthiasc@poet.de>
 
 	* glib/Makefile.am (MKDB_OPTIONS): Add --sgml-mode.

docs/reference/glib/tmpl/conversions.sgml

@@ -2,7 +2,7 @@
 Character Set Conversion
 
 <!-- ##### SECTION Short_Description ##### -->
-
+convert strings between different character sets using <function>iconv()</function>
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/fileutils.sgml

@@ -2,7 +2,7 @@
 File Utilities
 
 <!-- ##### SECTION Short_Description ##### -->
-
+various file-related functions.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/iochannels.sgml

@@ -9,13 +9,13 @@ portable support for using files, pipes and sockets.
 The #GIOChannel data type aims to provide a portable method for using file
 descriptors, pipes, and sockets, and integrating them into the
 <link linkend="glib-The-Main-Event-Loop">main event loop</link>.
-Currently full support is available on Unix platforms, though support for
+Currently full support is available on Unix platforms, support for
 Windows is only partially complete.
 </para>
 <para>
 To create a new #GIOChannel on Unix systems use g_io_channel_unix_new().
 This works for plain file descriptors, pipes and sockets.
-Alternately, a channel can be created for a file in a system independent
+Alternatively, a channel can be created for a file in a system independent
 manner using g_io_channel_new_file().
 </para>
 <para>
@@ -51,7 +51,7 @@ The new functions g_io_channel_read_chars(), g_io_channel_read_line(),
 g_io_channel_read_line_string(), g_io_channel_read_to_end(),
 g_io_channel_write_chars(), g_io_channel_seek_position(),
 and g_io_channel_flush() should not be mixed with the
-depricated functions g_io_channel_read(), g_io_channel_write(),
+deprecated functions g_io_channel_read(), g_io_channel_write(),
 and g_io_channel_seek() on the same channel.
 </para>
 
@@ -213,8 +213,6 @@ programmer (unless you are creating a new type of #GIOChannel).
 @channel: 
 @error: 
 @Returns: 
-<!-- # Unused Parameters # -->
-@err: 
 
 
 <!-- ##### FUNCTION g_io_channel_seek_position ##### -->
@@ -227,41 +225,17 @@ programmer (unless you are creating a new type of #GIOChannel).
 @type: 
 @error: 
 @Returns: 
-<!-- # Unused Parameters # -->
-@err: 
 
 
 <!-- ##### ENUM GSeekType ##### -->
 <para>
 An enumeration specifying the base position for a g_io_channel_seek_position()
 operation.
-
-<informaltable pgwide=1 frame="none" role="enum">
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
-<tbody>
-
-<row>
-<entry>G_SEEK_CUR</entry>
-<entry>the current position in the file.</entry>
-</row>
-
-<row>
-<entry>G_SEEK_SET</entry>
-<entry>the start of the file.</entry>
-</row>
-
-<row>
-<entry>G_SEEK_END</entry>
-<entry>the end of the file.</entry>
-</row>
-
-</tbody></tgroup></informaltable>
-
 </para>
 
-@G_SEEK_CUR: 
+@G_SEEK_CUR: the current position in the file.
-@G_SEEK_SET: 
+@G_SEEK_SET: the start of the file.
-@G_SEEK_END: 
+@G_SEEK_END: the end of the file.
 
 <!-- ##### FUNCTION g_io_channel_shutdown ##### -->
 <para>
@@ -381,52 +355,15 @@ with the given priority.
 <para>
 A bitwise combination representing a condition to watch for on an event
 source.
-
-<informaltable pgwide=1 frame="none" role="enum">
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
-<tbody>
-
-<row>
-<entry>G_IO_IN</entry>
-<entry>There is data to read.</entry>
-</row>
-
-<row>
-<entry>G_IO_OUT</entry>
-<entry>Data can be written (without blocking).</entry>
-</row>
-
-<row>
-<entry>G_IO_PRI</entry>
-<entry>There is urgent data to read.</entry>
-</row>
-
-<row>
-<entry>G_IO_ERR</entry>
-<entry>Error condition.</entry>
-</row>
-
-<row>
-<entry>G_IO_HUP</entry>
-<entry>Hung up (the connection has been broken, usually for pipes and
-sockets).</entry>
-</row>
-
-<row>
-<entry>G_IO_NVAL</entry>
-<entry>Invalid request. The file descriptor is not open.</entry>
-</row>
-
-</tbody></tgroup></informaltable>
-
 </para>
 
-@G_IO_IN: 
+@G_IO_IN: There is data to read.
-@G_IO_OUT: 
+@G_IO_OUT: Data can be written (without blocking).
-@G_IO_PRI: 
+@G_IO_PRI: There is urgent data to read.
-@G_IO_ERR: 
+@G_IO_ERR: Error condition.
-@G_IO_HUP: 
+@G_IO_HUP: Hung up (the connection has been broken, usually for pipes 
-@G_IO_NVAL: 
+           and sockets).
+@G_IO_NVAL: Invalid request. The file descriptor is not open.
 
 <!-- ##### USER_FUNCTION GIOFunc ##### -->
 <para>
@@ -491,9 +428,6 @@ generic way.
 
 @channel: 
 @Returns: 
-<!-- # Unused Parameters # -->
-@flags: 
-@error: 
 
 
 <!-- ##### FUNCTION g_io_channel_set_flags ##### -->
@@ -509,14 +443,22 @@ generic way.
 
 <!-- ##### ENUM GIOFlags ##### -->
 <para>
-
+Specifies properties of a #GIOChannel. Some of the flags can only
+be read with g_io_channel_get_flags(), but not changed with
+g_io_channel_set_flags(). 
 </para>
 
-@G_IO_FLAG_APPEND: 
+@G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND (see the 
-@G_IO_FLAG_NONBLOCK: 
+   documentation of the Unix <function>open()</function> syscall). 
-@G_IO_FLAG_IS_READABLE: 
+@G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to 
-@G_IO_FLAG_IS_WRITEABLE: 
+   %O_NONBLOCK/%O_NDELAY (see the documentation of the Unix 
-@G_IO_FLAG_IS_SEEKABLE: 
+   <function>open()</function> syscall). 
+@G_IO_FLAG_IS_READABLE: indicates that the io channel is readable. This flag 
+   can not be changed.
+@G_IO_FLAG_IS_WRITEABLE: indicates that the io channel is writable. This flag 
+   can not be changed.
+@G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable, i.e. that 
+   g_io_channel_seek_position() can be used on it. This flag can not be changed.
 @G_IO_FLAG_MASK: 
 @G_IO_FLAG_GET_MASK: 
 @G_IO_FLAG_SET_MASK: 
@@ -610,7 +552,7 @@ generic way.
 
 <!-- ##### ENUM GIOError ##### -->
 <para>
-#GIOError is only used by the depricated functions g_io_channel_read(),
+#GIOError is only used by the deprecated functions g_io_channel_read(),
 g_io_channel_write(), and g_io_channel_seek().
 </para>
 

docs/reference/glib/tmpl/shell.sgml

@@ -2,7 +2,7 @@
 Shell-related Utilities
 
 <!-- ##### SECTION Short_Description ##### -->
-
+shell-like commandline handling
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/spawn.sgml

@@ -1,8 +1,8 @@
 <!-- ##### SECTION Title ##### -->
-Spawning Processes (fork/exec)
+Spawning Processes
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Process launching with <function>fork()</function>/<function>exec()</function>
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/unicode.sgml

@@ -2,16 +2,31 @@
 Unicode Manipulation
 
 <!-- ##### SECTION Short_Description ##### -->
-
+functions operating on Unicode characters and UTF-8 strings.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+This section describes a number of functions for dealing with
+Unicode characters and strings.  There are analogues of the
+traditional <filename>ctype.h</filename> character classification
+and case conversion functions, UTF-8 analogues of some string utility 
+functions, functions to perform normalization, case conversion and
+collation on UTF-8 strings and finally functions to convert between
+the UTF-8, UTF-16 and UCS-4 encodings of Unicode.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
+<variablelist>
 
+<varlistentry>
+<term>g_locale_to_utf8(), g_locale_from_utf8()</term>
+<listitem><para>
+Convenience functions for converting between UTF-8 and the locale encoding. 
+</para></listitem>
+</varlistentry>
+
+</variablelist>
 </para>
 
 <!-- ##### TYPEDEF gunichar ##### -->

docs/reference/glib/tmpl/windows.sgml

@@ -2,7 +2,7 @@
 Windows Compatibility Functions
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Unix emulation on Windows
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

glib/giochannel.c

@@ -160,7 +160,7 @@ g_io_error_get_from_g_error (GIOStatus status,
  * @count: the number of bytes to read from the #GIOChannel.
  * @bytes_read: returns the number of bytes actually read. 
  * 
- * Reads data from a #GIOChannel. This function is depricated. New code should
+ * Reads data from a #GIOChannel. This function is deprecated. New code should
  * use g_io_channel_read_chars() instead.
  * 
  * Return value: %G_IO_ERROR_NONE if the operation was successful. 
@@ -195,7 +195,7 @@ g_io_channel_read (GIOChannel *channel,
  * @count: the number of bytes to write.
  * @bytes_written:  the number of bytes actually written.
  * 
- * Writes data to a #GIOChannel. This function is depricated. New code should
+ * Writes data to a #GIOChannel. This function is deprecated. New code should
  * use g_io_channel_write_chars() instead.
  * 
  * Return value:  %G_IO_ERROR_NONE if the operation was successful.
@@ -232,8 +232,8 @@ g_io_channel_write (GIOChannel  *channel,
  *        file).
  * 
  * Sets the current position in the #GIOChannel, similar to the standard library
- * function fseek(). This function is depricated. New code should
+ * function <function>fseek()</function>. This function is deprecated. New 
- * use g_io_channel_seek_position() instead.
+ * code should use g_io_channel_seek_position() instead.
  * 
  * Return value: %G_IO_ERROR_NONE if the operation was successful.
  **/
@@ -278,7 +278,7 @@ g_io_channel_seek  (GIOChannel   *channel,
  * g_io_channel_new_file:
  * @filename: A string containing the name of a file.
  * @mode: One of "r", "w", "a", "r+", "w+", "a+". These have
- *        the same meaning as in fopen().
+ *        the same meaning as in <function>fopen()</function>.
  * @error: A location to return an error of type %G_IO_FILE_ERROR.
  *
  * Open a file @filename as a #GIOChannel using mode @mode. This
@@ -592,7 +592,7 @@ g_io_channel_error_from_errno (gint en)
  * @channel: a #GIOChannel
  * @size: the size of the buffer. 0 == pick a good size
  *
- * Set the buffer size.
+ * Sets the buffer size.
  **/  
 void
 g_io_channel_set_buffer_size (GIOChannel	*channel,
@@ -613,7 +613,7 @@ g_io_channel_set_buffer_size (GIOChannel	*channel,
  * g_io_channel_get_buffer_size:
  * @channel: a #GIOChannel
  *
- * Get the buffer size.
+ * Gets the buffer size.
  *
  * Return value: the size of the buffer.
  **/  
@@ -630,11 +630,11 @@ g_io_channel_get_buffer_size (GIOChannel	*channel)
  * @channel: a #GIOChannel
  * @line_term: The line termination string. Use %NULL for auto detect.
  *             Auto detection breaks on "\n", "\r\n", "\r", "\0", and
- *             the unicode paragraph separator. Auto detection should
+ *             the Unicode paragraph separator. Auto detection should
  *             not be used for anything other than file-based channels.
  * @length: The length of the termination string. If -1 is passed, the
- *          string is assumed to be null terminated. This option allows
+ *          string is assumed to be nul-terminated. This option allows
- *          termination strings with embeded nulls.
+ *          termination strings with embeded nuls.
  *
  * This sets the string that #GIOChannel uses to determine
  * where in the file a line break occurs.
@@ -685,10 +685,10 @@ g_io_channel_get_line_term (GIOChannel	*channel,
 /**
  * g_io_channel_set_flags:
  * @channel: a #GIOChannel.
- * @flags: the flags to set on the channel.
+ * @flags: the flags to set on the IO channel.
  * @error: A location to return an error of type #GIOChannelError.
  *
- * Sets flags on the channel.
+ * Sets flags on the IO channel.
  *
  * Return value: the status of the operation. 
  **/
@@ -716,7 +716,7 @@ g_io_channel_set_flags (GIOChannel *channel,
  * The values of the flags %G_IO_FLAG_IS_READABLE and %G_IO_FLAG_IS_WRITEABLE
  * are cached for internal use by the channel when it is created.
  * If they should change at some later point (e.g. partial shutdown
- * of a socket with the unix shutdown () function), the user
+ * of a socket with the Unix <function>shutdown()</function> function), the user
  * should immediately call g_io_channel_get_flags () to update
  * the internal values of these flags.
  *
@@ -890,11 +890,11 @@ g_io_channel_seek_position	(GIOChannel* channel,
  * @channel: a #GIOChannel
  * @error: location to store an error of type #GIOChannelError
  *
- * Flush the write buffer for the GIOChannel.
+ * Flushes the write buffer for the GIOChannel.
  *
  * Return value: the status of the operation: One of
- *   G_IO_CHANNEL_NORMAL, G_IO_CHANNEL_AGAIN, or
+ *   #G_IO_CHANNEL_NORMAL, #G_IO_CHANNEL_AGAIN, or
- *   G_IO_CHANNEL_ERROR.
+ *   #G_IO_CHANNEL_ERROR.
  **/
 GIOStatus
 g_io_channel_flush (GIOChannel	*channel,
@@ -937,7 +937,7 @@ g_io_channel_flush (GIOChannel	*channel,
  *
  * A buffered channel can only be set unbuffered if the channel's
  * internal buffers have been flushed. Newly created channels or
- * channels which have returned G_IO_STATUS_EOF
+ * channels which have returned %G_IO_STATUS_EOF
  * not require such a flush. For write-only channels, a call to
  * g_io_channel_flush () is sufficient. For all other channels,
  * the buffers may be flushed by a call to g_io_channel_seek_position ().
@@ -993,7 +993,7 @@ g_io_channel_get_buffered	(GIOChannel *channel)
  * @encoding: the encoding type
  * @error: location to store an error of type #GConvertError.
  *
- * Set the encoding for the input/output of the channel. The internal
+ * Sets the encoding for the input/output of the channel. The internal
  * encoding is always UTF-8. The default encoding for the
  * external file is UTF-8.
  *
@@ -1012,15 +1012,15 @@ g_io_channel_get_buffered	(GIOChannel *channel)
  *
  * 4. The current encoding is %NULL or UTF-8.
  *
- * 5. One of the (new API) read functions has just returned G_IO_STATUS_EOF
+ * 5. One of the (new API) read functions has just returned %G_IO_STATUS_EOF
- *    (or, in the case of g_io_channel_read_to_end (), G_IO_STATUS_NORMAL).
+ *    (or, in the case of g_io_channel_read_to_end (), %G_IO_STATUS_NORMAL).
  *
  * 6. One of the functions g_io_channel_read_chars () or g_io_channel_read_unichar ()
- *    has returned G_IO_STATUS_AGAIN or G_IO_STATUS_ERROR. This may be
+ *    has returned %G_IO_STATUS_AGAIN or %G_IO_STATUS_ERROR. This may be
- *    useful in the case of G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
+ *    useful in the case of %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
  *    Returning one of these statuses from g_io_channel_read_line (),
  *    g_io_channel_read_line_string (), or g_io_channel_read_to_end ()
- *    does _not_ guarantee that the encoding can be changed.
+ *    does <emphasis>not</emphasis> guarantee that the encoding can be changed.
  *
  * Channels which do not meet the above conditions cannot call
  * g_io_channel_seek_position () with an offset of %G_SEEK_CUR,
@@ -1028,7 +1028,7 @@ g_io_channel_get_buffered	(GIOChannel *channel)
  * call g_io_channel_write_chars () after calling one
  * of the API "read" functions.
  *
- * Return Value: %G_IO_STATUS_NORMAL if the encoding was succesfully set.
+ * Return Value: %G_IO_STATUS_NORMAL if the encoding was successfully set.
  **/
 GIOStatus
 g_io_channel_set_encoding (GIOChannel	*channel,
@@ -1158,7 +1158,7 @@ g_io_channel_set_encoding (GIOChannel	*channel,
  * g_io_channel_get_encoding:
  * @channel: a #GIOChannel
  *
- * Get the encoding for the input/output of the channel. The internal
+ * Gets the encoding for the input/output of the channel. The internal
  * encoding is always UTF-8. The encoding %NULL makes the
  * channel safe for binary data.
  *
@@ -1350,20 +1350,19 @@ reencode:
  * @channel: a #GIOChannel
  * @str_return: The line read from the #GIOChannel, not including the
  *              line terminator. This data should be freed with g_free()
- *              when no longer needed. This
+ *              when no longer needed. This is a nul-terminated string. 
- *              is a null terminated string. If a @length of zero is
+ *              If a @length of zero is returned, this will be %NULL instead.
- *              returned, this will be %NULL instead.
  * @length: location to store length of the read data, or %NULL
  * @terminator_pos: location to store position of line terminator, or %NULL
  * @error: A location to return an error of type #GConvertError
  *         or #GIOChannelError
  *
- * Read a line, including the terminating character(s),
+ * Reads a line, including the terminating character(s),
- * from a #GIOChannel into a newly allocated string.
+ * from a #GIOChannel into a newly-allocated string.
  * @length will contain allocated memory if the return
  * is %G_IO_STATUS_NORMAL.
  *
- * Return value: a newly allocated string. Free this string
+ * Return value: a newly-allocated string. Free this string
  *   with g_free() when you are done with it.
  **/
 GIOStatus
@@ -1409,7 +1408,7 @@ g_io_channel_read_line (GIOChannel *channel,
  * @error: a location to store an error of type #GConvertError
  *         or #GIOChannelError
  *
- * Read a line from a #GIOChannel, using a #GString as a buffer.
+ * Reads a line from a #GIOChannel, using a #GString as a buffer.
  *
  * Return value: the status of the operation.
  **/
@@ -1613,13 +1612,13 @@ done:
  * @str_return: Location to store a pointer to a string holding
  *              the remaining data in the #GIOChannel. This data should
  *              be freed with g_free() when no longer needed. This
- *              data is terminated by an extra null, but there may be other
+ *              data is terminated by an extra nul character, but there 
- *              nulls in the intervening data.
+ *              may be other nuls in the intervening data.
  * @length: Location to store length of the data
  * @error: A location to return an error of type #GConvertError
  *         or #GIOChannelError
  *
- * Read all the remaining data from the file.
+ * Reads all the remaining data from the file.
  *
  * Return value: %G_IO_STATUS_NORMAL on success. This function never
  *               returns %G_IO_STATUS_EOF.
@@ -1873,7 +1872,7 @@ g_io_channel_read_unichar     (GIOChannel   *channel,
  * @channel: a #GIOChannel
  * @buf: a buffer to write data from
  * @count: the size of the buffer. If -1, the buffer
- *         is taken to be a nul terminated string.
+ *         is taken to be a nul-terminated string.
  * @bytes_written: The number of bytes written. This can be nonzero
  *                 even if the return value is not %G_IO_STATUS_NORMAL.
  *                 If the return value is %G_IO_STATUS_NORMAL and the