[Gimp-docs] GIMP manual writing in 2009

[Axel Wernicke]

Hi Alessandro,

2008/6/11 Alessandro Falappa <alessandro at falappa.net>:

> Axel,
>    your proposal is indeed original and tackles the problems from a
> whole different point of view.
> By looking at the Blender documentation example I acknowledge that there
> are indeed a lot of advantages in the "wiki way" especially as far as
> authoring and proofreading is concerned.
>
> As Julien  pointed out I haven't properly got how a translator can
> actually translate a topic but from a user perspective I guess it would
> end up having something like Wikipedia where in the side bar you have
> "Other languages: English Deutsch ...". May be you coud add a sample
> page in your proof of concept wiki where you show how it looks when you
> make a topic available in more than one language?


I added some examples for that. For Example look at
http://lexaikon.dnsalias.org/~medius/mediawiki/index.php/24_gimp-tool-rect-select/en#Rectangle_Selectionat
the top of the section you find a list of the languages the manual is
available in. All the blue links mean that translation is available, the red
ones point out missing translations. Klicking on a blue link brings you to
the translation of just that piece of content.
Of course these links are not maintained manually, as you can see by looking
into the source of that article. The whole language selection area is
created by a template that is called as {{Language|<gimp
versionversion>_<gimp help id>}}.


>
>
> Another big issue to think about is how to ship the manual in a packaged
> form to let users install an offline copy of it alongside the GIMP
> application. Is it possible? How do you think to solve this?


Thats a 100% percent valid concern! It has of course to be possible to
create "something" that can be deployed in addition to the gimp app to
provide offline help. The solution is to create a set of html pages from the
wiki which provide the same content as the online version but without
editing functionality of course. You can get a preview of such a static html
page by clicking on the "print version" link in the tool bar on the left
side.
media wiki provides some well maintained extensions to create a static html
version of a whole wiki too - these can be used to create the "offline help"
files.


>
>
> Other issues:
> What about the context sensitive help invocation mechanism?
> What's the impact on GIMP code?


Right now gimp calls the help by creating and opening an url that contains
of some building blocks:

<base>/<language>/<gimp help id><.html>

Example 'file://user/me/here/is/the/gimp-help/html' / 'en' /
'gimp-tool-rect-select' '.html'

So, guess what, that mechanism also works for the wiki. Here we could have
just on additional building block - the gimp version. It would look like:

<base> / <gimp version>_<gimp help id> / <language>

Example: 'http://lexaikon.dnsalias.org/~medius/mediawiki/index.php' / '24' _
'gimp-tool-rect-select' / 'en'

In addition to that you get something very cool: if you do not add a
specific language, the wiki tries to determine the language of the user and
automatically forwards to that language if it exists (so me beeing german
forwards the wiki from http://lexa [...] /24_gimp-tool-rect-select to
http://lexa [...] /24_gimp-tool-rect-select/de) If the page in the language
of the user not exists, the wikis default language (usually english) is
shown to the reader.


To get all this there is an abstraction layer build in. The content is
written in articles named like the topic in each language:

for en: http://lexa [...] /Selection Tools
for de: http://lexa [...] /Auswahlwerkzeuge


in addition to that there are some forwarding rules (build into pages):

http://lexa [...] /24_gimp-tools-selection -> 'Selection Tools'
http://lexa [...] /24_gimp-tools-selection/en -> 'Selection Tools'
http://lexa [...] /24_gimp-tools-selection/de -> 'Auswahlwerkzeuge'

This way one gets articles that contain purely one language only (including
the page title) bound to each other by the gimp-help-id that is also the
link to the gimps context help. Even more, with this architecture you can
manage the manual for more than one version in one wiki at a time. For gimp
2.6 we would just have to add 26_gimp-tools-selection.


Hope this makes it somewhat more clear. Feel free to ask further questions
:)

Greetings, lexA




>
>
> Greets.
>
> Axel Wernicke ha scritto:
> > Hi List,
> > ...
> >
> > I propose to wholeheartly and open minded discuss alternatives. Please
> > have a look into
> >
> http://lexaikon.dnsalias.org/~medius/mediawiki/index.php/Meta/Why_GIMP-Manual_as_wiki#Pro.27s_.26_Con.27s<http://lexaikon.dnsalias.org/%7Emedius/mediawiki/index.php/Meta/Why_GIMP-Manual_as_wiki#Pro.27s_.26_Con.27s>
> > <
> http://lexaikon.dnsalias.org/%7Emedius/mediawiki/index.php/Meta/Why_GIMP-Manual_as_wiki#Pro.27s_.26_Con.27s
> >
> > and let me know what you think about it.
> >
> > Greetings, lexA
>
>
> --
> Alessandro Falappa
> web: http://www.falappa.net/
>
> _______________________________________________
> Gimp-docs mailing list
> Gimp-docs at lists.XCF.Berkeley.EDU
> https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs
>



-- 
life is like a box of chocolates - you never know what you wanna get.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: /lists/gimp-docs/attachments/20080611/a388bbf8/attachment.html