1.0 Features

Hi Shaun,

Sorry, I realised I didn't reply to this.

On Tue, 2011-02-15 at 10:06 -0500, Shaun McCance wrote:
> I'd like to finally declare Mallard 1.0 stable this summer,
> so I'm looking over what outstanding features might be worth
> including. Here's my proposed list:
> 
> * The links element - Discussed on this list last August.
> This gives you a way to control how and where automatic
> links are displayed, such as links on guide pages. This
> is the biggest of the proposed features. I'll write up a
> proposed spec and ask for more review.

+1, it's working well for the GNOME Help. It introduces a lot more
flexibility into the navigational structure of complicated documents.

> * A mark element - Yelp has supported the e:hi element in
> the experimental namespace for a very long time, basically
> since the very beginning of Mallard support. It highlights
> a run of text. I added it so I could highlight what was
> added in successive examples in the Mallard spec.

+1, although I worry about abuse when it's being used inside <p> tags.
In most cases <em> will be a better choice - can we offer some guidance
on this in the spec?

> It turns out that e:hi was also useful when doing developer
> tutorials for Gnome. So that makes me think it's probably
> generally useful for a lot of similar cases. Since HTML has
> a similar element called mark, I propose we just use that
> as the element name instead.
> 
> * A version attribute - We should have a way to specify what
> Mallard version a page is written for. The obvious way to do
> that is with a version attribute on the page element.
> 
> I actually have a pretty decent idea of how the version could
> be used to specify what extensions are used, and how a tool
> could dynamically construct an RNG schema to validate based
> on that. It's a tad tricky because of restrictions on name
> classes in RNG, but doable.
> 
> * Extra link title roles - There's a role attribute for link
> titles that allows you to specify different titles for links
> in different contexts. The defined roles are guide, seealso,
> topic, and trail. Extra roles should be added to match the
> things you can do with the links element.

+1, especially if the <desc> element can take different roles too (maybe
not for 1.0 though).

> Looking at the list archives, I see discussions on conditional
> processing, push content, an action attribute, and faceted
> navigation.
> 
> I think conditional processing and faceted navigation are good
> ideas, but should be extensions. Basic facets actually work
> right now in Yelp, but I'd like to hammer on them more before
> trying to finalize a spec.

Yes, conditionals should be an extension. They could lead to very
complex documents, which I think we should try to discourage with the
main spec.

With faceted navigation, I wonder if that could just be implemented as a
"type" attribute for the <links> element? I don't remember how it's
currently being done.

> Push content is a neat idea, but I'm not sure I could get the
> performance good enough for delivery. It might be useful as
> part of a build process. Either way, it's definitely extension
> material.
> 
> As for the action attribute, I'm not convinced it's the right
> way to go. We could probably figure out something more general
> to support more interactive pages. But without more use cases,
> I can't come up with a good proposal.
> 
> I'd love to get some comments on all of these.

Thanks,

Phil

-- 
Phil Bull
https://launchpad.net/~philbull
Book - http://nostarch.com/ubuntu4.htm