Some questions about mallard

On Wed, 2011-06-22 at 16:07 +0200, Aurélien Naldi wrote:
> I guess that a good enough use case would not need so many changes to
> mallard itself, but most could be done in a smart external tool.
> In docbook, I used biblioentry, but this was pretty unpleasant. We
> have semantic description of entries as bibtex or similar format and I
> think that reusing such a format is the best option, especially as I
> prefer having the bibliography as a separate page. It may also be
> possible with minimal (if any) changes to mallard itself.
> 
> For example, one could add references as <link xref="biblio#refid">.
> The biblio page can be handwritten, with only paragraphs with the
> proper IDs and span with a good set of style hints. As handwriting it
> can be cumbersome, an external tool could extract required references
> from mallard pages, then build the "biblio" page for these references
> based on a separate bibtex file (or some XML port of bibtex, which
> already exists and is less insane to parse).
> 
> This would be more than good enough for me, the main problem is that
> currently a link can not point to a paragraph.
> Does it seem possible? If you already have a working system for
> glossaries, I guess it can be adapted to fill this gap as well.

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.

Term definitions can also provide short descriptions. Links to
terms can optionally show these as a tooltip on hover. Glossary
pages can match on tags, so you can provide pages like "Index
of new symbols in 2.28" and "Index of all symbols". Sections in
glossaries can segment by tag. Other coolness. I still need to
write a spec. And code.

So, how you might use this extension for bibliographies. You
could have a bibliography page that provides all the entries.
It sounds like you might even generate this automatically from
bibtex. That's cool. It would look something like this:

<page id="bibliography" type="gloss">
<info>
  <gloss:term>
    <title>[Gentle2009]</title>
    <p>Gentle, Anne. Conversation and Community. XML Press.
    2009.</p>
  </gloss:term>
  ...
</info>
</page>

Then you'd link to this in any other page like this:

<p>See <em>Conversation and Community</em> (<gloss:term
xref="bibliography">[Gentle2009]</gloss:term>) for more
information.</p>

Or maybe you want to eschew typical book-like formatting and
go for this:

<p>See <em xref="bibliography" gloss:term="[Gentle2009]"
>Conversation and Community</em> for more information.</p>

So, I don't know if this perfectly suits your needs. I think it
probably at least comes close. Obviously, the extension needs
to exist before it can be useful for you. I'm just trying to
give a glimpse of the kinds of things I intend to work on soon,
in case it helps you too.

You can also just develop your own extension to do the things
you need to do. Mallard was intentionally designed to make that
as easy as possible. I'll help if I can.

--
Shaun