Merge branch 'release/debian/4.10-1'debian/4.10-1

1 files changed, 142 insertions, 0 deletions

diff --git a/doc/libHX_Documentation.rst b/doc/libHX_Documentation.rst
new file mode 100644
index 0000000..710e265
--- /dev/null
+++ b/doc/libHX_Documentation.rst
@@ -0,0 +1,142 @@
+===================
+libHX Documentation
+===================
+
+libHX collects many useful day-to-day functions, intended to reduce the amount
+of otherwise repeatedly open-coded instructions.
+
+Overview
+========
+
+* Maps (key-value pairs)
+
+  Originally created to provide a data structure like Perl's associative
+  arrays. Different map types and characteristics are available, such as
+  hash-based or the traditional rbtree.
+
+* Linked lists (Deques)
+
+  Double-ended queues, implemented as a doubly-linked list with sentinels, are
+  suitable for both providing stack and queue functionality.
+
+* Inline doubly-linked list, uncounted and counted
+
+  Light-weight linked lists as used in the Linux kernel.
+
+* Common string operations
+
+  ``basename``, ``chomp``, ``dirname``, ``getl``/``getline``, ``split``,
+  ``strlcat``/``strlcpy``, ``strlower``/``strupper``, ``str*trim``, ``strsep``,
+  etc.
+
+* Memory container, auto-sizing string operations
+
+  Scripting-like invocation for string handling — automatically doing
+  (re)allocations as needed.
+
+* String formatter (Format templates)
+
+  HXfmt is a template system for by-name variable expansion. It can be used to
+  substitute placeholders in format strings supplied by the user by appropriate
+  expanded values defined by the program.
+
+* Directory functions
+
+  Directory creation, traversal, removal, and file copying.
+
+* Option parsing
+
+  Table-/callback-based option parser that works similar to Perl's
+  Getopt::Long — no open-coding but a single “atomic” invocation.
+
+* Shell-style config parser
+
+  Configuration file reader for Shell-style “configuration” files
+  with key-value pairs, as usually foudn in ``/etc/sysconfig``.
+
+* Random number gathering
+
+  Convenient wrapper that uses kernel-provided RNG devices when
+  available.
+
+* External process invocation
+
+  Setting up pipes for the standard file descriptors for
+  sending/capturing data to/from a program.
+
+* a bit more beyond that ... Miscellaneous
+
+
+General reading
+===============
+
+* `Installation <install.rst>`_ (if you do not have a binray package from a
+  distro yet)
+* `History <history.rst>`_ remarks
+
+
+First things first
+==================
+
+Many functions are prefixed with ``HX_`` or ``HXsubsys_``, as are structures
+(sometimes without underscores, be sure to check the syntax and names), to
+avoid name clashes with possibly existing files. Functions that are not tied to
+a specific data structure such as most of the string functions use the
+subsystem-less prefix, ``HX_``. Functions from a clearly-defined subsystem,
+such as map or deque, augment the base prefix by a suffix, forming e.g.
+``HXmap_``.
+
+* `Library initialization <init.rst>`_
+
+
+Data structures
+===============
+
+* `Bitmaps <bitmaps.rst>`_
+* `Maps <maps.rst>`_
+* `Linked lists <linked_list.rst>`_
+* `Inline lists <inline_list.rst>`_
+* `Counted inline lists <inline_clist.rst>`_
+
+
+Strings and memory
+==================
+
+* `String operations <string_ops.rst>`_
+* `Memory containers <memory_container.rst>`_
+* `String formatter <string_formatter.rst>`_
+* Everything with `Files and directories <files_and_dirs.rst>`_
+
+
+Options and configuration files
+===============================
+
+* `Option parsing <option_parsing.rst>`_
+* `Shell-style config file parser <shconfig.rst>`_
+
+
+Systems-related components
+==========================
+
+* `Time functions <time_functions.rst>`_
+* `Random numbers <random_number.rst>`_
+* `Process functions <process_functions.rst>`_
+
+
+Miscellaneous
+=============
+
+* `Type-checking casts <typechecking_casts.rst>`_
+* `Helper headers <helper_headers.rst>`_ for other software
+* `Macros <macros.rst>`_
+* `Misc functions <misc_functions.rst>`_ that did not fit in any other category
+
+
+Resources
+=========
+
+As of this writing, the repository is located at
+
+* git://git.inai.de/libhx — clone URL
+
+* https://inai.de/projects/libhx/ — home page (and link to tarballs)