The current GIMP documentation is a pretty amazing work. It needs
updating for 2.10.
I was asked to try to contribute to updating the GIMP color management
documentation. I don't know docbook. I don't know XML.
I don't know the GIMP-manual way of writing patches, submitting commits,
etc. I only know how these things are done wrt to patches, commits, and
bug reports for GIMP code.
I do know the GIMP code base regarding color management pretty well. So
I decided to try updating one small file (desaturate.xml) for the GIMP
manual and see how it goes.
I strongly suggest that if there is any thought about getting more
people on board with this GIMP-manual documentation, that something be
done about making it a little easier for newcomers. I have spent what
amounts to 3 full working days on this one file already, essentially all
of which has been spent dealing with "non-content" stuff like XML,
docbook, compiling GIMP-help, validating, and etc.
In my emails I've been trying to provide feedback on "how this
experience has been for a potential new contributor". Hopefully this
feedback might be helpful in figuring out how to smooth the process for
the next person who tries to contribute to GIMP-manual.
Speaking for myself, I'd rather go to the dentist than work with
docbook/XML, and I knew this *before* trying to update the desaturate
help. Nonetheless I decided to work on the desaturate help because
"someone" needs to update the GIMP color management documentation. The
"desaturate" page was supposed to be my "learn how to do this" trial run
at updating the documentation.
In future I'll just push patches that I write. I promise you I won't
keep flooding this mailing list with questions.
On 03/27/2017 02:35 AM, Julien Hardelin wrote:
Unless there are objections (and/or advice), I'm going to try to make
and upload a patch.
Assuming that eventually I'll succeed in putting the modified
desaturate.xml file into a shape that is acceptable for gimp-help, at
that point I'll need to make a patch.
I don't understand clearly. Will you push your changes directly to the
git repository, or will you create a patch file that you will send to
someone who will push it?
There is an open bug report on the desaturate page of GIMP-manual:
https://bugzilla.gnome.org/show_bug.cgi?id=767763
When submitting patches that fix bugzilla bug reports for GIMP, the
procedure is to attach the patch to the bug report. AFAIK, no one ever
actually pushes such patches to git until given the go-ahead by Mitch,
the GIMP maintainer.
My (possibly completely wrong) assumption is that there is a GIMP-manual
maintainer who maintains similar control over what bug report patches
are actually pushed to GIMP-manual. But if the usual procedure is to
just push the changes, then that is something that needs to be made
explicit, it seems to me.
When pushing patches for GIMP that fix particular bug reports, the patch
references the bug report, as per this example:
https://bugzilla.gnome.org/show_bug.cgi?id=780065#c7
So reasoning by analogy I assumed the correct procedure for the
GIMP-manual desaturate bug 767763 was to upload the patch, wait for
approval, and push the patch with a comment that references bug 767763.
But having never interacted with GIMP-manual before, perhaps my
"reasoning by analogy" is completely wrong.
I've very new at this "pushing of commits" stuff as I've only had commit
rights for a short time.
This whole conversation would be a lot easier to handle on IRC instead
of relying on email.
Question 1:
There is a long list of "po/..." files that are modified by building
gimp-help after modifying/adding the above xml/png files.
Should these modified "po/..." files be added to the git commit?
Normally, working on xml file don't modify the po files. git status
shows only your new files in the untracked section and modified files
(xml and images) in the index section. What have you done? perhaps a
make status?
No, I have never done a "make status". I've never even heard of a "make
status".
I made changes to the xml file and then recompiled the manual to see the
resulting html file. Compiling the manual results in a lot of changed
"po" files.
For some reason typing "git clean -xdf" doesn't get rid of the changed
"po" files. Instead they need to be checked out at the command line.
Which is tedious.
My apologies for saying this, but the procedures and command lines I've
been given for compiling and modifying GIMP-help have been less than
clear and doled out over time.
First I was given this command, which doesn't work (as I've already
noted in a previous email):
./autogen.sh --without-gimp --ALL_LINGUAS="en xx", where xx refers to a
language code, and so presumably ./autogen.sh --without-gimp
--ALL_LINGUAS="en" should also work, but to be on the safe side I also
tried ./autogen.sh --without-gimp --ALL_LINGUAS="en es".
Unfortunately at least on my computer ./autogen.sh --without-gimp
--All_LINGUAS="en" won't compile, ends in an error message. As I've
already explained this to you all, but no one responded.
Also unfortunately at least on my computer, the ./autogen.sh command
won't take a prefix unless that prefix in fact has GIMP already
installed in the prefix.
Otherwise no matter what prefix I give to autogen.sh, it tries to
install in /usr/share/gimp/2.0/help, and as I try to avoid install
development software as root, this fails (not to mention I don't want
GIMP-manual writing to /usr). I already tried to tell this to you all in
a previous email, but no one responded.
It was suggested to use kate for validating my xml code, but this
apparently requires a version of kate that I can't install on my version
of Gentoo unless I put an old version of kate (which version?) in a prefix.
I asked previously on this list (a couple of years ago) about what
editor to use for XML, and didn't receive any helpful advice. So far I
haven't really turned up any good information from the internet.
I use geany for writing c code and bluefish for writing html/php code.
Geany doesn't do autocomplete for XML (I don't use autocomplete when
writing c code). bluefish does autocomplete for XML, but in the wrong
place at the wrong time.
Geany doesn't even indicate the matching open/close tags, at least
bluefish does do this.
Is there a good GTK XML editor? Putting in line breaks at the "80"
column by hand is tedious.
I asked on this list about putting line breaks between images, but no
one responded. Do you have any idea how much time and searching through
the internet it took me to find an answer that would validate?
I asked a couple of other XML/docbook questions, and didn't get any
answers. I did find answers by searching the internet, but it was very
slow going.
I asked about how to validate the XML, and pointed out that the terminal
output from "make validate-en" wasn't exactly easy to interpret, but no
one responded to my inquiries. So I'm using the W3 validator instead.
A very kind soul finally offered these very much appreciated terminal
commands:
make html-en
make validate-NN
make status-NN
make html-NN
where NN is the language code like en, it, de, etc.
Prior to these terminal commands, it was taking an incredibly long time
to recompile gimp-manual every time I made a change to the xml file, to
the point where I was just about ready to say "forget about it, this
takes far too long".
You have to "checkout" all this po files
Question 2:
These image files are no longer used in the desaturate help, so
perhaps these files should be rm'ed from git before I make a patch?
images/C/toolbox/colors-desaturate-brightness.png
images/C/toolbox/colors-desaturate-luminosity.png
images/C/toolbox/colors-desaturate-average.png
images/C/toolbox/colors-desaturate-orig.png
You delete these images. They will appear as "deleted" in the index
section of git status
Thank you.
Question 3:
Is there anything different about the process of making a patch for
gimp-help, compared to making a patch for gimp code? Anything to watch
out for, or special commands, or anything along these lines?
To answer to this question, I need to know what you mean with "patch".
See above. I mean a patch to attach to
https://bugzilla.gnome.org/show_bug.cgi?id=767763
Best,
Elle
_______________________________________________
gimp-docs-list mailing list
gimp-docs-list@xxxxxxxxx
https://mail.gnome.org/mailman/listinfo/gimp-docs-list
