Building the GIMP documentation

Applications
, ,
1

Hello,

I’m trying to follow the instructions in GNOME / gimp-help · GitLab. I’m at a point where I can generate HTML files from the XML, but the images in figures are missing. Can anyone help solve this or narrow down the issue?

  • The src field is empty for figures in the HTML.
  • All of the image files are added to the html/en/images folder.
  • Icons like the navigation arrows, home, and hints are all displayed. As is the banner image on the index page.
  • There are no errors in the console.

I’m building on Windows in an MSYS2 environment.

I had to use local copies of the DocBook XSL and DTD files, because there’s an error when I use the URLs. Maybe it’s related to the --nonet flags? I didn’t look into it too closely.

Any help is appreciated. Thanks.

2

Building gimp-help on Windows has some issues. You say MSYS2 environment, but usually you use one of the other environments (UCRT64, CLANG64, …). I will assume you mean one of the latter.

The gettext and libxml2 dependencies of e.g. UCRT64 do not work well. However the versions in the base MSYS2 do work. This is most likely due to how path conversions are done.

In my script to build gimp-help I set the following env vars:

MSGCAT_DIR=/usr/bin/msgcat
MSGFMT_DIR=/usr/bin/msgfmt
MSGINIT_DIR=/usr/bin/msginit
MSGMERGE_DIR=/usr/bin/msgmerge
MSGUNIQ_DIR=/usr/bin/msguniq

# Using MSYS2 xsltproc instead of the MINGW64 version dramatically speeds up processing (in addition to or maybe because of not having path finding issues)
XSLTPROC_DIR=/usr/bin/xsltproc
XMLLINT_DIR=/usr/bin/xmllint

# Bug in msginit of MINGW64 package but the one in MSYS package does work
export MSGINIT=$MSGINIT_DIR
export MSGCAT=$MSGCAT_DIR
export MSGFMT=$MSGFMT_DIR
export MSGMERGE=$MSGMERGE_DIR
export MSGUNIQ=$MSGUNIQ_DIR

export XSLTPROC=$XSLTPROC_DIR
export XMLLINT=$XMLLINT_DIR

The missing images is related to xmllib2 IIRC.

If you have the relevant Docbook packages installed (docbook-xml and docbook-xsl for the MSYS2 profile you are using), you should normally not need local copies of the Docbook files. (Except for docbook-web files if you are also trying to build gimp-help website, which does not have an MSYS2 package.)

Note for a first build it is highly encouraged to just use make-en (instead of just make, due to the long time it takes to build for al languages).

3

Thanks! It seems to be working now.

I think it was just the docbook-xml and docbook-xsl packages. From the error, I thought it was supposed to dynamically load the files from the internet.

I still need to do some more testing on the setup process though. For reference, I installed the following packages:

pacman -S mingw-w64-ucrt-x86_64-gcc [was recommended on the MSYS2 site. I haven’t tested if it’s needed]
pacman -S autotools
pacman -S libxslt
pacman -S python
pacman -S libxml2-python
pacman -S docbook-xml
pacman -S docbook-xsl

You were right about the environment. By default the MSYS2 installer starts a UCRT64 environment, so on the first install I partly used that. I created a separate install and used msys2.exe exclusively. That one didn’t copy the image files, but I just switched to the Cygwin copy code in the makefile (~1465). I can use both installs to build the html help with images, but I’d be happier to get a smooth install process nailed down.

After that, what’s the best way to help out? Should I just pick an open issue? Do I need to comment or add a label if I pick an issue up?

4

In general it is said that the MSYS2 environment should only be used for developers working on MSYS2 itself. Except for needing to set some environment vars, I would use either UCRT64 or CLANG64.

As for installed packages: we don’t use gcc, so in this case I doubt that is needed. A reference for what we use is our .gitlab-ci.yml. Although that has extra packages needed for building the website.

From a quick glance, what’s missing from your list is gettext, librsvg2-2 for building the quickreference pdf’s, intltool and Innosetup if you also want to build the installer(s). For keeping the repository up-to-date you will also need git. polib is needed for validating, but I think on MSYS2 you need to install it via pip, there isn’t a separate package IIRC, so you would also need the pip package.

After that, what’s the best way to help out? Should I just pick an open issue? Do I need to comment or add a label if I pick an issue up?

We are all volunteers and we are happy in any way someone wants to help out. That means you can work on anything you would like to, even if it’s not on our issue tracker. So either pick a subject that you are familiar with, or that you are interested in.

For issues that are easy to fix in a short time, I wouldn’t bother commenting on them that you are working on it. Just make the changes and submit a merge request (MR). For more extensive work, you could add a comment and then I can assign the issue to you (I don’t think you can yourself).

I think this is mentioned in our readme, but for completeness: best is to fork our gimp-help repository from the website interface; then clone that to your computer. For every issue you are working on, create a new branch and only make changes relevant to that in that particular branch.

When done add a relevant commit message and push to your fork. Then go into the web interface and you should see a button that says create merge request.

Feel free to ask more information. I can also be reached at certain hours on GIMP’s IRC server.