From 3b32e02eecf88c9dccc58a71d7ab54464154a227 Mon Sep 17 00:00:00 2001 From: Nicolas Boulenguez Date: Mon, 25 Jul 2022 04:52:06 +0200 Subject: [PATCH 1/5] docs: remove commas before ellipses A comma before an ellipsis is common in mathematical typography but quite rare in english. --- docs/dom.rst | 4 ++-- docs/input.rst | 6 +++--- docs/schema.rst | 13 ++++++------- docs/unicode.rst | 4 ++-- docs/using.rst | 2 +- 5 files changed, 14 insertions(+), 15 deletions(-) diff --git a/docs/dom.rst b/docs/dom.rst index 200fecf..3d8dd6f 100644 --- a/docs/dom.rst +++ b/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,7 +103,7 @@ 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 diff --git a/docs/input.rst b/docs/input.rst index a484a35..3b62055 100644 --- a/docs/input.rst +++ b/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 diff --git a/docs/schema.rst b/docs/schema.rst index 2b83409..9ae0410 100644 --- a/docs/schema.rst +++ b/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 @@ -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/ `_), 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` @@ -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: diff --git a/docs/unicode.rst b/docs/unicode.rst index 4acd35f..835e281 100644 --- a/docs/unicode.rst +++ b/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,7 +293,7 @@ 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 diff --git a/docs/using.rst b/docs/using.rst index eff781b..e54ed0d 100644 --- a/docs/using.rst +++ b/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:: From d1b32d3b1d96115eecbcce857056038d42ddf673 Mon Sep 17 00:00:00 2001 From: Nicolas Boulenguez Date: Mon, 25 Jul 2022 05:09:38 +0200 Subject: [PATCH 2/5] docs: quote raw text with double backquotes The ReStructured Text variant used by sphinxdoc recommends two consecutive backquotes for raw text. Single backquote or double quotes sometimes work, but interact poorly with each other. --- docs/schema.rst | 6 +++--- docs/unicode.rst | 4 ++-- docs/using.rst | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/schema.rst b/docs/schema.rst index 9ae0410..f5c4692 100644 --- a/docs/schema.rst +++ b/docs/schema.rst @@ -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 `` 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 +```` line. The root node must be named `schema`, and belong to the namespace (`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 @@ -336,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 diff --git a/docs/unicode.rst b/docs/unicode.rst index 835e281..ab0fbc7 100644 --- a/docs/unicode.rst +++ b/docs/unicode.rst @@ -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 diff --git a/docs/using.rst b/docs/using.rst index e54ed0d..f696193 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -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 From bd5bb267d8aca89dd3cf486e47366b414b9f43ab Mon Sep 17 00:00:00 2001 From: Nicolas Boulenguez Date: Mon, 25 Jul 2022 07:54:42 +0200 Subject: [PATCH 3/5] docs: move the only non-ASCII character to a one-line separate file Unicode substitutions seem impossible in litteral blocks or code-blocks. --- docs/dom.rst | 7 +++---- docs/dom/convert.adb | 1 + 2 files changed, 4 insertions(+), 4 deletions(-) create mode 100644 docs/dom/convert.adb diff --git a/docs/dom.rst b/docs/dom.rst index 3d8dd6f..2321ef1 100644 --- a/docs/dom.rst +++ b/docs/dom.rst @@ -109,14 +109,13 @@ 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 ================== diff --git a/docs/dom/convert.adb b/docs/dom/convert.adb new file mode 100644 index 0000000..33a8fd3 --- /dev/null +++ b/docs/dom/convert.adb @@ -0,0 +1 @@ +Set_Attribute (N, Convert ("å", From => Get_By_Name ("iso-8859-15"))); From ff8c617718837207c4c2c7c66367295bdeb49a2a Mon Sep 17 00:00:00 2001 From: Nicolas Boulenguez Date: Wed, 27 Jul 2022 00:11:36 +0200 Subject: [PATCH 4/5] docs/conf.py: close configure.in file --- docs/conf.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index be076f8..9619678 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -51,9 +51,10 @@ copyright = 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") From 9e1bd23397f28e84a13419c9c1620ac50722480d Mon Sep 17 00:00:00 2001 From: Nicolas Boulenguez Date: Sat, 6 Aug 2022 11:41:40 +0200 Subject: [PATCH 5/5] docs: remove erroneous execution permissions --- docs/cross/README | 0 docs/cross/dom/default.gpr | 0 docs/cross/dom/domexample.adb | 0 docs/cross/sax/default.gpr | 0 docs/cross/sax/saxexample.adb | 0 docs/cross/sax/saxexample.ads | 0 docs/cross/sax/saxexample_main.adb | 0 docs/cross/schema/default.gpr | 0 docs/cross/schema/schemaexample.adb | 0 tests/examples/domexample2.expected | 0 tests/examples/saxexample_main.expected | 0 11 files changed, 0 insertions(+), 0 deletions(-) mode change 100755 => 100644 docs/cross/README mode change 100755 => 100644 docs/cross/dom/default.gpr mode change 100755 => 100644 docs/cross/dom/domexample.adb mode change 100755 => 100644 docs/cross/sax/default.gpr mode change 100755 => 100644 docs/cross/sax/saxexample.adb mode change 100755 => 100644 docs/cross/sax/saxexample.ads mode change 100755 => 100644 docs/cross/sax/saxexample_main.adb mode change 100755 => 100644 docs/cross/schema/default.gpr mode change 100755 => 100644 docs/cross/schema/schemaexample.adb mode change 100755 => 100644 tests/examples/domexample2.expected mode change 100755 => 100644 tests/examples/saxexample_main.expected diff --git a/docs/cross/README b/docs/cross/README old mode 100755 new mode 100644 diff --git a/docs/cross/dom/default.gpr b/docs/cross/dom/default.gpr old mode 100755 new mode 100644 diff --git a/docs/cross/dom/domexample.adb b/docs/cross/dom/domexample.adb old mode 100755 new mode 100644 diff --git a/docs/cross/sax/default.gpr b/docs/cross/sax/default.gpr old mode 100755 new mode 100644 diff --git a/docs/cross/sax/saxexample.adb b/docs/cross/sax/saxexample.adb old mode 100755 new mode 100644 diff --git a/docs/cross/sax/saxexample.ads b/docs/cross/sax/saxexample.ads old mode 100755 new mode 100644 diff --git a/docs/cross/sax/saxexample_main.adb b/docs/cross/sax/saxexample_main.adb old mode 100755 new mode 100644 diff --git a/docs/cross/schema/default.gpr b/docs/cross/schema/default.gpr old mode 100755 new mode 100644 diff --git a/docs/cross/schema/schemaexample.adb b/docs/cross/schema/schemaexample.adb old mode 100755 new mode 100644 diff --git a/tests/examples/domexample2.expected b/tests/examples/domexample2.expected old mode 100755 new mode 100644 diff --git a/tests/examples/saxexample_main.expected b/tests/examples/saxexample_main.expected old mode 100755 new mode 100644