Top-level stack element

Shaun McCance <shaunm at gnome.org>
Sun Oct 21 10:48:04 EDT 2018

I spent a little time working on the stack element. Here's the
beginnings of a MEP:

http://projectmallard.org/mep/mep0013.html

It's implemented in yelp-xsl and yelp-build, and working just fine as
far as I can tell. It would still need implementation work in yelp,
yelp-check, pintail, itstool, and any custom build scripts out there.

The basic idea is you can write multiple pages in a single file:

<stack>
  <page id="page1">
    ...
  </page>
  <page id="page2">
    ...
  </page>
  ...
</stack>

The stack can have an info element, and some of the elements in there
(credit, license, revision) apply to all pages in the stack.

If the stack has type="series", then each page implicitly gets a next
link to the next page. If nothing else, this is a much nicer way of
writing a linear series than writing next links.

There's an open question of what to do with informational link elements
in the stack info. Some thoughts:

* It doesn't make sense to apply next links across pages.

* It does make sense to apply guide links across pages. Then you can
more easily write all the pages under one guide in one stack. (What
would maybe be more convenient is to write a guide and all its pages in
one stack. Maybe a different stack type?)

* I don't think it makes sense to apply topic links across pages,
unless you frequently write collections of guide pages that all link to
the same topics. Maybe they should just apply anyway.

* It makes some sense to apply seealso links across pages. What would
probably be even more convenient is to be able to make all pages in the
stack seealso link to each other.


Feedback greatly appreciated.

Thanks,
Shaun