kconf_update user documentation
Hi! I see that user documentation for kconf_update has been moved from README.kconf_update to https://techbase.kde.org/Development/Tools/Using_kconf_update.
Is there a reason for it being on TechBase and not alongside the code in the repository? There is already a tutorial on techbase: https://techbase.kde.org/Development/Tutorials/Updating_KConfig_Files, and I think having documentation in the repository and a tutorial on TechBase makes sense.
If it was in the repository, I could easily open MRs against it, provide autotested example code with doxygen snippets, and keep it synchronized to code changes. (And I personally prefer doxygen over wiki markup.)
I actually want to improve this documentation, and update it to the current version where needed (there is a template on top of the page requiring so). At this time I would also like to ask whether someone else is currently planning work on this. I see that Simone added a section about testing recently.
Planned changes
(Public, so community has a chance to complain)
- “How it works” section:
-
Better describe the mechanisms that prevent double updating - $Version group; currently only noted “Debugging update scripts” section at the end of the manual
- New config files have no $Version group, what prevents running updates on them although they come from a new application version?
-
Provide a helpful link to KDED -
Fix installation paths (e. g. $KDEDIR/share/apps/kconf_update/ is wrong.)
-
-
Add an explicit “How to use” section after “How it works” -
There I can mention KConfig::checkUpdate()
-
- List of entries
-
Move the complex documentation of Script= and ScriptArguments= to a dedicated section “External scripts” -
In this section I can provide an example script
-
-
Sort the list in the way I like (maybe by grouping in subsections)
-
-
Remove KMail link (there are no longer interesting .upd files, just a bash script with a sed call.) - “Debugging update scripts” section: feels a bit lost in this manual, I want to move information to more appropriate places, mainly the “External scripts” section.
Results
- Rewrote most of Tools/Using_kconf_update, including the TODO above
- Extracted tutorials to Tutorials/Updating_KConfig_Files