Improved documentation.

 * also renamed canonicalDumper to explanatoryDumper
   because there's nothing canonical about it

CHANGELOG.md

@@ -1,3 +1,25 @@
+## 2.1.0 (upcoming)
+
+Changes:
+
+ * renamed ``canonicalDumper`` / ``setCanonicalStyle`` to
+   ``explanatoryDumper`` / ``setExplanatoryStyle`` because it was
+   a misnomer and there is nothing canonical about this output style.
+   The terminology *canonical* was carried over from PyYAML, but the
+   YAML specification uses that term for different things.
+ * The ``explanatoryDumper`` now automatically enables the
+   tag shorthand ``!n!``, because in this style you want that for readability.
+
+Bugfixes:
+
+ * Fixed a bug that prevented instances of generic types to be used in ``Option``
+   fields (e.g. ``Option[seq[string]]``) (#101)
+ * Fixed a problem that caused invalid indentation when dumping with certain
+   settings (#140)
+ * Fixed parsing errors for verbatim tags in flow style (#140)
+ * Fixed a problem that caused presentation of block scalars in
+   flow collections (#140)
+
 ## 2.0.0
 
 Breaking Changes:

doc/migrating.rst

@@ -11,7 +11,7 @@ Motivation
 NimYAML 2.0.0 is a release made for Nim 2.0.
 It drops support for earlier Nim versions and introduces features added in Nim 2.0, mainly default values for object fields.
 
-The second goal of NimYAML 2.0.0 was to make dumping YAML simpler and more useful.
+Another goal of NimYAML 2.0.0 was to make dumping YAML simpler and more useful.
 Previously, the default style for writing out YAML used exotic features like directives (e.g. ``%YAML 1.2``) and tags.
 This style has originally been chosen to closely follow the YAML specification's intentions of using YAML to share data between applications.
 However, the major usage for YAML today is configuration files.
@@ -50,25 +50,36 @@ Example code for old API:
 .. code-block:: nim
   var value = # some value
   var s = newFileStream("out.yaml", fmWrite)
-  dump(value, s, tagStyle = tsAll, options = defineOptions(
-    style = psCanonical, outputVersion = ov1_2)
+  
+  #simple dump
+  dump(value, s)
+  
+  # dump with options
+  dump(value, s, tagStyle = tsAll, options =
+    defineOptions(style = psBlockOnly, outputVersion = ov1_2))
 
 Same code for new API:
 
 .. code-block:: nim
   var value = # some value
   var s = newFileStream("out.yaml", fmWrite)
-  var dumper = canonicalDumper()
+  var dumper = Dumper()
+  
+  # simple dump
+  dumper.dump(value, s)
+  
+  # dump with options
+  dumper.setBlockOnlyStyle()
   dumper.presentation.outputVersion = ov1_2
   dumper.dump(value, s)
 
 The previous ``PresentationOptions`` now live in ``dumper.presentation``.
 There are also ``SeralizationOptions`` in ``dumper.serialization``.
-A preset sets values for both option objects.
+A preset (like ``setBlockOnlyStyle``) sets values for both option objects.
 You can modify the options afterwards to your liking.
 
 The new API makes use of Nim 2 default values for object fields.
-Hence ``defineOptions`` is gone, you can simply use the constructor of ``PresentationOptions``.
+Hence ``defineOptions`` is gone, you can instead use the constructor of ``PresentationOptions``.
 
 Changes to Default Output Style
 ===============================

doc/serialization.txt

@@ -8,8 +8,8 @@ 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.dumping.html#dump,Dumper,K,Stream>`_
-and `load <yaml.loading.html#load,,K>`_. On the other side, the process
+`dump <api/dumping.html#dump%2CDumper%2CK>`_
+and `load <api/loading.html#load%2C%2CK>`_. On the other side, the process
 should be as customizable as possible to allow the user to tightly control how
 the generated YAML character stream will look and how a YAML character stream is
 interpreted.

doc/snippets/quickstart/02/00-code.nim

@@ -8,8 +8,7 @@ personList.add(Person(name: "Karl Koch", age: 23))
 personList.add(Person(name: "Peter Pan", age: 12))
 
 var s = newFileStream("out.yaml", fmWrite)
-var dumper = canonicalDumper()
-dumper.serialization.handles = initNimYamlTagHandle()
+var dumper = explanatoryDumper()
 dumper.presentation.indentationStep = 3
 dumper.presentation.newlines = nlLF
 dumper.presentation.outputVersion = ov1_1

yaml/dumping.nim

@@ -13,12 +13,14 @@
 ## forms the highest-level API of NimYAML.
 
 import std/streams
-import parser, presenter, native, private/internal
+import parser, presenter, native, private/internal, taglib
 export native
 
 type
   Dumper* = object
     ## Holds configuration for dumping Nim values.
+    ## Default initialization yields the style that can be set via
+    ## ``setDefaultStyle``.
     presentation* : PresentationOptions
     serialization*: SerializationOptions 
 
@@ -41,9 +43,9 @@ proc setMinimalStyle*(dumper: var Dumper) =
 proc minimalDumper*(): Dumper =
   result.setMinimalStyle()
 
-proc setCanonicalStyle*(dumper: var Dumper) =
+proc setExplanatoryStyle*(dumper: var Dumper) =
   ## Output preset. Generates specific tags for all nodes, uses flow style,
-  ## quotes all string scalars.
+  ## quotes all string scalars. Enables the ``!n!`` tag shorthand.
   dumper.presentation = PresentationOptions(
     containers: cFlow,
     directivesEnd: deAlways,
@@ -54,11 +56,20 @@ proc setCanonicalStyle*(dumper: var Dumper) =
   )
   dumper.serialization = SerializationOptions(
     tagStyle: tsAll,
-    anchorStyle: asTidy
+    anchorStyle: asTidy,
+    handles: initNimYamlTagHandle()
   )
 
-proc canonicalDumper*(): Dumper =
-  result.setCanonicalStyle()
+proc setCanonicalStyle*(dumper: var Dumper)
+    {. deprecated: "renamed to setExplanatoryStyle" .} =
+  dumper.setExplanatoryStyle()
+
+proc explanatoryDumper*(): Dumper =
+  result.setExplanatoryStyle()
+
+proc canonicalDumper*(): Dumper
+    {. deprecated: "renamed to explanatoryDumper" .} =
+  result.setExplanatoryStyle()
 
 proc setDefaultStyle*(dumper: var Dumper) =
   ## Output preset. Uses block style by default, but flow style for collections