Merge pull request ElektraInitiative#4616 from markus2330/markus/history

Markus/history

doc/contrib/README.md

@@ -0,0 +1,3 @@
+This folder contains information for contributors to Elektra.
+
+- [Documentation Guidelines](documentation.md)

doc/dev/README.md

@@ -7,6 +7,7 @@ It complements the man pages found [here](/doc/help).
 - [Classes](classes.md)
 - [Data structures](data-structures.md)
 - [Plugins Framework](plugins-framework.md)
+- [History](history.md)
 
 ## Concepts
 

doc/dev/history.md

@@ -0,0 +1,46 @@
+# History
+
+## Elektrify
+
+The development of Elektra started in 2004.
+Initially the initiative only aimed at the straightforward idea to unify a configuration access API and a configuration format.
+Elektra started by introducing an API with a few language bindings.
+
+The idea of introducing a configuration access API was not new:
+Most proprietary software systems already had similar APIs for a long time.
+Nevertheless, it was clear that there was no portable configuration library available to be used for typical FLOSS applications.
+For example, the configuration libraries X/Q/GSettings, KConfig, dconf, plist, and Windows Registry are tied to their respective platforms.
+
+The first idea to improve adoption of Elektra was that the Elektra Initiative itself patches applications to use Elektra.
+This was done, e.g., for the X Server.
+The maintainers of the X Server, however, had other plans and later improved their software to auto-detect hardware.
+This was admittedly the right choice for them:
+Elektra would not have been able to help them at that time.
+
+## Mounting
+
+One obvious limitation of Elektra was that no gradual migration is possible and previous configuration files would need to be rewritten.
+In a first step, we introduced backends, chosen by users at run-time.
+
+An implementation providing only a single backend for the whole system proved to be too limited:
+Individual applications cannot customize their backends for their own needs.
+We implemented a layer similar to a virtual file system, which enables applications and system administrators to mount configuration files.
+
+## Dependencies
+
+Furthermore, dependences in the core made Elektra unattractive.
+To solve this problem, we modularized Elektra so that users can select exactly the features they need.
+
+Such changes made part of the software more complicated.
+At first, we provided too little documentation for newcomers to grasp the abstraction mechanisms.
+Then we started to put efforts into rebuilding the community by overhauling documentation, introducing more regression tests, writing tutorials, and designing a new website.
+
+## Elektrify: Back Again
+
+In the beginning of Elektra, there was no vision how configuration management and Elektra would work together.
+After many years of research, we now have a [clear vision](/doc/VISION.md) how a world with Elektra would look like.
+
+To actually improve the adoption of Elektra, however, configuration management cannot help directly.
+Instead we need applications that depend on Elektra, so that Elektra gets packaged for all distributions.
+We now elektrify KDE, GNOME and XFCE to achieve this goal.
+Furthermore, we are now in the process of doing the last cleanups before version 1.0.

doc/help/elektra-faq.md

@@ -4,25 +4,26 @@
 
 [Please open an issue](https://git.libelektra.org/issues).
 You can simply remove all template text and it is enough if the issue only contains your question.
-If you want you can [label it as question](https://git.libelektra.org/issues/labels/question), but we
-can also categorize it for you.
+If you are unsure, [label it as question](https://git.libelektra.org/issues/labels/question).
 
-Please do not waste too much time to find something out yourself. Information where people get
-stuck is valuable to improve Elektra and its documentation. Even if you find out directly after
-you posted the question: the pointer can be helpful for other people having the same problem.
+Please do not waste too much time to find something out yourself.
+Information where people get stuck is valuable to improve Elektra and its documentation.
+Even if you find out directly after you posted the question:
+the pointer can be helpful for other people having the same problem.
 
 ## Isn't it Easier to Implement a new Parser Than to use Elektra?
 
-No, it is not. And even if it were, the story does not end with implementing
-a configuration file parser but, at least, you also need:
+No, it is not.
+And the story does not end with implementing a configuration file parser.
+You also need:
 
 - operating-system-specific code to locate configuration files
 - tools to change the configuration files
 - validation to make such changes user-friendly
 
 Every successful project has implemented many features Elektra has.
-But Elektra has the distinctive advantage that you can pick the features
-as you need them. Not used plugins do not cause any overhead or dependency.
+But Elektra has the distinctive advantage that you can pick the features as you need them.
+Not used plugins do not cause any overhead or dependency.
 If you need new plugins or bindings, there is a community which can help you.
 Furthermore, Elektra has a defined API and you can swap implementations as needed.
 
@@ -40,20 +41,29 @@ to see how useful it can be.
 
 Longer answer:
 
-Elektra abstracts [configuration settings](elektra-glossary.md), something
-desperately needed within configuration management. Instead of rewriting
-complete configuration files, which might create security problems,
-Elektra operates precisely on the configuration setting you want to
-change: leaving others as chosen by the application or distribution.
-Furthermore, Elektra also allows us to _specify_ configuration settings,
-which again brings benefits for configuration management tools.
+Elektra abstracts [configuration settings](elektra-glossary.md), something desperately needed within configuration management.
+Instead of rewriting complete configuration files, which might create security problems due to ignoring distributions configuration files;
+Elektra operates precisely on the configuration setting you want to change:
+leaving others as chosen by the application or distribution.
+Furthermore, Elektra also allows us to _specify_ configuration settings, which again brings benefits for configuration management tools.
 
 Elektra is a radical step needed towards better configuration management:
-Let us fix how applications access configuration settings, so that we
-can properly access them, for example, from configuration management tools.
+Let us fix how applications access configuration settings, so that we can properly access them, for example, from configuration management tools.
 
-As an intermediate step, we can [mount](elektra-mounting.md)
-existing configuration files and operate on them.
+See [our vision](/doc/VISION.md) for an example.
+
+## If Elektra Already Exists so Long, why isn't it more Widespread?
+
+There are two main reasons:
+
+1. Research:
+   First we needed to [explore the design space](/doc/dev/history.md).
+   At that time, Elektra provided little benefit, except for niche applications.
+   Then it was challenging to actually implement the [vision](/doc/VISION.md).
+2. Bootstrapping:
+   Developers would like to have everything smooth and shiny, like packages available as are part of their distributions.
+   But Elektra only gets packaged if there are already application using Elektra.
+   We solved this problem in [many intermediate steps](/doc/dev/history.md), e.g., allow [mounting](elektra-mounting.md) legacy configuration files.
 
 ## Do We Retain the Old Way of Configuring Things, i.e. Manually Editing an INI File in /etc?
 

doc/man/man7/elektra-faq.7

@@ -1,12 +1,12 @@
 .\" generated with Ronn-NG/v0.10.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1.pre1
-.TH "ELEKTRA\-FAQ" "" "March 2022" ""
+.TH "ELEKTRA\-FAQ" "" "October 2022" ""
 .SH "I Am Stuck\. Where Can I Get Help?"
-Please open an issue \fIhttps://git\.libelektra\.org/issues\fR\. You can simply remove all template text and it is enough if the issue only contains your question\. If you want you can label it as question \fIhttps://git\.libelektra\.org/issues/labels/question\fR, but we can also categorize it for you\.
+Please open an issue \fIhttps://git\.libelektra\.org/issues\fR\. You can simply remove all template text and it is enough if the issue only contains your question\. If you are unsure, label it as question \fIhttps://git\.libelektra\.org/issues/labels/question\fR\.
 .P
 Please do not waste too much time to find something out yourself\. Information where people get stuck is valuable to improve Elektra and its documentation\. Even if you find out directly after you posted the question: the pointer can be helpful for other people having the same problem\.
 .SH "Isn't it Easier to Implement a new Parser Than to use Elektra?"
-No, it is not\. And even if it were, the story does not end with implementing a configuration file parser but, at least, you also need:
+No, it is not\. And the story does not end with implementing a configuration file parser\. You also need:
 .IP "\(bu" 4
 operating\-system\-specific code to locate configuration files
 .IP "\(bu" 4
@@ -32,11 +32,18 @@ to see how useful it can be\.
 .P
 Longer answer:
 .P
-Elektra abstracts configuration settings \fIelektra\-glossary\.md\fR, something desperately needed within configuration management\. Instead of rewriting complete configuration files, which might create security problems, Elektra operates precisely on the configuration setting you want to change: leaving others as chosen by the application or distribution\. Furthermore, Elektra also allows us to \fIspecify\fR configuration settings, which again brings benefits for configuration management tools\.
+Elektra abstracts configuration settings \fIelektra\-glossary\.md\fR, something desperately needed within configuration management\. Instead of rewriting complete configuration files, which might create security problems due to ignoring distributions configuration files; Elektra operates precisely on the configuration setting you want to change: leaving others as chosen by the application or distribution\. Furthermore, Elektra also allows us to \fIspecify\fR configuration settings, which again brings benefits for configuration management tools\.
 .P
 Elektra is a radical step needed towards better configuration management: Let us fix how applications access configuration settings, so that we can properly access them, for example, from configuration management tools\.
 .P
-As an intermediate step, we can mount \fIelektra\-mounting\.md\fR existing configuration files and operate on them\.
+See our vision \fI/doc/VISION\.md\fR for an example\.
+.SH "If Elektra Already Exists so Long, why isn't it more Widespread?"
+There are two main reasons:
+.IP "1." 4
+Research: First we needed to explore the design space \fI/doc/dev/history\.md\fR\. At that time, Elektra provided little benefit, except for niche applications\. Then it was challenging to actually implement the vision \fI/doc/VISION\.md\fR\.
+.IP "2." 4
+Bootstrapping: Developers would like to have everything smooth and shiny, like packages available as are part of their distributions\. But Elektra only gets packaged if there are already application using Elektra\. We solved this problem in many intermediate steps \fI/doc/dev/history\.md\fR, e\.g\., allow mounting \fIelektra\-mounting\.md\fR legacy configuration files\.
+.IP "" 0
 .SH "Do We Retain the Old Way of Configuring Things, i\.e\. Manually Editing an INI File in /etc?"
 Absolutely, you can think of libelektra as a small library in C that reads a configuration file and returns a data structure if you do not use any of its advanced features\.
 .P

doc/news/_preparation_next_release.md

@@ -394,7 +394,7 @@ This section keeps you up-to-date with the multi-language support provided by El
 - <<TODO>>
 - <<TODO>>
 - <<TODO>>
-- <<TODO>>
+- Write about [history](/doc/dev/history.md) to make plans of Elektra's adoption more clear. _(Markus Raab)_
 - <<TODO>>
 - <<TODO>>
 - <<TODO>>