make README.md more attractive, add cmake cache to .gitignore

[omnidan]

installation/usage instructions should definitely be one of the first things the user sees, as for the goals and facts, I really want them on top too, but they're just too long, so I put them after the Getting started section, but added a link to the Goals section: Why should I use Elektra?

hopefully that makes it easier for people to find the information they need

[omnidan]

I would love to add a usage section that gives a short introduction to running kdb, although someone who is more familiar with elektra should probably write that. It could go like this:

### Usage ###

After successfully installing Elektra, you should now have the `kdb` command
available. To...

As for qt-gui and the web ui, their usage information should be in their respective folders and linked to from the main README.md. (IMO those two should even be separate repos on github)

It would also be nice to add a badge with the build status (and maybe other useful information)

[markus2330]

Actually with out-of-tree builds that should not be necessary.

[markus2330]

isn't the contact/start developing/contributing more important then e.g. how to install?

[markus2330]

Daniel Bugl wrote:

I would love to add a usage section that gives a short introduction to
running kdb, although someone who is more familiar with elektra should
probably write that.

I think its ideal if it is written by someone who is currently not familiar
with it. Then it will be easily understandable.

As for qt-gui and the web ui, their usage information should be in their
respective folders and linked to from the main README.md. (IMO those two
should even be separate repos on github)

Separate repos only make sense if there is a separate maintainer and releases.

[omnidan]

Actually with out-of-tree builds that should not be necessary.

I think the .gitignore additions are only useful if you accidentally run cmake in the main directory once. Not sure about the tools gitignore, though. - I can remove those additions if you want me to.

isn't the contact/start developing/contributing more important then e.g. how to install?

It depends. Contributing to libelektra - I don't think so. Developing with libelektra, sure, that's important. The quickstart section contains a link to the application integration tutorial. Contact could be moved too, but it's usually found at the end - a lot of github projects add a gitter badge at the beginning so people can get in touch with you if they run into any problems, maybe we could do something like that (add a small contact link, or even use gitter)

As for installation, I think it is important as that's the first step to get started with elektra, so it should be one of the first things new visitors see. (after an explanation on what elektra actually is)

I think its ideal if it is written by someone who is currently not familiar
with it. Then it will be easily understandable.

True. I'll try out kdb and the qt-gui soon (hopefully today) and add the Usage section.

Separate repos only make sense if there is a separate maintainer and releases.

My reasoning was that if you want to use elektra in your application, you go to libelektra, but if you want to configure an application, you use the qt-gui or kdb. That's why I would separate it, but I can also simply link to the respective READMEs in the Usage section.

[markus2330]

Hello,

Daniel Bugl wrote:

I think the .gitignore additions are only useful if you accidentally run
cmake in the main directory once. Not sure about the tools gitignore,
though. - I can remove those additions if you want me to.

It might be even annoying for the accidentally run, because git clean does not
clean it up anymore. So I think its better to not have the .gitignore.

isn't the contact/start developing/contributing more important then e.g.
how to install?
It depends. Contributing to libelektra - I don't think so. Developing
with libelektra, sure, that's important.

Ok.

The quickstart section contains
a link to the application integration tutorial.

Why not have a link to the others tutorials, too?
(Its ok to have the link to application integration additionally because it
might be considered more important than others)

Contact could be moved too,
but it's usually found at the end - a lot of github projects add a
gitter badge at the beginning so people can get in touch with
you if they run into any problems, maybe we could do something like that
(add a small contact link, or even use gitter)

I am ok when you want to add social networks (stackoverflow might be very
worthwhile), but I do not have the time to set everything up nor to watch
multiple sources. But it would be good to be more present.

As for installation, I think it is important as that's the first step to get
started with elektra, so it should be one of the first things new visitors
see. (after an explanation on what elektra actually is)

I doubt that information really helps for installation. It is more an
advertisment that Elektra is already available for most distributions (and
thats the reason its on the main page).

There is also doc/INSTALL.md, we could move the information of sources.list
lines for debian there.

True. I'll try out kdb and the qt-gui soon (hopefully today) and add the
Usage section.

A big thanks to you for fixing these issues!

Separate repos only make sense if there is a separate maintainer and
releases.
My reasoning was that if you want to use elektra in your application, you go
to libelektra, but if you want to configure an application, you use the
qt-gui or kdb. That's why I would separate it, but I can also simply
link to the respective READMEs in the Usage section.

That it is called "libelektra" is a practical decision: the name is easier to
find on the web and the domain was available. Most parts of the "libelektra"
repository are not a library!

[omnidan]

I'll do the following things then:

• revert my changes to the .gitignore files
• link to other tutorials too (which ones would be important?)
• add the short info about contacting us to the top, remove the separate contact section (or should we just keep it anyway?)
• try to come up with a better Quickstart/Installation section (I'll have a look at doc/INSTALL.md)
• move the current Installation section further down and call it Packages
• try out kdb and qt-gui and write a short introduction for these tools (Usage section)

[omnidan]

I updated the README.md.

I also tested the qt-gui, but unfortunately couldn't get it to run with kdb qt-gui (I built the qt-gui separately with QT Creator to get it to run) - maybe someone can make sure running kdb qt-gui works in the release? If we're putting the qt-gui in a separate package, please let me know so I can add the package name to the new Quickstart section.

I would like to add an example of setting envvars with elektra to the Quickstart section - please let me know how this works :)

Which other tutorials should be included and where (which sections)?

[markus2330]

Thanks, it is a lot nicer now!

kdb qt-gui needs Elektra to be installed. It won't work if you compile it locally.

To run the locally compiled version, you simply can run:

./qt-gui

Setting envvars is:

kdb set user/env/override/HTTP_PROXY "http://my.proxy:8080"

See docu in src/libgetenv/README.md

Further tutorials: I created an issue #280 because nobody will see the text here...

[omnidan]

I did try to compile and install it with make install. I created a separate issue for the qt-gui issue too: #279

As for the envvar example, I added it in my new pull request, which also improves formatting in other docs: #281