Fixed links in documentation

config.nims

@@ -22,7 +22,11 @@ task documentation, "Generate documentation":
   exec "mkdir -p docout"
   exec r"nim doc2 -o:docout/yaml.html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/`git log -n 1 --format=%H` yaml"
   # bash! ah-ah \\ savior of the universe
-  exec r"find yaml -type f -print0 | while read -d '' -r f; do a=${f#yaml/}; nim doc2 -o:docout/yaml.${a%%.nim}.html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/yaml/`git log -n 1 --format=%H` $f; done"
+  for file in listFiles("yaml"):
+    let packageName = file[5..^5]
+    exec r"nim doc2 -o:docout/yaml." & packageName &
+        ".html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/yaml/`git log -n 1 --format=%H` " &
+        file
   exec r"nim rst2html -o:docout/index.html doc/index.txt"
   exec r"nim rst2html -o:docout/api.html doc/api.txt"
   exec r"nim rst2html -o:docout/serialization.html doc/serialization.txt"

doc/api.txt

@@ -25,8 +25,8 @@ Intermediate Representation
 ===========================
 
 The base of all YAML processing with NimYAML is the
-`YamlStream <yaml.html#YamlStream>`_. This is basically an iterator over
+`YamlStream <yaml.stream.html#YamlStream>`_. This is basically an iterator over
-`YamlStreamEvent <yaml.html#YamlStreamEvent>`_ objects. Every proc that
+`YamlStreamEvent <yaml.stream.html#YamlStreamEvent>`_ objects. Every proc that
 represents a single stage of the loading or dumping process will either take a
 ``YamlStream`` as input or return a ``YamlStream``. Procs that implement the
 whole process in one step hide the ``YamlStream`` from the user. Every proc that
@@ -45,16 +45,17 @@ Loading YAML
 ============
 
 If you want to load YAML character data directly into a native Nim variable, you
-can use `load <yaml.html#load,Stream,K>`_. This is the easiest and recommended
+can use `load <yaml.serialization.html#load,,K>`_. This is the easiest and
-way to load YAML data. The following paragraphs will explain the steps involved.
+recommended way to load YAML data. This section gives an overview about how
+``load`` is implemented. It is absolutely possible to reimplement the loading
+step using the low-level API.
 
-For parsing, a `YamlParser <yaml.html#YamlParser>`_ object is needed. This
+For parsing, a `YamlParser <yaml.parser.html#YamlParser>`_ object is needed.
-object stores some state while parsing that may be useful for error reporting to
+This object stores some state while parsing that may be useful for error
-the user. The
+reporting to the user. The `parse <yaml.parser.html#parse,YamlParser,Stream>`_
-`parse <yaml.html#parse,YamlParser,Stream>`_ proc implements the YAML processing
+proc implements the YAML processing step of the same name. All syntax errors in
-step of the same name. All syntax errors in the input character stream are
+the input character stream are processed by ``parse``, which will raise a
-processed by ``parse``, which will raise a ``YamlParserError`` if it encounters
+``YamlParserError`` if it encounters a syntax error.
-a syntax error.
 
 Transforming a ``YamlStream`` to a native YAML object is done via
 ``construct``. It skips the ``compose`` step for efficiency reasons. As Nim is
@@ -67,19 +68,21 @@ Dumping YAML
 ============
 
 Dumping is preferredly done with
-`dump <yaml.html#dump,K,Stream,PresentationStyle,TagStyle,AnchorStyle,int>`_,
+`dump <yaml.serialization.html#dump,K,Stream,TagStyle,AnchorStyle,PresentationOptions>`_,
-which serializes a native Nim variable to a character stream. Like ``load``, you
+which serializes a native Nim variable to a character stream. As with ``load``,
-can use the steps involved separately.
+the following paragraph describes how ``dump`` is implemented using the
+low-level API.
 
-You transform a variable into a ``YamlStream`` with
+A Nim value is transformed into a ``YamlStream`` with
-`represent <yaml.html#represent,T,TagStyle,AnchorStyle>`_. Depending on the
+`represent <yaml.serialization.html#represent,T,TagStyle,AnchorStyle>`_.
-``AnchorStyle`` you specify, this will transform ``ref`` variables with multiple
+Depending on the ``AnchorStyle`` you specify, this will transform ``ref``
-instances into anchored elements and aliases (for ``asTidy`` and ``asAlways``)
+variables with multiple instances into anchored elements and aliases (for
-or write the same element into all places it occurs (for ``asNone``). Be aware
+``asTidy`` and ``asAlways``) or write the same element into all places it
-that if you use ``asNone``, the value you serialize might not round-trip.
+occurs (for ``asNone``). Be aware that if you use ``asNone``, the value you
+serialize might not round-trip.
 
 Transforming a ``YamlStream`` into YAML character data is done with
-`present <yaml.html#present,YamlStream,Stream,TagLibrary,PresentationStyle,int>`_.
+`present <yaml.presenter.html#present,YamlStream,Stream,TagLibrary,PresentationOptions>`_.
 You can choose from multiple presentation styles. ``psJson`` is not able to
 process some features of ``YamlStream`` s, the other styles support all features
 and are guaranteed to round-trip to the same ``YamlStream`` if you parse the
@@ -90,11 +93,12 @@ The Document Object Model
 
 Much like XML, YAML also defines a *document object model*. If you cannot or do
 not want to load a YAML character stream to native Nim types, you can instead
-load it into a ``YamlDocument``. This ``YamlDocument`` can also be serialized
+load it into a `YamlDocument <yaml.dom.html#YamlDocument>`_. This
-into a YAML character stream. All tags will be preserved exactly as they are
+``YamlDocument`` can also be serialized into a YAML character stream. All tags
-when transforming from and to a ``YamlDocument``. The only important thing to
+will be preserved exactly as they are when transforming from and to a
-remember is that when a value has no tag, it will get the non-specific tag
+``YamlDocument``. The only important thing to remember is that when a value has
-``"!"`` for quoted scalars and ``"?"`` for all other nodes.
+no tag, it will get the non-specific tag ``"!"`` for quoted scalars and ``"?"``
+for all other nodes.
 
 While tags are preserved, anchors will be resolved during loading and re-added
 during serialization. It is allowed for a ``YamlNode`` to occur multiple times

doc/processing.svg

@@ -113,14 +113,14 @@
 
     <g id="serialize" transform="translate(235 10)">
       <use xlink:href="#atomic-right"/>
-      <a xlink:href="yaml.html#serialize,YamlDocument,TagLibrary,AnchorStyle" target="_top">
+      <a xlink:href="yaml.dom.html#serialize,YamlDocument,TagLibrary,AnchorStyle" target="_top">
         <text x="70" y="25" font-style="italic" font-weight="bold">serialize</text>
       </a>
     </g>
 
     <g id="present" transform="translate(385 10)">
       <use xlink:href="#atomic-right"/>
-      <a xlink:href="yaml.html#present,YamlStream,Stream,TagLibrary,PresentationStyle,int" target="_top">
+      <a xlink:href="yaml.presenter.html#present,YamlStream,Stream,TagLibrary,PresentationOptions" target="_top">
         <text x="70" y="25" font-style="italic" font-weight="bold">present</text>
       </a>
     </g>
@@ -132,14 +132,14 @@
 
     <g id="compose" transform="translate(235 120)">
       <use xlink:href="#atomic-left"/>
-      <a xlink:href="yaml.html#compose,YamlStream,TagLibrary" target="_top">
+      <a xlink:href="yaml.dom.html#compose,YamlStream,TagLibrary" target="_top">
         <text x="70" y="35" font-style="italic" font-weight="bold">compose</text>
       </a>
     </g>
 
     <g id="parse" transform="translate(385 120)">
       <use xlink:href="#atomic-left"/>
-      <a xlink:href="yaml.html#parse,YamlParser,Stream" target="_top">
+      <a xlink:href="yaml.parser.html#parse,YamlParser,Stream" target="_top">
         <text x="70" y="35" font-style="italic" font-weight="bold">parse</text>
       </a>
     </g>
@@ -148,13 +148,13 @@
   <g id="skipping-things" text-anchor="middle" transform="translate(0 90)">
     <g id="skipping-represent" transform="translate(55 10)">
       <use xlink:href="#skipping-right"/>
-      <a xlink:href="yaml.html#represent,T,TagStyle,AnchorStyle" target="_top">
+      <a xlink:href="yaml.serialization.html#represent,T,TagStyle,AnchorStyle" target="_top">
           <text x="175" y="25" font-weight="bold">represent</text>
       </a>
     </g>
     <g id="skipping-construct" transform="translate(55 160)">
       <use xlink:href="#skipping-left"/>
-      <a xlink:href="yaml.html#construct,YamlStream,T" target="_top">
+      <a xlink:href="yaml.serialization.html#construct,YamlStream,T" target="_top">
           <text x="175" y="75" font-weight="bold">construct</text>
       </a>
     </g>
@@ -163,25 +163,25 @@
   <g id="whole-lines" text-anchor="middle" transform="translate(0 20)">
     <g id="dump">
       <use xlink:href="#whole-right"/>
-      <a xlink:href="yaml.html#dump,K,Stream,PresentationStyle,TagStyle,AnchorStyle,int" target="_top">
+      <a xlink:href="yaml.serialization.html#dump,K,Stream,TagStyle,AnchorStyle,PresentationOptions" target="_top">
           <text x="325" y="25" font-style="italic" font-weight="bold">dump</text>
       </a>
     </g>
     <g id="dumpDOM">
       <use xlink:href="#dom-right"/>
-      <a xlink:href="yaml.html#dumpDOM,YamlDocument,Stream,PresentationStyle,AnchorStyle,int" target="_top">
+      <a xlink:href="yaml.dom.html#dumpDOM,YamlDocument,Stream,AnchorStyle,PresentationOptions" target="_top">
         <text x="380" y="65" font-weight="bold">dumpDOM</text>
       </a>
     </g>
     <g id="loadDOM" transform="translate(0 320)">
       <use xlink:href="#dom-left"/>
-      <a xlink:href="yaml.html#loadDOM,Stream" target="_top">
+      <a xlink:href="yaml.dom.html#loadDOM," target="_top">
         <text x="380" y="25" font-weight="bold">loadDOM</text>
       </a>
     </g>
     <g id="load" transform="translate(0 360)">
       <use xlink:href="#whole-left"/>
-      <a xlink:href="yaml.html#load,Stream,K" target="_top">
+      <a xlink:href="yaml.serialization.html#load,,K" target="_top">
           <text x="325" y="25" font-style="italic" font-weight="bold">load</text>
       </a>
     </g>

doc/serialization.txt

@@ -8,10 +8,11 @@ Introduction
 NimYAML tries hard to make transforming YAML characters streams to native Nim
 types and vice versa as easy as possible. In simple scenarios, you might not
 need anything else than the two procs
-`dump <yaml.html#dump,K,Stream,PresentationStyle,TagStyle,AnchorStyle,int>`_ and
+`dump <yaml.serialization.html#dump,K,Stream,TagStyle,AnchorStyle,PresentationOptions>`_
-`load <yaml.html#load,Stream,K>`_. On the other side, the process should be as
+and `load <yaml.serialization.html#load,,K>`_. On the other side, the process
-customizable as possible to allow the user to tightly control how the generated
+should be as customizable as possible to allow the user to tightly control how
-YAML character stream will look and how a YAML character stream is interpreted.
+the generated YAML character stream will look and how a YAML character stream is
+interpreted.
 
 An important thing to remember in NimYAML is that unlike in interpreted
 languages like Ruby, Nim cannot load a YAML character stream without knowing the
@@ -42,7 +43,8 @@ added in the future.
 
 This also means that NimYAML is generally able to work with object, tuple and
 enum types defined in the standard library or a third-party library without
-further configuration.
+further configuration, given that all fields of the object are accessible at the
+code point where NimYAML's facilities are invoked.
 
 Scalar Types
 ------------