Chicken and egg with docs
This discussion is connected to the gimp-developer-list.gnome.org mailing list which is provided by the GIMP developers and not related to gimpusers.com.
This is a read-only list on gimpusers.com so this discussion thread is read-only, too.
| Chicken and egg with docs | Ilya Zakharevich | 26 Oct 02:59 |
| Chicken and egg with docs | Sven Neumann | 27 Oct 21:50 |
Chicken and egg with docs
GIMP docs are most of the time out-of-sync. Possible workaround:
Currently, a changelog entry looks like this:
=====
commit 16643800a1ff14378bbba981793c6d6085fda607
Author: Sven Neumann
Date: Tue Aug 4 23:20:49 2009 +0200
Change the default for the 'trust-dirty-flag' gimprc option back to FALSE
It appears that there are good reasons why a user might want to save a clean image, for example because the file has been deleted or damaged. (cherry picked from commit 5c630f4ad8ef55d2249968102cb8f5cb8fadfe23) =====
Suppose
A) One puts section names like
sect1="gimp-concepts-file-save" sect1="gimp-file-save-dialogue"
in a separate paragraph inside the changelog entry. Whatever follows this paragraph is considered to be worthy to be seen by users.
B) A script scans changelog, and extracts user-visible changes to
files (e.g., to
Changes-auto/gimp-concepts-file-save-16643800a1ff14378bbba981793c6d6085fda607.txt,
Changes/auto/gimp-file-save-dialogue-16643800a1ff14378bbba981793c6d6085fda607.txt)
with appropriate dates.
C) Each documenation language has a Updated-up-to-this-date value stored, and the corresponding release number (e.g., 2.8.12).
D1) English docs: each sect1 which is mentioned in changelog after its "updated-up-to" date has the following link AUTOMATICALLY added at the end:
Changes after 2.8.12
D2) Non-English docs do likewise, but have 2 links added:
Changes after 2.8.12 (English) Changes after 2.8.12 (Google translated)
What do you think? Ilya
P.S. This may get clumsy if description of a commit is not easy to change later...
P.P.S. This does not address where to store the file which is Google translated (since it depends on the "updated-up-to" date, it is language-dependent...
If one can pass URL#section through google translation, then one could have an HTML file common for all languages...
Chicken and egg with docs
On Mon, 2009-10-26 at 01:59 +0000, Ilya Zakharevich wrote:
GIMP docs are most of the time out-of-sync. Possible workaround:
Currently, a changelog entry looks like this:
===== commit 16643800a1ff14378bbba981793c6d6085fda607 Author: Sven Neumann
Date: Tue Aug 4 23:20:49 2009 +0200Change the default for the 'trust-dirty-flag' gimprc option back to FALSE
It appears that there are good reasons why a user might want to save a clean image, for example because the file has been deleted or damaged. (cherry picked from commit 5c630f4ad8ef55d2249968102cb8f5cb8fadfe23) =====
Suppose
A) One puts section names like
sect1="gimp-concepts-file-save" sect1="gimp-file-save-dialogue"
in a separate paragraph inside the changelog entry. Whatever follows this paragraph is considered to be worthy to be seen by users.
Sorry, but that is not feasible. We can't look through the list of help IDs for each commit. What we usually do at some point is to collect a list of user-visible changes and puth them into the release notes. We do that to help users and documenters.
If you want to help, then forget about doing this automatically. Instead you could volunteer to track the git repository for user-visible changes that should be documented and prepare a list of these changes. If you'd do that on a regular basis, that would certainly help.
This is still the wrong mailing-list for discussing the documentation. If you want to reach the people who are actually writing the docs, then please move this to the gimp-docs list.
Sven
