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") 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/docs/dom.rst b/docs/dom.rst index 200fecf..2321ef1 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,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 ================== 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"))); 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..f5c4692 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 @@ -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 @@ -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` @@ -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: diff --git a/docs/unicode.rst b/docs/unicode.rst index 4acd35f..ab0fbc7 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,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 eff781b..f696193 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:: @@ -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 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