Hi,

Marco's post reminds me that I lately read about the GNOME documentation project switching from DocBook to Mallard [1]. I think this is considerable if we want to use GNOME's manpower to contribute to GIMP's user documentation and it could also have impact on the choice of translation tools.

Kind regards

Sven

[1] https://wiki.gnome.org/action/show/Projects/ProjectMallard?action=show&redirect=ProjectMallard https://wiki.gnome.org/DocumentationProject/

Dear Marco,

On Tue, Sep 09, 2014 at 10:47:21PM +0200, Marco Ciampa wrote:

Hi Roman, I am afraid of being a bit off topic (see below). I am wondering about this:

http://wiki.gimp.org/wiki/Documentation:Main https://bugzilla.gnome.org/show_bug.cgi?id=723512

Why are you choosing this tool (publican)?

Two reasons:

* It would improve and extend the possible formats we can export to, since we would not have to write all the Makefile rules ourself. * I've used it inside Red Hat.

Have you considered po4a[1] eventually with the aid of sisu[2]

Nope. Thanks for sharing.

[1]
http://po4a.alioth.debian.org/

[2] http://www.jus.uio.no/sisu/sisu_markup/ http://en.wikipedia.org/wiki/SiSU
http://www.sisudoc.org/

I actually haven't started on the work looking into publican because of real life.

What I do know is, that publican would not lower the barrier for writers to contribute new content to the manual, since it still uses DocBook.

I did consider looking into asciidoc[1] tho, since asciidoc provides the same semantic model, but is simple text. Yet a first glance at it, I was unable to see any way on extracting the strings in order to support translation based on po files. It looks like SiSU tries to achieve a similar goal by using text. I think that would improve the manual, since no one has to write XML anymore.

The additional benefit of asciidoc would be, that it could export to docbook, which then could hook into our current setup. Not sure if this is applicable tho.

I am considering these tools for another project (KiCad) but I think that GIMP too could gain from these, as you pointed out, only I want to discuss pros and cons with someone more skilled than me. :-)

Maybe we can catch two birds with one stone analizing these two tools for the two projects that IMHO have similar goals.

po4a could be a potential candidate to extract strings from asciidoc... not sure.

What do you think?

It's certainly worth looking into. All I did with publican is to check if we could benefit from it.

Cheers,

Roman Joost
www: http://www.romanofski.de
email: romanofski@gimp.org

On Fri, Sep 19, 2014 at 01:00:55PM +1000, Roman Joost wrote:

What I do know is, that publican would not lower the barrier for writers to contribute new content to the manual, since it still uses DocBook.

I did consider looking into asciidoc[1] tho, since asciidoc provides the same semantic model, but is simple text. Yet a first glance at it, I was unable to see any way on extracting the strings in order to support translation based on po files. It looks like SiSU tries to achieve a similar goal by using text. I think that would improve the manual, since no one has to write XML anymore.
[...]

And I forgot the link:

http://www.methods.co.nz/asciidoc/

Kind Regards,

Roman Joost
www: http://www.romanofski.de
email: romanofski@gimp.org

On Wed, Sep 10, 2014 at 12:07:24AM +0200, scl wrote:

Hi,

Marco's post reminds me that I lately read about the GNOME documentation project switching from DocBook to Mallard [1].

This is concerning. I never took Mallard as a big contender, since it doesn't solve any of the problems with DocBook. For writers, writing XML sucks. Now with Mallard we just say: "Hey - you just write less XML", but it will still suck.

I think this is considerable if we want to use GNOME's manpower to contribute to GIMP's user documentation and it could also have impact on the choice of translation tools.

Yes, that is true. It feels a bit as if the documentation world splits apart again in terms of tools.

I certainly can't understand from a users point of view, why we still want to keep XML. I can understand it from a technical point of view - yes ...

Kind Regards

Roman Joost
www: http://www.romanofski.de
email: romanofski@gimp.org

Dear Marco,

On Tue, Sep 09, 2014 at 10:47:21PM +0200, Marco Ciampa wrote:

Hi Roman, I am afraid of being a bit off topic (see below). I am wondering about this:

http://wiki.gimp.org/wiki/Documentation:Main https://bugzilla.gnome.org/show_bug.cgi?id=723512

Why are you choosing this tool (publican)? Have you considered po4a[1] eventually with the aid of sisu[2]

[1] http://po4a.alioth.debian.org/

... at a closer glance, I see that this tool supports AsciiDoc:

text (simple text files with some formatting, markdown, or AsciiDoc)

I feel confident that might be a beneficial. Perhaps something worth investigating in a branch and see how far we go.

Cheers,

Roman Joost
www: http://www.romanofski.de
email: romanofski@gimp.org