Replacing MIME attribute for syntax highlighting

Shaun McCance <shaunm at>
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.

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

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:

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.