Various cosmetic improvements to documentation

This comes from the GitHub pull request #24
no-tn-check no-precommit-check

Change-Id: I610e6e3a0c09754b23bb4b4fcc23adcc2af28597

docs/conf.py

@@ -51,9 +51,10 @@ def get_copyright():
 
 def get_version():
     """Extract the version from configure.in"""
-    for line in open("../configure.in").readlines():
-        if line.startswith("AC_INIT"):
-            return line.split(",")[1]
+    with open("../configure.in") as configure_in:
+        for line in configure_in.readlines():
+            if line.startswith("AC_INIT"):
+                return line.split(",")[1]
     raise Exception("Cannot find version number")
 
 

docs/dom.rst

@@ -6,7 +6,7 @@ The DOM module
 
 DOM is another standard associated with XML, in which the XML stream is
 represented as a tree in memory. This tree can be manipulated at will, to add
-new nodes, remove existing nodes, change attributes,...
+new nodes, remove existing nodes, change attributes...
 
 Since it contains the whole XML information, it can then in turn be dumped to a
 stream.
@@ -103,20 +103,19 @@ fully.
 
 One important note however is related to the use of strings. Various
 subprograms allow you to set the textual content of a node, modify its
-attributes,.... Such subprograms take a Byte_Sequence as a parameter.
+attributes... Such subprograms take a Byte_Sequence as a parameter.
 
 This Byte_Sequence must always be encoded in the encoding defined in the
 package `Sax.Encoding` (as described earlier, changing this package requires
 recompiling XML/Ada). By default, this is UTF-8.
 
-.. highlight:: ada
-
 Therefore, if you need to set an attribute to a string encoded for
 instance in iso-8859-15, you should use the subprogram
 `Unicode.Encodings.Convert` to convert it appropriately.
-The code would thus look as follows::
+The code would thus look as follows:
 
-    Set_Attribute (N, Convert ("å", From => Get_By_Name ("iso-8859-15")));
+.. literalinclude:: dom/convert.adb
+   :language: ada
 
 Printing DOM tress
 ==================

docs/dom/convert.adb

@@ -0,0 +1 @@
+Set_Attribute (N, Convert ("å", From => Get_By_Name ("iso-8859-15")));

docs/input.rst

@@ -58,13 +58,13 @@ detect the encoding to use for a file, based on a header read directly from the
 file.
 
 Based on the first four bytes of the stream (assuming this is valid XML), they
-will automatically detect whether the file was encoded as Utf8, Utf16,... If
+will automatically detect whether the file was encoded as Utf8, Utf16... If
 you are writing your own input streams, consider adding this automatic
 detection as well.
 
 However, it is always possible to override the default through a call to
-`Set_Encoding`. This allows you to specify both the character set (Latin1, ...)
-and the character encoding scheme (Utf8,...).
+`Set_Encoding`. This allows you to specify both the character set (Latin1...)
+and the character encoding scheme (Utf8...).
 
 The user is also encouraged to set the identifiers for the stream they are
 parsing, through calls to `Set_System_Id` and `Set_Public_Id`. These are used

docs/schema.rst

@@ -14,7 +14,7 @@ XML files:
 
   This is a basic step where we ensure that XML tags are correctly nested, that
   closing tags have the same names as the matching opening tags, that attribute
-  values are quoted,.... This corresponds to a syntactic parser in a compiler.
+  values are quoted... This corresponds to a syntactic parser in a compiler.
 
   This step does not depend on the application domain. One file that is
   well-formed will always be so, no matter in what context you use it.
@@ -27,7 +27,7 @@ XML files:
 
   This is the phase in which the application needs to check whether a given XML
   file has all its required attributes, whether the children of an XML tag are
-  the expected ones, whether the type of the attributes is valid,....
+  the expected ones, whether the type of the attributes is valid...
 
 * Use the XML file in the application.
 
@@ -63,7 +63,7 @@ satisfy in order to be considered as valid.
   The XML schemas are replacing the DTDs. They are written in XML, and provide
   an extensive capability to describe what the XML document should look like.
   In fact, almost all Ada types can be described in an XML schema, including
-  range constraints, arrays, records, type inheritance, abstract types,....
+  range constraints, arrays, records, type inheritance, abstract types...
 
   It is for instance possible to indicate that the value of a preference, in
   our example, must be a string of length 6. Any other length will result in a
@@ -84,8 +84,8 @@ a tutorial (`http://www.w3.org/TR/xmlschema-0/
 
 The typical extension for a schema file is :file:`.xsd`.
 
-A schema file must be a valid XML file, and thus start with the usual `<?xml
-version="1.0" ?>` line. The root node must be named `schema`, and belong to the
+A schema file must be a valid XML file, and thus start with the usual
+``<?xml version="1.0" ?>`` line. The root node must be named `schema`, and belong to the
 namespace (`http://www.w3.org/2001/XMLSchema/
 <http://www.w3.org/2001/XMLSchema/>`_). The handling of namespaces is fairly
 powerful, but also complex. A given XML document might have nodes belonging to
@@ -114,13 +114,12 @@ The contents of the element is then defined in one of two ways:
 
   Schemas come with a number of predefined simple types. A simple type is
   such that an element of that type accepts no child node, and that its
-  contents must satisfy additional constraints (be an integer, a date,
-  ...).
+  contents must satisfy additional constraints (be an integer, a date...).
 
   Among the predefined simple types (which are all defined in the namespace
   `http://www.w3.org/2001/XMLSchema/ <http://www.w3.org/2001/XMLSchema/>`_),
   one can find: `string`, `integer`, `byte`, `date`, `time`, `dateTime`,
-  `boolean`,...
+  `boolean`...
 
   If no additional constraint should be enforced on this simple type when
   applied to the element, the type of the element is given through a `type`
@@ -337,7 +336,7 @@ validating a file.
 
     This attribute is a list of strings, alternatively the prefix of
     a namespace and the name of an xsd file to use for that
-    namespace. For instance, `"ns1 file1.xsd ns2 file2.xsd"`.
+    namespace. For instance, ``"ns1 file1.xsd ns2 file2.xsd"``.
 
   When it encounters any of these two attributes, XML/Ada will
   automatically parse the corresponding schema files, and use the result
@@ -368,7 +367,7 @@ using SAX itself. Instead of inheriting from `Sax.Readers.Reader`, your tagged
 type must inherit from `Schema.Readers.Validating_Reader`.
 
 As usual, you can still override the predefined primitive operations like
-`Start_Element`, `End_Element`, ...
+`Start_Element`, `End_Element`...
 
 Note the activation of the `Schema_Validation_Feature` feature, without which
 no validation takes place:

docs/unicode.rst

@@ -85,7 +85,7 @@ a portable manner.
 
 Given its size, most applications will only support a subset of Unicode.  Some
 of the scripts, most notably Arabic and Asian languages, require a special
-support in the application (right-to-left writing,...), and thus will not be
+support in the application (right-to-left writing...), and thus will not be
 supported by some applications.
 
 The Unicode standard includes a set of internal catalogs, called collections.
@@ -293,10 +293,10 @@ single type, `Unicode.Encodings.Unicode_Encoding`.
 
 This package provides additional functions to manipulate these encodings, for
 instance to retrieve them by the common name that is associated with them (for
-instance "utf-8", "iso-8859-15",...), since very often the encoding scheme is
+instance ``utf-8``, ``iso-8859-15``...), since very often the encoding scheme is
 implicit. If you are speaking of utf-8 string, most people always assume you
 also use the unicode character set. Likewise, if you are speaking of
-"iso-8859-1", most people will assume you string is encoded as 8 byte
+``iso-8859-1``, most people will assume you string is encoded as 8 byte
 characters.
 
 The goal of the `Unicode.Encodings` package is to make these implicit

docs/using.rst

@@ -34,7 +34,7 @@ and you build your application with::
 Note in the project file the first line, which indicates that your
 application requires XML/Ada to build. This will automatically set the
 appropriate compiler and linker switches to use XML/Ada. Your application
-will be linked against all modules of XML/Ada (DOM, SAX, ...).
+will be linked against all modules of XML/Ada (DOM, SAX...).
 
 If your application doesn't use DOM, you can replace the first line with
 something like::
@@ -78,7 +78,7 @@ Running on VxWorks
 
 On VxWorks, XML Ada processing might require more stack space than what is
 typically available from the VxWorks shell, the tasks spawned from there with
-"sp", or Ada tasks with no or a too small Storage_Size value attached.
+``sp``, or Ada tasks with no or a too small Storage_Size value attached.
 
 Such stack overflow conditions are typically characterized by non-deterministic
 erratic behavior and can be cured by allocating more stack space for the tasks