Sign up now! · Forgot password?
RSS/Atom feed Twitter

building documentation?

This discussion is connected to the gimp-docs-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.

10 of 10 messages available
Toggle history

Please log in to manage your subscriptions.

building documentation? Michael Grosberg 23 Mar 19:10
  building documentation? Owen 23 Mar 20:27
   building documentation? Michael Grosberg 24 Mar 07:10
    building documentation? Owen 24 Mar 09:26
     building documentation? Michael Grosberg 24 Mar 11:54
      building documentation? Owen 24 Mar 20:33
       building documentation? Michael Grosberg 26 Mar 11:25
       building documentation? Ulf-D. Ehlert 26 Mar 19:11
        building documentation? Michael Grosberg 27 Mar 19:32
    building documentation? Ulf-D. Ehlert 24 Mar 10:57
Michael Grosberg
2011-03-23 19:10:09 UTC (about 9 years ago)

building documentation?

IT's taken some time (I had a rather optimistic estimate of tmy free time) but I'm finally making some headway with rewriting parts of the documentation. My current aim is to rewrite Gimplite Quickies. Problem is, I still don't know how to build the html. I was told here on the mailing list that Ubuntu has all the needed tools but I wasn't told what they are... Validating is not a problem, I have XML validation tools, but editing XML blindly can only go so far: I really need to see what I'm doing.

Can anyone help me with this?

BTW, I'm targeting 2.8, i.e., changing references from "save as" to "Export", etc.

Owen
2011-03-23 20:27:42 UTC (about 9 years ago)

building documentation?

IT's taken some time (I had a rather optimistic estimate of tmy free time)
but I'm finally making some headway with rewriting parts of the documentation. My current aim is to rewrite Gimplite Quickies. Problem is, I
still don't know how to build the html. I was told here on the mailing list
that Ubuntu has all the needed tools but I wasn't told what they are...
Validating is not a problem, I have XML validation tools, but editing XML
blindly can only go so far: I really need to see what I'm doing.

Can anyone help me with this?

BTW, I'm targeting 2.8, i.e., changing references from "save as" to "Export", etc.

This wiki entry may help you

http://gimp-wiki.who.ee/index.php/Hacking:Building/Linux#Building_the_Documentation

Owen

Michael Grosberg
2011-03-24 07:10:13 UTC (about 9 years ago)

building documentation?

2011/3/23 Owen

This wiki entry may help you

http://gimp-wiki.who.ee/index.php/Hacking:Building/Linux#Building_the_Documentation

Owen

OK, wiki says to type this:

./autogen.sh --without-gimp ALL_LINGUAS="en"

Then look for errors on missing dependencies, install them, repeat until autogen finishes successfully.

First of all I updated my local copy of GIT. I installed the following packages:
gettext
docbook
automake
docbook2odf
pngcrush
pngnq

And got autogen to announce I can now use make. I can either build html or PDF.
I managed to build a PDF, so that's good news, but when I try to build the HTML I get this:

michael@michael-desktop:~/gimp-help-2$ LINGUAS=en make Making all in quickreference
make[1]: Entering directory `/home/michael/gimp-help-2/quickreference' make[1]: Nothing to be done for `all'. make[1]: Leaving directory `/home/michael/gimp-help-2/quickreference' make[1]: Entering directory `/home/michael/gimp-help-2' Cleaning up 'en' xml files ...
*** Making html for en ...
I/O error : Attempt to load network entity http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl warning: failed to load external entity " http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl" compilation error: file stylesheets/plainhtml.xsl line 10 element import xsl:import : unable to load
http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl make[1]: *** [html/en/index.html] Error 5 make[1]: Leaving directory `/home/michael/gimp-help-2' make: *** [all-recursive] Error 1

Any ideas? (I can reach the XSL using Firefox)

I can work with the PDF but I'd be happier if I could see the HTML result.

Owen
2011-03-24 09:26:37 UTC (about 9 years ago)

building documentation?

2011/3/23 Owen

This wiki entry may help you

http://gimp-wiki.who.ee/index.php/Hacking:Building/Linux#Building_the_Documentation

Owen

OK, wiki says to type this:

./autogen.sh --without-gimp ALL_LINGUAS="en"

Then look for errors on missing dependencies, install them, repeat until
autogen finishes successfully.

First of all I updated my local copy of GIT. I installed the following packages:
gettext
docbook
automake
docbook2odf
pngcrush
pngnq

And got autogen to announce I can now use make. I can either build html or PDF.
I managed to build a PDF, so that's good news, but when I try to build the
HTML I get this:

michael@michael-desktop:~/gimp-help-2$ LINGUAS=en make Making all in quickreference
make[1]: Entering directory `/home/michael/gimp-help-2/quickreference' make[1]: Nothing to be done for `all'. make[1]: Leaving directory `/home/michael/gimp-help-2/quickreference' make[1]: Entering directory `/home/michael/gimp-help-2' Cleaning up 'en' xml files ...
*** Making html for en ...
I/O error : Attempt to load network entity http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl warning: failed to load external entity " http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl" compilation error: file stylesheets/plainhtml.xsl line 10 element import
xsl:import : unable to load
http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl make[1]: *** [html/en/index.html] Error 5 make[1]: Leaving directory `/home/michael/gimp-help-2' make: *** [all-recursive] Error 1

Any ideas? (I can reach the XSL using Firefox)

I can work with the PDF but I'd be happier if I could see the HTML result.

Could I suggest that you run autogen.sh again, and read the last 20 or so lines.

Just see what programs weren't found and install them.

Now if you have the style sheets on your computer, it shouldn't have to go to the net to get them. Install all the stylesheets you can find (I think you were using Ubuntu so just search synaptic for stylesheets )

I remember having problems getting this external link to work, maybe 5 or 6 years ago, and since then have used local copies

HTH

Owen

Ulf-D. Ehlert
2011-03-24 10:57:22 UTC (about 9 years ago)

building documentation?

Michael Grosberg (Thursday, 24. March 2011) [...]

*** Making html for en ...
I/O error : Attempt to load network entity http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl warning: failed to load external entity "

You have to install the DocBook stylesheets (package name probably "docbook-xsl" or "docbook-xsl-stylesheets"; source: http://sourceforge.net/projects/docbook/). Then you'll have a local copy of ".../xhtml/chunk.xsl" and xsltproc should use this version.

Bye, Ulf

Keiner schreibt, daß er nichts zu sagen hat;
doch die meisten, die schreiben, sagen nichts als das.
		-- Karlheinz Deschner
Michael Grosberg
2011-03-24 11:54:08 UTC (about 9 years ago)

building documentation?

2011/3/24 Owen

Could I suggest that you run autogen.sh again, and read the last 20 or so lines.

Just see what programs weren't found and install them.

Now if you have the style sheets on your computer, it shouldn't have to go to the net to get them. Install all the stylesheets you can find (I think you were using Ubuntu so just search synaptic for stylesheets )

Owen

Thanks! It's working now. And with a launcher to a small script that generates a draft of a single file, I can preview with the click of a button, like God intended :)

I see you've already changed the wiki, so add the following: docbook-xsl (this is the one with the stylesheets) docbook-utils (solved a number of dependencies)

There might be more packages necessary; I added a bunch of other packages, don't remember which, I just ticked anything that seemed like it was related to docbook.
Also, I still get one line of missing dependencies: checking for dot... no
I couldn't find something called "dot" in synaptic and it seems to be working without it anyway.

Now, some more questions: 1. There are two folders, both with XML files: XML and SRC. I understand XML is the one files are built from, and SRC is the one GIT uses to fetch files. But how do the two interact? do I copy files manually or is there some tool or script to update one or the other? In other words what is the work process here?

2. UI screenshots: Do you have a preference for the theme used in the screenshots? The wiki says screenshots should use the "default theme" but is it the Gnome's or Ubuntu's default theme I should be using? Gnome's default is Clearlooks, right?

3. I intend to replace the astronomy images used in the quickies with images more representative of something a normal user would use, everyday objects such as cars, animals, plants, tourist attractions and if I find the right subjects, people. These are good looking images I took myself, but I want to know if I need to do anything rights-wise, you know, do I need to explicitly release them under the GPL or CC or what have you, and if I do, how do I do it.

4. it's a long shot, but does anyone here use Notepad++ and has the correct HTMLtidy settings file to correctly reflow and indent docbook XML?

Owen
2011-03-24 20:33:14 UTC (about 9 years ago)

building documentation?

On Thu, 24 Mar 2011 13:54:08 +0200 Michael Grosberg wrote:

I am totally out of my depth here, but here are some ramblings

Now, some more questions:
1. There are two folders, both with XML files: XML and SRC. I understand XML is the one files are built from, and SRC is the one GIT uses to fetch files. But how do the two interact? do I copy files manually or is there some tool or script to update one or the other? In other words what is the work process here?

I am pretty sure this is all controlled by the Makefile. have a sqizz if you are happy reading that stuff

2. UI screenshots: Do you have a preference for the theme used in the screenshots? The wiki says screenshots should use the "default theme" but is it the Gnome's or Ubuntu's default theme I should be using? Gnome's default is Clearlooks, right?

I am pretty sure what is meant here is that the "Default" is that set out in the preferences under themes, .../share/gimp/2.0/themes/Default

3. I intend to replace the astronomy images used in the quickies with images more representative of something a normal user would use, everyday objects such as cars, animals, plants, tourist attractions and if I find the right subjects, people. These are good looking images I took myself, but I want to know if I need to do anything rights-wise, you know, do I need to explicitly release them under the GPL or CC or what have you, and if I do, how do I do it.

Too hard, Ulf or Roman may help here.

4. it's a long shot, but does anyone here use Notepad++ and has the correct HTMLtidy settings file to correctly reflow and indent docbook XML?

Don't know Notepad++, but there is a linux program "tidy" which does a fairly good job once you psyche it out.

Owen

Michael Grosberg
2011-03-26 11:25:02 UTC (about 9 years ago)

building documentation?

2011/3/24 Owen

On Thu, 24 Mar 2011 13:54:08 +0200 Michael Grosberg wrote:

4. it's a long shot, but does anyone here use Notepad++ and has the correct HTMLtidy settings file to correctly reflow and indent docbook XML?

Don't know Notepad++, but there is a linux program "tidy" which does a fairly good job once you psyche it out.

This is the library that NPP uses to clean up code anyway. And it produces well-formatted, line-wrapped XML. The only difference is in the tag:

the existing XML files indent the tag this way:

content more content

While tidy produces output like this:

content more content

Other tags are identical. would that be a problem?

Ulf-D. Ehlert
2011-03-26 19:11:27 UTC (about 9 years ago)

building documentation?

Owen (Thursday, 24. March 2011)

On Thu, 24 Mar 2011 13:54:08 +0200 Michael Grosberg wrote:

[...]

1. There are two folders, both with XML files: XML and SRC. I understand XML is the one files are built from, and SRC is the one GIT uses to fetch files. But how do the two interact? do I copy files manually or is there some tool or script to update one or the other? In other words what is the work process here?

I am pretty sure this is all controlled by the Makefile. have a sqizz if you are happy reading that stuff

Yes, English is a special case (no po/pot files), the files are just copied when you type e.g.
'make html-en'
or
'make xml-en'.

2. UI screenshots: Do you have a preference for the theme used in the screenshots? The wiki says screenshots should use the "default theme" but is it the Gnome's or Ubuntu's default theme I should be using? Gnome's default is Clearlooks, right?

I am pretty sure what is meant here is that the "Default" is that set out in the preferences under themes, .../share/gimp/2.0/themes/Default

I think you are right. But IMO it's much more important which OS and (under Linux) which desktop manager is used. IMHO we should use distribution-independent (default) themes - e.g. Gnome's default theme rather than Ubuntu's.

3. I intend to replace the astronomy images used in the quickies with images more representative of something a normal user would use, everyday objects such as cars, animals, plants, tourist attractions and if I find the right subjects, people. These are good looking images I took myself, but I want to know if I need to do anything rights-wise, you know, do I need to explicitly release them under the GPL or CC or what have you, and if I do, how do I do it.

Too hard, Ulf or Roman may help here.

I wonder if we won't get a copyright problem if the images are replaced... And even if not, shouldn't we show respect for the original author?

Ulf

Daß Götter stets nur in Menschengestalt kommen,
hat noch keinen Gläubigen nachdenklich gemacht.
		-- Karlheinz Deschner
Michael Grosberg
2011-03-27 19:32:42 UTC (about 9 years ago)

building documentation?

2011/3/26 Ulf-D. Ehlert

I wonder if we won't get a copyright problem if the images are replaced... And even if not, shouldn't we show respect for the original author?

Obviously not - the entire thing is under the GNU Free documentation License. The original images were taken from Astronomy picture of the Day, and checking the "About" page, I see they were not released under any kind of free license; some of them may be copyrighted. If anything, replacing the images will make the doc more free. As for my own pictures, I figure if I add them to the documentation they fall under the GNU FDL. Anther reason for taking the time to replace all of them was that I wanted all the screenshots to have a similar theme (clearlooks, which I believe is the Gnome 2.x default) and I had to replace at least some because the interface has changed.

As for respect, I have all respect to Carol Spears who invested her time and effort to write the original tutorials, and I kept the credit in the introduction. But while it is natural for tutorials on personal website to maintain a casual tone and have tangential interests such as astronomy feature in the tutorials, I believe official documentation should be more professional. These are, after all, quick tutorials for those who don't want to read the entire manual to get some small task done; I tried to make it as short and to the point as possible.