Index of all topics in a set of Mallard pages

Shaun McCance <shaunm at gnome.org>
Wed May 4 16:12:41 EDT 2011

On Wed, 2011-05-04 at 19:49 +0200, Philip Chimento wrote:
> 2011/5/1 Shaun McCance <shaunm at gnome.org>:
> > 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.
> 
> Hmm, I can't get it to work in Yelp 3.0.2. No links are showing up on
> the index page. Have I got the correct namespace for 'facet'? I have
> "http://projectmallard.org/facet/1.0/". I've tried with the
> <facet:match> element inside and outside the pages' <info> elements,
> if that makes any difference. Any ideas?

1) On the page you want the links to appear on, make sure
you set the type attribute to "facets".

2) There was a typo in my instructions above. The page that
has the links has the facet:match element in the info element,
as above. The other pages, though, have a facet:tag element,
not a facet:match element. Add this to each page:

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

Sorry. That's what happens when I don't proofread.

--
Shaun