Complete Getting Started Tutorials

[markus2330]

Create "Getting Started Tutorials" to be linked on main page:

• [ ] error handling (how to set/add errors/warnings)
• [ ] how to work with types in Elektra (+ guarantees if C99) + elektraKeyTo* by @Eiskasten
• [ ] merging, how to use KDB (get/state states, conflict handling, tools vs. importing) by @hannes99
• [x] how to work with spec+metadata (link to doc/METADATA.ini)
• [x] how to disable mmap @mpranj
• [X] how to report bugs (kdb stash/restore), shell recorder, ..
• [x] basic tutorial with kdb mount, qt-gui, import, export (done for LCDproc)
• [x] bindings
• [x] get started with language bindings: lua/java/c++
• [x] how to use "plugins"
• [X] mount tutorial (basic tutorial with kdb)
• [X] get started with namespaces and cascading lookup (starting with /)

Further ideas, see #1522

[markus2330]

And add:

• working with envvars (libelektra-getenv) @omnidan

[omnidan]

I would like to add envvars as a short example directly in the Usage section. (instead of the current example which isn't all that useful) Then we could link to a separate page which explains it further.

[markus2330]

@omnidan nice, maybe it can be used for release notes, too

[petermax2]

are you working on this?

@markus2330 yes I was going to!

[markus2330]

was going to OR am going to?

Manuel already has finished his MinGW task. I hope #273 gets resolved soon too. Every push request for improvement of docu received before #273 is resolved, can make it into the release.

[petermax2]

Alright, I hope I get it done by the end of the day.

[petermax2]

@markus2330 how would a tutorial about namespaces differ from doc/NAMESPACES.md?

[petermax2]

My pull request #285 has been merged.

[markus2330]

Yes, I forgot to mark this issue here.

[markus2330]

Still open is:

• get started with python/lua/java/c++
• get started with spec+metadata (link to doc/METADATA.ini)
• get started with envvars (libelektra-getenv) @omnidan
• get started with some plugins?

[omnidan]

get started with envvars is done in the main README.md with a link to more information

[markus2330]

Still open is:

• get started with python/lua/java/c++
• get started with spec+metadata (link to doc/METADATA.ini)
• get started with some plugins?

[markus2330]

Btw. a fancy name for spec+metadata tutorial would be "how to keep /etc empty"

basic idea: provided default values in the specification, installing config files to /etc is not necessary anymore.

[omnidan]

:+1:

[machinekoder]

@markus2330 I would like to use elektra in my project. However, I cannot find examples for the basics like mounting a INI file. I have no problem reading through the code for the Python bindings if necessary but I won't get there if I do not have a basic tutorial at least.

My suggestion: Add a basic tutorial with kdb (loading a ini file and manipulating some parameters).

[markus2330]

@strahlex Usage of specific plugins usually can be found in the README.md of the specific plugins. I added an example in https://github.com/ElektraInitiative/libelektra/tree/master/src/plugins/ini

But you are correct: a more general introduction into mounting would be helpful. One currently written is in https://github.com/ElektraInitiative/libelektra/pull/304/files see kdb-mount.

[markus2330]

Hi, I am thinking about something complete end-users (neither Elektra nor Application Developers) might find useful with Elektra 0.8.16 (which hopefully will be a part of Debian stretch release): The hosts plugin+validation seems to be one of the most robust end-users solutions. And it works with kdb, qt-gui, python interface and so on. So I would suggest to write a tutorial about that.

Not that config for the hosts plugin is different to other parts of the KDB hierarchy, but the keys within the hosts plugin would give a more pragmatic look on Elektra, it would give an immediate benefit even when edited with kdb editor because it provides validation. Simply try to write something which is not an IP in the tutorial to show its usefulness.

So something like:

sudo kdb mount --with-recommends hosts /hosts hosts
sudo kdb set system/hosts/ipv4/a3 128.130.173.28
sudo kdb set system/hosts/ipv4/a3 128.130.173.28a
-> Error (#51) occurred!
    Description: Value of key is not a valid IP Address
sudo kdb editor user/hosts hosts
sudo kdb qt-gui
python << HERE
import kdb
k = kdb.KDB()
ks = kdb.KeySet()
k.get(ks, "system/hosts")
print(ks.lookup("system/hosts/ipv4/a3").value)
HERE

with many explanations about each possibility.

@omnidan do you have some time for it?

[markus2330]

@fberlakovich It is critical for adoption of the augeas plugin that we have a tutorial covering step-by-step how to use the augeas plugin. Please also explain the combinations with journald and keytometa (and others) to show some advantages over directly using augeas.

[dominicjaeger]

Are those getting started tutorials different from all the tutorials in /doc? Are they the same?

[markus2330]

Yes, it is about completing the tutorials in doc/tutorials. The goal is that someone, who read all the tutorials, knows how to use Elektra.

[raphi011]

@markus2330 what should be in the Elektrad Tutorial that isn't already in the README.md of Elektrad and in the API Documentation on apiary.io?

[markus2330]

Yes, you are right, forget about that. src/tools/web/README.md is already quite nice. Better to have a longer go tutorial. I updated the top post.

[raphi011]

The go bindings also have a (small) tutorial already. Do you want me to

• extend / improve it there and / or link it to doc/tutorials or
• create a longer one directly in doc/tutorials?

I just want to prevent duplication

[markus2330]

It is up to you where to write it but my gut feeling says that on doc/tutorials it will be more visible.

It will also be important that you somehow add the information that go bindings are available: at the frontpage of the website and src/bindings/README.md

[ghost]

Not related to visible error messages. As discussed in the Elektra meeting I may unassign myself.

[markus2330]

@Eiskasten as discussed, please write tutorial/documentation about Elektra's type system.

@atmaxinger I assigned you to write tutorial/documentation for 3-way merging.

[eiskasten]

I am not entirely sure what the types tutorial should actually cover. Should developers be the target audience? If so wouldn't that tutorial similar if not even completely the same, as the High-Level API Readme? Otherwise, if it is supposed to land in the General Information section, I am not sure which roles C99+ and elektraKeyTo* would have.

[markus2330]

@Eiskasten it should be enough if you discuss all the types in the XFCE tutorial (together with its mapping).