Chicken and egg with docs

[Ilya Zakharevich]

GIMP docs are most of the time out-of-sync.  Possible workaround:

Currently, a changelog entry looks like this:

=====
commit 16643800a1ff14378bbba981793c6d6085fda607
Author: Sven Neumann <sven@...>
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...

_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer

[Sven Neumann]

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


_______________________________________________
Gimp-developer mailing list
Gimp-developer@...
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer