Some questions about mallard

On Mon, Jun 27, 2011 at 2:33 AM, Shaun McCance <shaunm at gnome.org> wrote:
> All right, so here's the basic idea of the as-yet-unwritten glossary
> and index extension. It has a lot of overlap with what you want to
> do for bibliographies. It could be that it would be sufficient for
> bibliographies.
>
> Terms are defined with the gloss:term element in the info element
> of any page or section. If some page wants to provide a definition
> for Mallard, it would do this:
>
> <page id="mallard">
>  <info>
>    <gloss:term>
>      <title>Mallard</title>
>      <p>Mallard is an XML format for creating topic-oriented
>      documents with dynamic links and navigation.</p>
>    </gloss:term>
>    ...
>  </info>
>  ...
> </page>
>
> You then have a page that collects these terms. This is a special
> type of page with the type attribute set to "gloss".
>
> <page id="glossary" type="gloss">
>  <title>Glossary of Terms</title>
> </page>
>
> The page collects definitions, as well as links to page that made
> those definitions. If the definition is provided on the glossary
> page itself, it doesn't get a link. Multiple plages can declare
> a term, even without providing definitions, to get return links
> from the glossary page. So the glossary also acts as a sort of
> index.
>
> You can link to a term inline like so:
>
> <p><gloss:term xref="glossary">Mallard</gloss:term></p>
>
> Or this:
>
> <p><link xref="glossary" gloss:term="Mallard">Mallard</link></p>
>
> Or this:
>
> <p><gloss:term xref="glossary" term="Mallard">ducks</link></p>
>
> Or a few other ways. I won't go into all the details. I'm just
> trying to give an overview. The point is, the term is separate
> from the xref, because xref really only knows about pages and
> sections. But with the term, you will get correct scrolling.
[... other cool stuff ..]

Hi,

this looks great, I guess it would work well for us!
In the meantime, I was looking for what is possible right now, so I
created a (simple) xslt to generate a valid mallard page for
"bibliography", based on the ref we currently have in docbook format,
references are linked with existing xref links to this page for now,
but adding a separate attribute for the term to get proper scrolling
(and possibly highlight) would be great.

For now I just created a page filled with refs grouped in a <terms>
list, with a lot of style hints (authors, title, year,...). As this
content is generated it is easy to move to other markup when it is
ready.

I attach the xslt file in case someone wants to have a look, it works
for me but is very basic and will only work for some docbook
bibliographies. It also had been a long time since I used xslt...

Do you have any idea about when you expect to have code to test for
your proposed extension? I would be glad to test it, and write some
code if needed, but I have little experience with this kind of things.
Having a well-defined format for the glossary entries and proper
linking would be enough for us right now but I do not think it makes
sense to make a separate extension for it.
How are extension supposed to work from the code side? Can we just
drop a xslt file into the mix and ask yelp-build to take it into
account with a command-line flag?

Anyway, I checked out and built the latest yelp-xsl and yelp-tools and
it works fine, but did it lost the ability to provide a custom css
file as gnome-doc-tool allows?


Best regards.

-- 
Aurélien Naldi
-------------- next part --------------
A non-text attachment was scrubbed...
Name: biblio.xslt
Type: application/octet-stream
Size: 2121 bytes
Desc: not available
URL: <http://projectmallard.org/pipermail/mallard-list/attachments/20110627/aecbfc60/attachment.obj>