Mallard 1.1 Features

On Thu, 2015-03-05 at 18:07 -0500, Shaun McCance wrote:
> Hi all,
> 
> It really is time we pushed a Mallard 1.1 out the door. There are
> features that people have been waiting for. Many of them are easy. Some
> of them have existed in experimental for a while. Below is a list of
> issues for features that could possibly be in 1.1.
> 
> If you have comments or questions on any of these, reply or leave
> comments on the issues. If you just really like something but don't have
> much to say, feel free to leave a "+1" comment on GitHub. If you think
> something is too half-baked for now, tell me you think we should defer
> to 1.2. (I think quite a few of these should be deferred.)

There were a few questions on IRC, so just to be clear: This was not a
list of what will be in 1.1. It's a list of things of things that could
be in 1.1 or could be deferred to 1.2 (or could be cut altogether).

That said, below my list of must-haves for 1.1, along with rationale. If
you like something not on this list, speak up. Maybe write a MEP.

> Make section IDs optional
> https://github.com/projectmallard/projectmallard.org/issues/2

Very very very common gotcha that only validators care about. Sure you
can't link without IDs, but people will just have to add IDs when they
want to link. The one trouble is people might link *from* a section
without an ID, not realizing the reciprocal link requires the ID. As it
is, people just forget to do IDs all the time, then face spurious and
frustrating validation errors.

> Provide a hi or mark element
> https://github.com/projectmallard/projectmallard.org/issues/3

This has been in Yelp as an experimental feature since forever ago.
Since before 1.0 was final. Probably since it even had a decent draft
specification. It was added to support the Mallard tutorials.

> Make example a formal element
> https://github.com/projectmallard/projectmallard.org/issues/4

This is easy to implement, and example is the only block container
element that can't take a title. With the introduction of block info
elements, I think it's even more important to let example join in the
fun.

> Add info element for formal block elements
> https://github.com/projectmallard/projectmallard.org/issues/5
> http://projectmallard.org/mep/mep0002

This has a lot of uses, and no downsides. It's needed for block linking
(though that's not in my 1.1 must-have list). It's useful for credits
for media and code. You can use it for alternate titles. UI expanders
can take advantage of that right now. And it requires 0 implementation
changes.

> Provide tagging mechanism
> https://github.com/projectmallard/projectmallard.org/issues/7

There are a number of extensions and features that could key off of
this. There was my experiment with faceted navigation. There was my
experiment with auto-populating help buttons and menus in UIs. Link
pools could be automatically constructed. Conditionals could use it.

The sticking point is that it needs to be fleshed out. I don't want to
get the syntax wrong and make potential uses hard or impossible.

> Add a th element
> https://github.com/projectmallard/projectmallard.org/issues/9

Frankly, this was an oversight to begin with. And the Ducktype syntax
already has a shorthand for th, so we might as well make its output
valid.

> Add a keywords element
> https://github.com/projectmallard/projectmallard.org/issues/10

This will help search results a lot.

> Allow info links with href
> https://github.com/projectmallard/projectmallard.org/issues/14

I get asked for this a lot. It really needs a way to specify the link
text though. I think that will be putting a title element into the info
link element. This needs discussion and experimentation, and it might
get deferred to 1.2. But it does get requested often.

> Generic formal div element
> https://github.com/projectmallard/projectmallard.org/issues/15
> http://projectmallard.org/mep/mep0005

Implementation is easy. It makes certain extensions nicer. And sometimes
it's really just useful on its own.

> Allow multiple desc elements
> https://github.com/projectmallard/projectmallard.org/issues/16

You can do all sorts of things with info titles. Why not desc? It just
makes sense to make them work the same.

> Block or desc in links
> https://github.com/projectmallard/projectmallard.org/issues/18

I run into this a lot. It needs some discussion and experimentation.

> Provide one-way links
> https://github.com/projectmallard/projectmallard.org/issues/19

Frequently requested. Very frequently. It's useful, for example, to have
a list of quick links on the index page without putting index into the
guide links and link trails of the topic. This happens a lot.

> Let guiseq and keyseq do linking
> https://github.com/projectmallard/projectmallard.org/issues/20

I'm not sure why they couldn't link before. They are kind of oddballs
among the inline elements. But they're still inline elements, so why
not?