Config File Examples

[markus2330]

The documentation of plugins received many improvements. Nevertheless, most storage plugins docus do not provide an example of how the configuration file looks like (or hide it somewhere in a HERE document). It would be nice to have examples for snippet conversions, tutorials and so on. Based on the examples we could also do some automatic test, e.g. import and check if keyset is not empty - or even regression tests.

I propose that we systematically add example(s) to every storage plugin. There are some competing ways how this can be done:

1. add infos/example in README.md
   • + Most simple way
   • + Can be shown (and referred to) via kdb info <plugin> example
   • + easy visible in github
   • - Supports only a single example
   • - Might confuse markdown parsers
2. add infos/example/#.. in README.md
   • + Can be shown (and referred to) via `kdb info example/#..
   • + easy visible in github
   • - Might confuse markdown parsers
3. stringify and include some other file(s) in infos/example
   • + Can contain anything without issues
   • ~ can be linked to in github
   • - Needs some extra handling in the build system (stringification of the file)
4. as 3. but with multiple files in infos/example/#..

Which way do you think is best?

[Namoshek]

Is it even possible that easily? I thought only the plugin description supports multi-line values (and most config snippets don't make sense / don't work with one line, e.g. ini).

[markus2330]

Is it even possible that easily?

One way to do it (which might also help to not confuse markdown parsers) would be:

- infos/status = unittest difficult unfinished old nodep
- infos/example =
```
# this is an fstab example
/dev/sr0        /media/cdrom   udf,iso9660 user,noauto     0       0
```
- infos/description=
... rest of document description in markdown ...

So the three ticks in a line would mark where the example starts/ends.
It obvously would prohibit these three ticks to occur in config files, but this should be a minor problem except if we have a markdown plugin some day.

[Namoshek]

I think we should allow multiple examples, so option 2 or 4. I also think that option 4 offers better readability; option 2 would change the layout of the README (also on GitHub) quite significantly.

[markus2330]

Thanks for the feedback! Which usecase do you have in mind for multiple examples? Would the snippet converter also profit from multiple examples?

[Namoshek]

Obviously the question is whether it is possible to put (always) everything into one example snippet or not. Most times this should be easily possible, but if you want to point out significant differences it could be difficult. For example it would be easy to explain with one snippet that the yajl plugin can handle both, objects and arrays (and even nested):

{
   "object": {
      "var1": "value1",
      "var2": {
         "inner_array": [ ]
      }
   },
   "array": [
      "val1",
      "val2",
      {"object_var":"val"}
   ]
}

But if you want to point out that the root hierarchy doesn't have to be an object, you couldn't do that within one snippet, because there are basically two cases for that (which could be, in this case, an important test case as well):

[
   "val1",
   "val2"
]

{
   "var1": "val1",
   "var2": "val2"
}

[sanssecours]

I like option 2 the best, assuming we use the fenced code block syntax as Markus suggested. If we use fenced code blocks, then we could also use syntax highlighting for some of the supported formats:

    - infos/placements = getstorage setstorage
    - infos/status = maintained coverage unittest
    - infos/examples/#1

        ```js
        [
           "val1",
           "val2"
        ]
        ```

    - infos/examples/#2

        ```js
        {
           "val1",
           "val2"
        }
        ```

    - infos/description = JSON using YAIL

• Might confuse markdown parsers

I do not think that is that big of a problem. The above example works

• on GitHub:

  • infos/placements = getstorage setstorage

  • infos/status = maintained coverage unittest

  • infos/examples/swig python: [] throws exception #1

    [
       "val1",
       "val2"
    ]

  • infos/examples/Error when compiling with clang #2

    {
       "val1",
       "val2"
    }

  • infos/description = JSON using YAIL

• in TextMate (using the GitHub Markdown bundle),
• in Pandoc and
• in Marked.

[markus2330]

Thank you for the detailed analysis! Are fenced code blocks already supported for most markdown parsers?

Small further details:

• we could also use names instead of arrays (infos/examples/_). (Btw. the array would start with #0.)
• so we should indent the snippets to make the enumeration work? (would make parsing of the file using cmake more complicated)

[sanssecours]

Are fenced code blocks already supported for most markdown parsers?

I do not know about most Markdown parsers, but some of the parsers certainly do (Source: StackExchange).

so we should indent the snippets to make the enumeration work?

Yes. Below is an example that shows the difference. As far as I know a code block will not be part of a list item unless we use indentation.

---

If we indent the fenced code blocks, then everything renders fine in the TextMate Preview (using Pandoc) and Marked (using DISCOUNT).

The preview in GitHub (most likely using Redcarpet) looks fine too:

1. infos/examples/#0 =

   [
       "val1",
       "val2"
   ]

2. infos/examples/swig python: [] throws exception #1 =

   {
       "val1",
       "val2"
   }

3. infos/description = JSON using YAIL

---

If we try to use a more compact syntax, then the example looks almost correct (the indentation in the code is incorrect) if we use Pandoc:

Marked only creates a list element for the first item of the numbered list:

The preview in GitHub creates a new list for every item:

1. infos/examples/#0 =

[
    "val1",
    "val2"
]

1. infos/examples/swig python: [] throws exception #1 =

{
    "val1",
    "val2"
}

1. infos/description = JSON using YAIL

[Namoshek]

But if we were using option 4 and would only add filename references, we could also use syntax highlighting in the example files (maybe an even better one)...?