RSS/Atom feed Twitter
Site is read-only, email is disabled
  1. Chat
  2. Useful links
  3. Polls

Featured content

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.

2 of 2 messages available
Toggle history

Please log in to manage your subscriptions.
Chicken and egg with docs Ilya Zakharevich 26 Oct 02:59
  Chicken and egg with docs Sven Neumann 27 Oct 21:50
Ilya Zakharevich
2009-10-26 02:59:44 UTC (about 15 years ago)

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...

Sven Neumann
2009-10-27 21:50:19 UTC (about 15 years ago)

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 +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.

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