Referencing glossary entries
Aurélien Naldi
<aurelien.naldi at gmail.com>
Wed Aug 17 04:46:14 EDT 2011
- Next message: internationalized documentation with mallard ?
- Sort by: [ thread ] [ subject ] [ author ] [ date ]
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