Rate Tutorials

[markus2330]

Extending on #280 we should summarize the current state of the tutorials. For which tutorials do you think we need improvements, which need to be newly written?

• give a rating for current tutorials

[sanssecours]

Overview

Tutorial	Rating
Application Integration	+
Cascading	++
Compilation Variants	◦
Elektra Merge Integration	?
Export	++
Import	+
Merge	◦
Mounting	+
Namespaces	+
Plugins	+
Python	+
REST Service	+
Validation	◦

The rating above apply if we merge pull request #1259.

Application Integration

More concrete examples would be nice. Maybe we could add a step by step tutorial , that describes how to create a very simple application (e.g. “Hello Elektra”) that uses Elektra in Linux/macOS.

Compilation Variants

I am not really sure how helpful this tutorial is. I guess I will see if I ever need to define compilation variants. For now I think the tutorial seems rather short, for a description of a process that might be complicated. However, I think we can leave it as is, and add additional information later if someone discovers important data that might be missing currently.

Elektra Merge Integration

I did not know what “ufc” is before I read this tutorial. Reading the tutorial did not change this fact. It might make sense to add a link to the homepage of “ufc” or an article that describes this tool, if such a page exists.

Import

I think we should add some concrete examples a user can try by himself here.

Merge

I think we should add kdb commands to the tutorial that generate the keysets system/base, system/ours, system/base.

The description of the strategies makes sense, when we only look at key4. However I do not understand how the strategies determine some of the other keys in the merged keyset. For example, why do we lose key2 if we use the strategy ours?

Validation

Customized Schemas

The examples in the section “Customized Schemas” do not work on my computer. The command

kdb spec-mount /tutorial/schema

fails, displaying the following error message:

The command kdb spec-mount terminated unsuccessfully with the info:
No plugin that provides conflict/set/missing could be found

. I also quite dislike the use of here document syntax, since my favorite shell does not, and quite possibly will never, support this feature.

[markus2330]

Thanks for the great feedback!

The rating above apply if we merge pull request #1259.

Done! This was really a great PR!

[application step by step using] macOS

Great idea! But maybe in a different tutorial?

Compilation Variants

@petermax2 should know if the tutorial is useful, he wrote plugin(s) extensively using the feature.

Elektra Merge Integration

Astonishing that you could read it anyway. In 247027d I added a disclaimer that people need to know what ucf is and how Debian handles config files.

For example, why do we lose key2 if we use the strategy ours?

Might be related to #329?

The examples in the section “Customized Schemas” do not work on my computer.

Maybe fixed in debd2f8. Would be nice to have this tutorial executable in shell recorder, it is quite tiresome to reproduce something there.

I also quite dislike the use of here document syntax, since my favorite shell does not, and quite possibly will never, support this feature

Would have been good to know that earlier ;) We implemented HERE document support in the shell recorder only some time ago. Is there a good way to write import/export tutorials without any HERE document?

[sanssecours]

Maybe fixed in debd2f8.

The command kdb spec-mount /tutorial/schema now displays a different error message:

The command kdb spec-mount terminated unsuccessfully with the info:
No plugin that provides require could be found

.

Is there a good way to write import/export tutorials without any HERE document?

As pointed out by xfix here the command below works both in fish and bash:

echo "\
Dear, 
I'll 
stay 
gold" | cat

.

[markus2330]

now displays a different error message:

Ok, I fixed this too: e63198d But be warned, I think some lines later another command might fail. I am waiting for the shellrecorder to easier reproduce all the issues that are lurking in the tutorials, but if you are not tired of trying it, I will not get tired resolving these issues ;)

As pointed out by xfix here the command below works both in fish and bash

It also works with zsh and dash, but it has many limitations which characters are allowed to be present (or must be escaped). And sometimes what needs a quote is even shell and position-dependent. (e.g. in zsh it won't work if ! is before the final ")

[sanssecours]

Ok, I fixed this too: e63198d But be warned, I think some lines later another command might fail.

Looks like now the command

kdb import -s validate -c "format=% : %" /tutorial/schema simpleini << HERE
notation : graph
tool-support : ? none
applied-to : small
HERE

fails:

The command kdb import terminated unsuccessfully with the info:
Was not able to load such a plugin!

Maybe you misspelled it, there is no such plugin or the loader has problems.
You might want to try to set LD_LIBRARY_PATH, use kdb-full or kdb-static.
Errors/Warnings during loading were:
1 Warning was issued:
 Warning number: 1
	Description: could not load module, dlopen failed
	Ingroup: modules
	Module: dl
	At: Elektra/src/libs/loader/dl.c:88
	Reason: of module: libelektra-simpleini.so, because: dlopen(libelektra-simpleini.so, 130): image not found
	Mountpoint:
	Configfile:

. If I use ini instead of simpleini in the command above, then the example seems to work 🙌.

[markus2330]

Yes, simpleini does not exist on Mac OS X. #1055 also fell into the trap. #701 proposes to write an replacement. If no newcomer wants to do it, we can easily write it once we know which grammars are best suited based of your investigations.

[markus2330]

reminder: look at libgit2 docu