Index of all topics in a set of Mallard pages

Shaun McCance <shaunm at gnome.org>
Sun May 1 17:25:03 EDT 2011

On Sun, 2011-05-01 at 21:30 +0200, Philip Chimento wrote:
> Hi,
> 
> Is there any facility in Mallard for creating an alphabetical index of
> topics, even ones that are not linked to on the main 'index.page'
> guide page?
> 
> What I tried is to create a section on the main index.page:
> 
> <section id="full-index">
>   <title>Index</title>
> </section>
> 
> and then a separate guide page, full-index.page, which every topic
> page links to using something like:
> 
> <link type="guide" xref="full-index"/>
> 
> This works fairly well, except for three things:
> - You have to manually add a link on every topic page.
> - When viewing with Yelp, where each page normally shows its hierarchy
> at the top, (e.g. Foo Guide ->  Foo Topic) it now also shows a second
> entry (Foo Guide ->  Index ->  Index of all help topics).
> - There is a see-also link on the bottom of every topic page that
> points to the index.

You could try using the experimental facets extension.

http://blogs.gnome.org/shaunm/2010/12/16/more-faceted-navigation/
http://projectmallard.org/facet/1.0/

Here's the gist. Create a page that collects all the links.
Set the type attribute on the page element to "facets". In
the info element, add this:

  <facet:match key="all-pages"/>

Then in each topic, add this:

  <facet:match key="all-pages" value="something"/>

The value doesn't really matter. You're not doing anything
besides aggregating pages with that tag. All that matters is
that the key attribute matches on all pages.

This solves problems 2 and 3 above (which are symptoms of the
same problem). You'll still have to manually add a facet tag
to each page. Perhaps we could add a way for facets pages to
aggregate all pages. (By just omitting facet:match perhaps?)

And the big caveat. This is still experimental. There could
be backwards-incompatible changes before it's releases. But
what I outlined does actually work in Yelp 3 right now.

> Is there perhaps some sort of style="no-see-also" attribute possible
> that one can use to suppress these see-also and hierarchical links to
> the index?

That's come up a few times. It's pretty clear there's a need
to be able to specify one-way links. Definitely something that
should be on the table for Mallard 1.1.

--
Shaun