libsmartcol docs: Format samples, lists, tables

Use gtk-doc constructs to mark up formatted sections of documentation
so that they display properly in the rendered output.

- Enclose code samples with informalexample+programlisting tags
- Enclose preformatted blocks of text (tables) in same
- Present numbered lists in markdown format (leading 1., 2., etc.)
  so that they're translated into HTML ordered lists

Signed-off-by: FeRD (Frank Dana) <ferdnyc@gmail.com>

diff --git a/libsmartcols/src/column.c b/libsmartcols/src/column.c
index 28def306053c0c1c9b644d2e0c8d641ccbd4ee8b..8c4621c94a8daf80f8277c986676d57f4d948c17 100644 (file)
--- a/libsmartcols/src/column.c
+++ b/libsmartcols/src/column.c
@@ -447,12 +447,15 @@ const char *scols_column_get_color(const struct libscols_column *cl)
  * The final cell URI is composed of the column-uri, cell-uri, and cell-data.
  * The column-uri and/or cell-uri must be set for this feature to be enabled.
  *
+ * <informalexample>
+ * <programlisting>
  * column-uri  cell-uri                  cell-data      final-URI                 link
- * -----------------------------------------------------------------------------------
+ * --------------------------------------------------------------------------------------------
  *             file://host/path/foo.txt  foo            file://host/path/foo.txt  foo
  * file://host /path/foo.txt             foo            file://host/path/foo.txt  foo
  * file://host                           /path/foo.txt  file://host/path/foo.txt  /path/foo.txt
- *
+ * </programlisting>
+ * </informalexample>
  *
  * Returns: 0, a negative value in case of an error.
  */

diff --git a/libsmartcols/src/table.c b/libsmartcols/src/table.c
index dc6a3a74b1169092f5c894e08a11af860c67ec44..aa7cdf3c6cef5d92fcc470f7765f20fac7b375b9 100644 (file)
--- a/libsmartcols/src/table.c
+++ b/libsmartcols/src/table.c
@@ -365,16 +365,24 @@ int scols_table_move_column(struct libscols_table *tb,
  *
  * This is shortcut for
  *
- *   cl = scols_new_column();
- *   scols_column_set_....(cl, ...);
- *   scols_table_add_column(tb, cl);
+ * <informalexample>
+ *   <programlisting language="C">
+ *     cl = scols_new_column();
+ *     scols_column_set_....(cl, ...);
+ *     scols_table_add_column(tb, cl);
+ *   </programlisting>
+ * </informalexample>
  *
  * The column width is possible to define by:
  *
- *  @whint: 0 < N < 1  : relative width, percent of terminal width
+ * <informalexample>
+ * <programlisting>
+ * whint: 0 < N < 1  : relative width, percent of terminal width
  *
- *  @whint: N >= 1     : absolute width, empty column will be truncated to
+ * whint: N >= 1     : absolute width, empty column will be truncated to
  *                     the column header width if no specified STRICTWIDTH flag
+ * </programlisting>
+ * </informalexample>
  *
  * Note that if table has disabled "maxout" flag (disabled by default) than
  * relative width is used as a hint only. It's possible that column will be
@@ -384,12 +392,12 @@ int scols_table_move_column(struct libscols_table *tb,
  * If the width of all columns is greater than terminal width then library
  * tries to reduce width of the individual columns. It's done in three stages:
  *
- * #1 reduce columns with SCOLS_FL_TRUNC flag and with relative width if the
+ * 1. reduce columns with SCOLS_FL_TRUNC flag and with relative width if the
  *    width is greater than width defined by @whint (@whint * terminal_width)
  *
- * #2 reduce all columns with SCOLS_FL_TRUNC flag
+ * 2. reduce all columns with SCOLS_FL_TRUNC flag
  *
- * #3 reduce all columns with relative width
+ * 3. reduce all columns with relative width
  *
  * The next stage is always used if the previous stage is unsuccessful. Note
  * that SCOLS_FL_WRAP is interpreted as SCOLS_FL_TRUNC when calculate column
@@ -400,12 +408,16 @@ int scols_table_move_column(struct libscols_table *tb,
  * The column is necessary to address by sequential number. The first defined
  * column has the colnum = 0. For example:
  *
- *     scols_table_new_column(tab, "FOO", 0.5, 0);             // colnum = 0
- *     scols_table_new_column(tab, "BAR", 0.5, 0);             // colnum = 1
- *      .
- *      .
- *     scols_line_get_cell(line, 0);                           // FOO column
- *     scols_line_get_cell(line, 1);                           // BAR column
+ * <informalexample>
+ *   <programlisting language="C">
+ *     scols_table_new_column(tab, "FOO", 0.5, 0);    // colnum = 0
+ *     scols_table_new_column(tab, "BAR", 0.5, 0);    // colnum = 1
+ *     .
+ *     .
+ *     scols_line_get_cell(line, 0);                  // FOO column
+ *     scols_line_get_cell(line, 1);                  // BAR column
+ *   </programlisting>
+ * </informalexample>
  *
  * Returns: newly allocated column
  */
@@ -801,10 +813,13 @@ int scols_table_next_line(struct libscols_table *tb,
  *
  * This is shortcut for
  *
- *   ln = scols_new_line();
- *   scols_table_add_line(tb, ln);
- *   scols_line_add_child(parent, ln);
- *
+ * <informalexample>
+ *   <programlisting language="C">
+ *     ln = scols_new_line();
+ *     scols_table_add_line(tb, ln);
+ *     scols_line_add_child(parent, ln);
+ *   </programlisting>
+ * </informalexample>
  *
  * Returns: newly allocate line
  */