From aurelien.naldi at gmail.com  Wed Aug 17 04:46:14 2011
From: aurelien.naldi at gmail.com (=?UTF-8?Q?Aur=C3=A9lien_Naldi?=)
Date: Wed, 17 Aug 2011 10:46:14 +0200
Subject: Referencing glossary entries
In-Reply-To: <1310229469.2158.132.camel@recto>
References: <1310136667.2158.102.camel@recto>
	 <1310214949.2847.56.camel@jaguar> <1310229469.2158.132.camel@recto>
Message-ID: <CAMHNpFGU8kQp9Q3dwFY7Oxr6uD6L7vUwkdXvNENtJ0KgA2UOww@mail.gmail.com>

On Sat, Jul 9, 2011 at 6:37 PM, Shaun McCance <shaunm at gnome.org> wrote:
[...]
> Right, so you can just define all the terms on the glossary page
> itself, to keep them in one place. There's some flexibility here,
> and I guess it's up to authors to decide what's easier for them
> to maintain.
>
> Now, each entry on a glossary page has both definitions and links
> to pages that declared the term. So if you only declare/define
> terms on the glossary page, you get no links. (You could always
> link inline in the definition, of course.) What you could do is
> do the full definitions on the glossary page, and then declare
> terms on other pages for links.
>
> On the glossary page:
>
> <info>
> ?<gloss:term id="mallard">
> ? ?<title>Mallard</title>
> ? ?<p>A dynamic, topic-oriented help markup language.</p>
> ?</gloss:term>
> </info>
>
> Then on any other page you want the glossary entry to link to:
>
> <info>
> ?<gloss:term id="mallard"/>
> </info>
>
> Think of glossary terms as miniature guides. Declaring a term
> on a page is then like declaring a guide link.

Hi,

I can confirm that this work great for me: I have a biblio.page file
where all terms are defined (generated from a docbook file), but I
find it a bit cumbersome to define the term in the page info just to
get the backward link.
While I see advantages in being able to pick which pages are
back-linked, it feels unconsistent with other links which always
trigger a backlink.

I would like to have a backlink whenever a page points to a term, even
if it is not defined in the page info. If we do want to avoid
introducing it, an attribute in the reference link could disable it
for this links. Then if another link in the page asks for it or if it
is defined in the page info, the backlink should still be here.
This way, we have full control (in a more intuitive way for me, but
your mileage may vary), and it would be easier to maintain as well:
adding or removing a link do not require to edit the page info or to
check if the link is used on some other part of the page.

PS: while the glossary page works well in the html output, it is empty in yelp.
Version info:

$ dpkg -l | grep yelp
ii  libyelp0                   3.1.2-0ubuntu1
ii  yelp                        3.1.2-0ubuntu1
ii  yelp-tools                3.1.4-0ubuntu2
ii  yelp-xsl                   3.1.3-0ubuntu1


Best regards.

-- 
Aur?lien Naldi


From gnugeo at gnugeo.de  Wed Aug 24 06:38:11 2011
From: gnugeo at gnugeo.de (Jochen georges)
Date: Wed, 24 Aug 2011 12:38:11 +0200
Subject: internationalized documentation with mallard ?
Message-ID: <4E54D493.6050004@gnugeo.de>

Hello,

I am looking for an easy to use tool to make a helpsystem for a
java-application.

It should provide the possibility of an internationalized documentation.

Is that possible with mallard?

Thanks for your answers!

Sincerely
Jochen


From shaunm at gnome.org  Wed Aug 24 14:01:32 2011
From: shaunm at gnome.org (Shaun McCance)
Date: Wed, 24 Aug 2011 14:01:32 -0400
Subject: internationalized documentation with mallard ?
In-Reply-To: <4E54D493.6050004@gnugeo.de>
References: <4E54D493.6050004@gnugeo.de>
Message-ID: <1314208892.31755.67.camel@recto>

On Wed, 2011-08-24 at 12:38 +0200, Jochen georges wrote:
> Hello,
> 
> I am looking for an easy to use tool to make a helpsystem for a
> java-application.
> 
> It should provide the possibility of an internationalized documentation.
> 
> Is that possible with mallard?
> 
> Thanks for your answers!

There are a lot of things you'll have to take care of for a
fully internationalized help system. For example, you'll need
to be able to load the document in the correct language based
on the user's locale. This is kind of outside the scope of
Mallard, which is just the document markup. I can give some
tips on how to do that with Mallard documents though.

The bulk of the work is going to be in translating your files
into other languages. For that, you *really* want to be using
some sort of message-based translation system, like PO files
or XLIFF. Don't make your translators do entire pages without
any sort of change tracking.

For translating Mallard using PO files, take a look at itstool:

 http://itstool.org/

It extracts paragraphs and other block elements and puts them
into PO files for your translators. It then merges translations
from PO files with the original pages to create translated pages.
Everything it knows about how to deal with an XML vocabulary
comes from ITS rules. ITS (Internationalization Tag Set) is a
W3C recommendation for marking localization-related information
in XML.

The nice thing about ITS is that you can override the built-in
rules for special cases. For example, you could mark a run of
text as untranslatable, and itstool won't put it into the PO
file.

XML formats in general make localization easier, because they're
easily parsed and there's a wealth of tools for XML. But there
are things a format can do better or worse about, and you should
be aware of those things.

  http://projectmallard.org/1.0/details.html

Take a look at the three topics under "Internationalization and
Localization" for more details about internationalizing Mallard
documents. And if you have any questions or concerns, feel free
to email the list.

-- 
Shaun McCance
Community Help Expert
http://syllogist.net/




From listas at mabishu.com  Wed Aug 24 14:35:04 2011
From: listas at mabishu.com (Fran Dieguez)
Date: Wed, 24 Aug 2011 20:35:04 +0200
Subject: internationalized documentation with mallard ?
In-Reply-To: <1314208892.31755.67.camel@recto>
References: <4E54D493.6050004@gnugeo.de>  <1314208892.31755.67.camel@recto>
Message-ID: <1314210905.21071.1.camel@fry>

E adem?is pode exportar a HTML cunha plantilla personalizada.
-- 
Fran Dieguez <listas at mabishu.com>

O M?r, 24-08-2011 ?s 14:01 -0400, Shaun McCance escribiu:
> On Wed, 2011-08-24 at 12:38 +0200, Jochen georges wrote:
> > Hello,
> > 
> > I am looking for an easy to use tool to make a helpsystem for a
> > java-application.
> > 
> > It should provide the possibility of an internationalized documentation.
> > 
> > Is that possible with mallard?
> > 
> > Thanks for your answers!
> 
> There are a lot of things you'll have to take care of for a
> fully internationalized help system. For example, you'll need
> to be able to load the document in the correct language based
> on the user's locale. This is kind of outside the scope of
> Mallard, which is just the document markup. I can give some
> tips on how to do that with Mallard documents though.
> 
> The bulk of the work is going to be in translating your files
> into other languages. For that, you *really* want to be using
> some sort of message-based translation system, like PO files
> or XLIFF. Don't make your translators do entire pages without
> any sort of change tracking.
> 
> For translating Mallard using PO files, take a look at itstool:
> 
>  http://itstool.org/
> 
> It extracts paragraphs and other block elements and puts them
> into PO files for your translators. It then merges translations
> from PO files with the original pages to create translated pages.
> Everything it knows about how to deal with an XML vocabulary
> comes from ITS rules. ITS (Internationalization Tag Set) is a
> W3C recommendation for marking localization-related information
> in XML.
> 
> The nice thing about ITS is that you can override the built-in
> rules for special cases. For example, you could mark a run of
> text as untranslatable, and itstool won't put it into the PO
> file.
> 
> XML formats in general make localization easier, because they're
> easily parsed and there's a wealth of tools for XML. But there
> are things a format can do better or worse about, and you should
> be aware of those things.
> 
>   http://projectmallard.org/1.0/details.html
> 
> Take a look at the three topics under "Internationalization and
> Localization" for more details about internationalizing Mallard
> documents. And if you have any questions or concerns, feel free
> to email the list.
>