On Jan 5, 2004, at 12:49 am, Roman Joost wrote:

3. I made the corresponding changes to the toolbox XML files and the stylesheets and added three new options:

a) The processor includes the titles up to section3. b) The processor chunks the documents up to section3 (Before, all the tools are displayed on one HTML page)

Do we really need section3s? Considering that it should be also possible to have the whole documentation in one "book" this is really too deep as we have .... Additionally if you
look at the ToC as a tree you will that the weights are not naturally spread because the depth varies a lot. Has anyone ever seen a distribution
like that? :)

As a rule of a thumb I normally tell that everything below sect2 needs a reconsideration of the structure.

5. I added some todos on my last mail (18. Dec). The todos are about not
yet written content and to add documents for the existing help ids. Daniel pointed to a very cool book (thanks for that) with some XInclude tricks. We've to create at least the docs for the help-ids, as far as i know now. The only idea i have is: we can create a "big" document with all the plugin names and information, which is of course
not yet written and include each section into the document.

The nice thing about xinclude is that one can rename ids on the go so one "not-yet-written" section can be included several times without having to be physically present several times.

6. The problem of the broken links, which are linking to glossary entries. I read a bit further in the book and found out, that can only link to ids in the current document. The author points to "olinks" and creating an external database file for crossreferences between documents. I'll try this out, but it looks really scary ...

Olinks really are scary. They only make sense if you have a good way to automatically index all referenced documents which can be a lot of nasty work depending on where they reside.

What exactly is the problem with linking to glossary entries?

-- Servus,
Daniel

Le lun 05/01/2004 à 00:49, Roman Joost a écrit :

2. I customised the purposed StructureOfTheDocumentation[1] a bit. It should now be implementable by the doc writers. The main thing is, that the depth is on section 3 at maximum (see the table on the "top" of the proposal). I wouldn't go any deeper for readability reasons. The changes are documented on the WIKI, so have a look at it. There is additionally an example of a document. Feel free to add your ideas to this example document.

I made some changes :

# Using GIMP :: 3. Image Window :: 2. Menus Julien and me we think that here it should be only an introduction about 'how to use the image window' and not a full list documented about all the stuff in the image window menu, this because the Title chapter is Using Gimp.
The place where I see the details for image window menu is # Dialogs (could be then renamed Dialogs & menus) :: Menus :: Image window.

# Dialogs :: 3. Gradients was an error it's 2. The Dialogs :: 14. Gradients

# Dialogs :: Preferences , forgotten ?? I add this dialog

and some comments :

# Toolbox :: 2. Tools :: 4. Color Tools, tools but not in the Toolbox.

# Dialogs :: 1. Tool Options what do you write here ? it's already described for each tool in the toolbox.

@+ Raymond

Le lun 05/01/2004 à 00:49, Roman Joost a écrit :

1. The problem, that the whole content is mixed up after the generation is now fixed. The problem was, that only the dtd in gimp.xml was wrong. It seems, that this was my fault and i'm sorry for that. I had a bit of time to add some german content and make some corrections, during the little meeting with Sven and Simon in Berlin. Unfortunately, i couldn't motivate Sven to finish the "install" target ...

What is the statut now ? Since christmas I only have a few html files with only "xinclude" in it. It's always possible to work with the old framework but I'd prefer work with the new one with the "TO BE WRITTEN" texts.

I don't find in the CVS the doc I written myself : rewritten Path tool, Dialog layer ? Do I have to resent them to you or not ?

@+ Raymond

Le lun 05/01/2004 à 00:49, Roman Joost a écrit :

a) Screenshots should be made with the standard GNOME theme and a generic font (like Bitstream Sans).

Standard GNOME theme is ? I don't remember but on my Mandrake the standard is Galaxy ??

b) If we make some compositing images, we should provide the source file. The others should be able to make the same image with translated text from it. Julien and Raymond made some cool diagrams in SVG. Unfortunately i can not translate them, without discarding the font data.

Well I made the SVG with sodipodi 0.33 with the fonts installed on my Mandrake 9.2. My first goal was to release this in XCF with text layers but the SVG import don't transform the Sodipodi text in Layers (may be I miss something). So finally I released a SVG that you can edit with Sodipodi (the fonts used are AD MONO, binary). I you think we should use only a few fonts (what you call generic fonts) please give us a list of the font that we can use (we need at least 3 fonts) and write this somewhere on the Wiki.

@+ Raymond

Hi all,

Roman Joost wrote:

On Fri, Jan 09, 2004 at 10:06:50PM +0100, raymond ostertag wrote:

What is the statut now ? Since christmas I only have a few html files with only "xinclude" in it.

A new cvs update should bring you all the changes. I hope, that the anonymous gnome cvs servers are now in sync with the other ones ...

Just a quick note on CVS best practices.

For fairly obvious reasons (disk crashes, accidental rms, etc) it is desirable to have as small a difference as possible between your local CVS copy and the repository. You should never really have any more than 1 or 2 outstanding things to commit locally.

In general, if you have something you don't want to put into CVS (or can't), create a patch file, attach it to a bug report, and then revert the change locally bringing you back to the base state. Once the patch is stored centrally, you can always get it back later.

If you're doing something which would get in the way of other people, then your choices are to develop it on a branch (doing regular merges from the head), or to set up a local repository for your development, again merging regularly from the main CVS. That way, you have your own stuff versioned too (preferably backed up off-disk).

I hope these kinds of comments aren't out of place. I have noticed that commits to gimp-help-2 are fairly infrequent, and tend to affect lots of files. It is better all round if there are more frequent commits, each one making a distinct change. This also gives people an interest to do frequent cvs updates (which is essential if you want to get patches that apply without conflicts from people).

Cheers, Dave.

On Jan 10, 2004, at 1:45 pm, David Neary wrote:

I hope these kinds of comments aren't out of place. I have noticed that commits to gimp-help-2 are fairly infrequent, and tend to affect lots of files. It is better all round if there are more frequent commits, each one making a distinct change. This also gives people an interest to do frequent cvs updates (which is essential if you want to get patches that apply without conflicts from people).

Actually it happens quite frequently with documentation that one figures out how to do something in better ways or that markup was abused and then spread over several files. Those kind of changes are best done all at once because it prevents files from diverging and to ensure consistency throughout the project.

IMHO your given rule of a thumb is not completely correct because the granule of a commit should not be the smallest possible change in a single file but the smallest possible changeset covering all files needed to be touched for a logical step. I however totally agree with you that only one logical step should be taken at one time at committed separately from other changes. Unfortunately with CVS that requires a lot of discipline because it doesn't support the notion of a changeset and creating and working with a branch is really overkill in most cases.

--
Servus,
Daniel

Daniel Egger wrote:

It is better all round if there are more frequent commits, each one making a distinct change.

IMHO your given rule of a thumb is not completely correct because the granule of a commit should not be the smallest possible change in a single file but the smallest possible changeset covering all files needed to be touched for a logical step.

This is what I meant above, although I can see how it might have been read differently. what I meant by "a distinct change" is precisely a changeset - something that has one paragraph in the ChangeLog, if you like.

Unfortunately with CVS that
requires a lot of discipline because it doesn't support the notion of a changeset and creating and working with a branch is really overkill in most cases.

It kind of does - it's not changeset oriented in the way that BK or Arch are, but checking in several files at once is possible, and cvs2svn manages to make changesets out of commits that happen with the same comment, at the same time, by the same person for Subversion repositories. Anyway, the rule of thumb is "when you've finished a "thing", get it out of your local tree as quickly as possible (either by sending it to CVS or attaching it as a patch to a bug report). The "thing" could be a feature, a document, or a bug fix.

Cheers, Dave.

Hi,

raymond ostertag writes:

Le lun 05/01/2004 à 00:49, Roman Joost a écrit :

a) Screenshots should be made with the standard GNOME theme and a generic font (like Bitstream Sans).

Standard GNOME theme is ? I don't remember but on my Mandrake the standard is Galaxy ??

I think Roman wanted to suggest to not use any GTK+ theme at all.

Well I made the SVG with sodipodi 0.33 with the fonts installed on my Mandrake 9.2. My first goal was to release this in XCF with text layers but the SVG import don't transform the Sodipodi text in Layers (may be I miss something).

GIMP-2.0 imports paths from SVG files. Noone ever claimed it would import text as text layers. Perhaps we can add such a feature later.

Sven

On Jan 10, 2004, at 4:38 pm, David Neary wrote:

It kind of does - it's not changeset oriented in the way that BK or Arch are, but checking in several files at once is possible, and cvs2svn manages to make changesets out of commits that happen with the same comment, at the same time, by the same person for Subversion repositories. Anyway, the rule of thumb is "when you've finished a "thing", get it out of your local tree as quickly as possible (either by sending it to CVS or attaching it as a patch to a bug report). The "thing" could be a feature, a document, or a bug fix.

Totally agreed. I just wanted to point out that a "thing" is often spread over many files in documentation which makes it look like it's a heavy change although in reality it is not and of course those things should be commited as a whole in one batch.

-- Servus,
Daniel

Le sam 10/01/2004 à 01:10, Roman Joost a écrit :

On Fri, Jan 09, 2004 at 10:06:50PM +0100, raymond ostertag wrote:

Le lun 05/01/2004 ?? 00:49, Roman Joost a ??crit :

A new cvs update should bring you all the changes. I hope, that the anonymous gnome cvs servers are now in sync with the other ones ... If not, drop me an e-mail and i'll send a tarball to you and Julien. The gimp.xml xincludes now the xml files and the entities are gone. There is additionally a tools.xml in the toolbox directory, which xincludes the tools. Have a look at gimp.xml and tools.xml.

my CVS is updated, the files gimp.xml and tools.xml are presents.

Make process begin with :

cd ../html/C && /usr/bin/xsltproc --xinclude --nonet ../../stylesheets/plainhtml.xsl ../../src/gimp.xml Attempt to load network entity
http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd ../../src/gimp.xml:6: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" ]>

But I am connected and the URL seems correct ... And then :

Writing gimp-xrefs-en.xml for book(GIMP) No template matches xi:include in chapter. Writing ch01.html for chapter(introduction) No template matches xi:include in chapter. Writing ch02.html for chapter(legal) No template matches xi:include in chapter. No template matches xi:include in chapter. No template matches xi:include in chapter. Writing ch03.html for chapter(toolbox) No template matches xi:include in chapter. No template matches xi:include in chapter. ....

@+
Raymond

On Jan 11, 2004, at 11:00 am, raymond ostertag wrote:

cd ../html/C && /usr/bin/xsltproc --xinclude --nonet ../../stylesheets/plainhtml.xsl ../../src/gimp.xml Attempt to load network entity
http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd ../../src/gimp.xml:6: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" ]>

But I am connected and the URL seems correct ... And then :

Too old version of xsltproc.

-- Servus,
Daniel

Hi,

raymond ostertag writes:

Make process begin with :

cd ../html/C && /usr/bin/xsltproc --xinclude --nonet ../../stylesheets/plainhtml.xsl ../../src/gimp.xml Attempt to load network entity
http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd ../../src/gimp.xml:6: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" ]>

But I am connected and the URL seems correct ...

The DTDs are absolutely necessary in order to process the files. You cannot expect things to work if the DTDs are missing. Also you shouldn't use the DTDs from the network but have them installed at your computer. You will need an XML catalog file that tells your XSLT processort where the DTDs are found on your disk. Usually this file lives in /etc/xml. AFAIK it is correctly installed on recent RedHat systems; it is known to be broken on Debian and I don't know about other distributions. For Debian there is a script that attempts to fix the catalog file. Use it at your own risk:

http://sven.gimp.org/build-xml-catalog-for-debian.sh

Sven

Hi,

Daniel Egger writes:

Too old version of xsltproc.

I don't think that's the problem (see my other mail) but let's assume it would be the problem... What makes you think it's a version problem and what would be the minimum xsltproc version that people need in order to build the help files?

Sven

On Jan 11, 2004, at 3:40 pm, Sven Neumann wrote:

I don't think that's the problem (see my other mail)

I know that it could simply because I experienced exactly the same problem with exactly the same symptoms in a different project 3 days ago.

What makes you think it's a version problem and

xsltproc processed the xi:include tags like other tags complaining about the inavailability of matching processing instructions althout the switch --xinclude was given.

what would be the minimum xsltproc version that people need in order to build the help files?

According to Daniel Veillard in
http://lists.w3.org/Archives/Public/www-xml-xinclude-comments/2002Dec/ 0000.html
libxml version 2.4.28 should handle xinclude just fine which would mean that Debian stable for instance is too old.

Other than that it seems a bit tricky to tell which version I'm running exactly since "xsltproc --version" is sortof unparsable for humans but xsltproc from Debian unstable worked quite well for some time now.

This is what I'm running: egger@alex:~$ xsltproc --version
Using libxml 20603, libxslt 10101 and libexslt 801 xsltproc was compiled against libxml 20603, libxslt 10101 and libexslt 801
libxslt 10101 was compiled against libxml 20603 libexslt 801 was compiled against libxml 20603

lucy:/sw egger$ xsltproc --version Using libxml 20602, libxslt 10100 and libexslt 800 xsltproc was compiled against libxml 20602, libxslt 10100 and libexslt 800
libxslt 10100 was compiled against libxml 20602 libexslt 800 was compiled against libxml 20602

(This one doesn't work all that well...)

lucy:/sw egger$ /usr/local/bin/xsltproc --version Using libxml 20604, libxslt 10102 and libexslt 802 xsltproc was compiled against libxml 20604, libxslt 10102 and libexslt 802
libxslt 10102 was compiled against libxml 20604 libexslt 802 was compiled against libxml 20604

-- Servus,
Daniel

On Jan 11, 2004, at 3:23 pm, Sven Neumann wrote:

The DTDs are absolutely necessary in order to process the files.

No, they are not. They are needed for some advanced DOM validation but one can very well process whole books without it.

http://sven.gimp.org/build-xml-catalog-for-debian.sh

Thanks, will try.

--
Servus,
Daniel

Le dim 11/01/2004 à 12:05, Roman Joost a écrit :

But I am connected and the URL seems correct ...

I think, thats because of --nonet parameter.

--nonet is part of the makefile.am itself, so maybe it's not a good idea to suppress it ?

It's finally a new xsltproc like mentionned Daniel and the solution posted by Owen Cook works for me.

I just now have to care about Julien who should have the same problem.

Thank you everybody.

@+ Raymond

Hi,

Roman Joost writes:

I looked at http://www.sagehill.net/docbookxsl/UseCatalog.html#d0e3162 and it seems for me, that we don't need a DTD declaration on top of gimp.xml if the catalog file is present and the corresponding environment variable is set. I tried to build the manual after removing the declaration and the translation process works fine. If this would work on other machines, i'll remove the DTD declaration on top of gimp.xml.

Are there any concerns about that or do i missed something?

You loose the ability to validate the file w/o explicitely specifying the DTD file. Also I am surprised that you can process the file w/o the DTD. Aren't you using any entities? What would be the advantage of removing the DTD declaration?

Sven