Open markus2330 opened 8 years ago
And add:
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.
@omnidan nice, maybe it can be used for release notes, too
are you working on this?
@markus2330 yes I was going to!
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.
Alright, I hope I get it done by the end of the day.
@markus2330 how would a tutorial about namespaces differ from doc/NAMESPACES.md
?
My pull request #285 has been merged.
Yes, I forgot to mark this issue here.
Still open is:
get started with envvars is done in the main README.md with a link to more information
Still open is:
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.
:+1:
@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).
@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.
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?
@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.
Are those getting started tutorials different from all the tutorials in /doc? Are they the same?
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.
@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?
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.
The go bindings also have a (small) tutorial already. Do you want me to
doc/tutorials
ordoc/tutorials
?I just want to prevent duplication
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
Not related to visible error messages. As discussed in the Elektra meeting I may unassign myself.
@Eiskasten as discussed, please write tutorial/documentation about Elektra's type system.
@atmaxinger I assigned you to write tutorial/documentation for 3-way merging.
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.
@Eiskasten it should be enough if you discuss all the types in the XFCE tutorial (together with its mapping).
Create "Getting Started Tutorials" to be linked on main page:
Further ideas, see #1522