Re: question about mallard topic organization

[Shaun McCance <shaunm gnome org>]

On Sat, 2010-10-30 at 13:06 -0400, Tiffany Antopolski wrote:
> Hi,
> 
> I am working on Evince Mallard docs.  I am having a problem figuring
> out why one of the topic pages is not sorting itself alphabetically.
> More specifically the guide page has a section called Reading
> Documents, and the topics in it are listed in this order:
> 
> Zooming in and out
> Error when opening a File
> Finding things in a document
> Moving around  a document
> Opening a document
> Passwords-protected documents
> 
> As you can see it's the Zooming in and out that is the problem.
> However the problem gets interesting.  I have an older version of the
> evince docs folder (let's call it evince_old), where that page is
> sorted properly, so appears at the end.   The difference in the
> zooming.page between the evince_old and evince_current folder is
> trivial (I am attaching both here).  If I take the zooming.page from
> evince_old and move it to evince_current, it sorts properly, and
> similarly if I take the zooming.page from evince_current and move it
> to evince_old, it appears first in the guide page.  (Since the two
> pages are in essence the same, I thought something else may have been
> interfering, so I had done this test and was surprised that it seems
> the problem really is in zooming.page).  So in a way, I can fix the
> problem just by reverting back to the older version of zooming.page,
> but I am curious as to what exactly is causing this to happen.  Any
> help or insight would be appreciated.

It's because the title technically starts with a newline,
and it's being sorted as such. That's a bug on my end.
Yelp should really use a space-normalized string to sort.
I'll fix that today. Meanwhile, it's probably best to just
write titles like this:

<title>Zooming in and out</title>

> 
> P.S.  Also, is there a way to manually set the order of topic pages in
> a section... I have another section where the topics begin with a
> number, so they appear in this order:  1,10,11...2, 3 etc.  I would
> want them to be in numerological order instead of 'alphabetical'
> order, so I think this would have to be set manually?  

There is a way to control the ordering using link groups.
Basically, you add a groups attribute to a page or section
element with a space-separated list of group names:

<page type="guide" id="index" groups="first second third"/>

Then you can put links into groups by specifying a group
on the link element:

<link type="guide" xref="index" group="second"/>

There are also three implicit groups: #first, #default, and
#last. You can use these to push links to the top or bottom
without actually defining groups. If you're sure no extra
pages will be added, you can use this to list the order of
each and every page, but it's not really designed for that.
It's design for a simpler push-up/push-down case.

In your case, however, there's a better way. You're not
really trying to micro-manage the ordering. You're just
trying to fix inadequacies in alphabetical ordering, in
a very mechanical way.

Mallard allows you to add extra titles with type attributes
to an info element. These are used instead of the main title
for various purposes, depending on the type attribute. What
you want here is an alternate title to be used for sorting.
Do something like this:

<page id="one">
  <info>
    <title type="sort">01 is the loneliest number</title>
  </info>
  <title>1 is the loneliest number</title>
  ...
</page>

The zero-padded title will be used whenever the title is
used for sorting, but the normal title will still be used
for display. Sort titles are useful for cases like this,
or for dropping leading articles ("a", "the", etc) from
sorting.


-- 
Shaun McCance
http://syllogist.net/