Replacing MIME attribute for syntax highlighting

Shaun McCance <shaunm at gnome.org>
Sat Jan 5 11:59:19 EST 2019

One of the 1.1 MEPs is to deprecate the mime attribute in favor of a
simpler type attribute for things like code.

http://projectmallard.org/mep/mep0010
https://github.com/projectmallard/projectmallard.org/issues/38
https://github.com/projectmallard/projectmallard.org/issues/21

This has been implemented in yelp-xsl (and thus yelp, yelp-build,
pintail, etc) for quite some time. The change affects four elements:

http://projectmallard.org/1.1/mal_block_code
http://projectmallard.org/1.1/mal_block_screen
http://projectmallard.org/1.1/mal_inline_cmd
http://projectmallard.org/1.1/mal_inline_code

I've now written the spec, finished off the MEP, and updated the 1.1
schemas. I'd appreciate feedback on this change, as it's the first
completed change that actually deprecates something. I'd also love to
see some testing.

Here's how you can test. If you have documents with a mime attribute on
code, screen, or cmd elements, remove that mime attribute in favor of a
type attribute. If your mime attribute looked like this:

  <code mime="application/x-shellscript">

Change it to this and be happy:

  <code type="sh">

(For actual production, you might want to keep both the mime and type
attributes if you care about yelp versions more than a year or so old.
But for testing, all out replacing attributes is better.)

There's no great documentation on type attribute values yet (I could
show you exactly how to add that if you want to help), but for most
programming languages, the file extension is probably correct. You can
also have a space-separated list of type values for when one thing is a
more specific variant of another thing. Use this for XML vocabularies:

  <code type="xml mallard">

If you need to consult a list, there's this:

https://gitlab.gnome.org/GNOME/yelp-xsl/blob/master/xslt/mallard/html/m
al2html-block.xsl#L200

Using the type attribute will make your pages no longer validate
against the 1.0 schema. To validate against the 1.1 schema, change or
set the version attribute on the page element to "1.1":

  <page version="1.1" ...>

If you're already using a version attribute with extension versions,
replace the "1.0" token with "1.1" but leave the rest alone, e.g.:

  <page version="1.1 if/1.0" ...>

Note that the 1.1 schema is not installed locally yet unless you do
some hacks, so `yelp-check validate` will have to hit the network.

Thanks,
Shaun