Merge branch 'develop'

doc/Makefile.am

@@ -8,7 +8,7 @@
 # using the SOFTWARE, you agree to be bound by the terms of that
 # LICENSE.
 
-doc docs: xolint.rst html
+doc docs: xolint-errors.rst html
 
 #
 # The contents of xolint.rst is generated based on xolint.pl, since we
@@ -17,8 +17,8 @@ doc docs: xolint.rst html
 # the developer needs to commit any changes.
 #
 
-xolint.rst: ${top_srcdir}/xolint/xolint.pl
-	perl ${top_srcdir}/xolint/xolint.pl -D > ${top_srcdir}/doc/xolint.rst
+xolint-errors.rst: ${top_srcdir}/xolint/xolint.pl
+	perl ${top_srcdir}/xolint/xolint.pl -D > ${top_srcdir}/doc/xolint-errors.rst
 
 SPHINX = python3 -msphinx
 

doc/api.rst

@@ -386,19 +386,18 @@ xo_destroy
 Emitting Content (xo_emit)
 --------------------------
 
-The functions in this section are used to emit output.
-
-The "fmt" argument is a string containing field descriptors as
-specified in :ref:`format-strings`.  The use of a handle is optional and
-`NULL` can be passed to access the internal "default" handle.  See
+The functions in this section are used to emit output.  They use a
+`format` string containing field descriptors as specified in
+:ref:`format-strings`.  The use of a handle is optional and `NULL` can
+be passed to access the internal "default" handle.  See
 :ref:`handles`.
 
 The remaining arguments to `xo_emit` and `xo_emit_h` are a set of
 arguments corresponding to the fields in the format string.  Care must
 be taken to ensure the argument types match the fields in the format
-string, since an inappropriate cast can ruin your day.  The vap
-argument to `xo_emit_hv` points to a variable argument list that can
-be used to retrieve arguments via `va_arg`.
+string, since an inappropriate or missing argument can ruin your day.
+The `vap` argument to `xo_emit_hv` points to a variable argument list
+that can be used to retrieve arguments via `va_arg`.
 
 .. c:function:: xo_ssize_t xo_emit (const char *fmt, ...)
 
@@ -428,19 +427,40 @@ be used to retrieve arguments via `va_arg`.
 Single Field Emitting Functions (xo_emit_field)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The functions in this section can also make output, but only make a
-single field at a time.  These functions are intended to avoid the
-scenario where one would otherwise need to compose a format
-descriptors using `snprintf`.  The individual parts of the format
-descriptor are passed in distinctly.
-
-.. c:function:: xo_ssize_t xo_emit_field (const char *rolmod, const char *contents, const char *fmt, const char *efmt, ...)
+The functions in this section emit formatted output similar to
+`xo_emit` but where `xo_emit` uses a single string argument containing
+the description for multiple fields, `xo_emit_field` emits a single
+field using multiple ar- guments to contain the field description.
+`xo_emit_field_h` adds an ex- plicit handle to use instead of the
+default handle, while `xo_emit_field_hv` accepts a va_list for
+additional flexibility.
+
+The arguments `rolmod`, `content`, `fmt`, and `efmt` are detailed in
+:ref:`field-formatting`.  Using distinct arguments allows callers to
+pass the field description in pieces, rather than having to use
+something like `snprintf` to build the format string required by
+`xo_emit`.  The arguments are each NUL-terminated strings. The `rolmod`
+argument contains the `role` and `modifier` portions of the field
+description, the `content` argument contains the `content` portion, and
+the `fmt` and `efmt` contain the `field-format` and `encoding-format` por-
+tions, respectively.
+
+As with `xo_emit`, the `fmt` and `efmt` values are both optional,
+since the `field-format` string defaults to "%s", and the
+`encoding-format`'s default value is derived from the `field-format`
+per :ref:`field-formatting`.  However, care must be taken to avoid
+using a value directly as the format, since characters like '{', '%',
+and '}' will be interpreted as formatting directives, and may cause
+xo_emit_field to dereference arbitrary values off the stack, leading
+to bugs, core files, and gnashing of teeth.
+
+.. c:function:: xo_ssize_t xo_emit_field (const char *rolmod, const char *content, const char *fmt, const char *efmt, ...)
 
   :param rolmod: A comma-separated list of field roles and field modifiers
   :type rolmod: const char *
-  :param contents: The "contents" portion of the field description string
-  :type contents: const char *
-  :param fmt: Content format string
+  :param content: The "content" portion of the field description string
+  :type content: const char *
+  :param fmt: Contents format string
   :type fmt: const char *
   :param efmt: Encoding format string, followed by additional arguments
   :type efmt: const char *
@@ -450,8 +470,11 @@ descriptor are passed in distinctly.
   ::
 
     EXAMPLE::
+        xo_emit_field("T", title, NULL, NULL, NULL);
         xo_emit_field("T", "Host name is ", NULL, NULL);
         xo_emit_field("V", "host-name", NULL, NULL, host-name);
+        xo_emit_field(",leaf-list,quotes", "sku", "%s-%u", "%s-000-%u",
+                        "gum", 1412);
 
 .. c:function:: xo_ssize_t xo_emit_field_h (xo_handle_t *xop, const char *rolmod, const char *contents, const char *fmt, const char *efmt, ...)
 

doc/faq.rst

@@ -205,4 +205,7 @@ a difference, change the names to make that difference more obvious.
 What does this message mean?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. include:: xolint.rst
+.. toctree::
+    :maxdepth: 2
+
+    xolint-errors.rst

doc/field-formatting.rst

@@ -1,5 +1,6 @@
 
 .. index:: Field Formatting
+.. _field-formatting:
 
 Field Formatting
 ----------------