8.16 Tags that Muse recognizes

Muse has several built-in tags that may prove useful during publishing. See muse-publish-markup-tags, to see how to customize the tags that Muse uses, as well as make your own tags.

Only a small subset of these tags are available in header and footer text. The muse-publish-markup-header-footer-tags option lists the tags that are allowed in headers and footers.

Syntax

If a tag takes arguments, it will look like this, where “tagname” is the name of the tag.

     <tagname arg1="string1" arg2="string2">

If you want the tag to look like it came straight from an XHTML document, you can alternatively do the following.

     <tagname arg1="string1" arg2="string2" />

If a tag surrounds some text, it will look like this.

     <tagname>Some text</tagname>

If a tag surrounds a large region, it will look like this.

     <tagname>
     Some text.
     Some more text.
     </tagname>

Tag listing

This is the complete list of tags that Muse accepts, including those that were mentioned in previous sections.

‘<br>’

Insert a line break.

Muse will automatically detect paragraphs when publishing by means of blank lines, so this tag is usually unnecessary.

‘<cite>’

Insert a citation to another source.

This takes the argument type, which indicates the type of citation. The valid types are "author" and "year". If this argument is omitted, include both author and year in the citation.

The bibliography to use for the citation may be specified by the #bibsource directive.

See Citations, for additional information.

‘<class>’

If publishing to HTML, surround the given text with a <span> tag. It takes one argument called “name” that specifies the “class” attribute of the <span> tag.

If publishing to a different format, do nothing extra to the text.

‘<code>’

Treat the text surrounded by the tag as if they were enclosed in equal signs, that is, make it monospace.

‘<command>’

Run a command on the region, replacing the region with the result of the command. The command is specified with the “interp” argument. If no value for “interp” is given, pass the entire region to the shell.

The “markup” argument controls how this section is marked up.

If it is omitted, publish the region with the normal Muse rules.

If "nil", do not mark up the region at all, but prevent Muse from further interpreting it.

If "example", treat the region as if it was surrounded by the <example> tag.

If "src", treat the included text as if it was surrounded by the <src> tag. You should also specify the “lang” attribute if doing this.

If "verse", treat the region as if it was surrounded by the <verse> tag, to preserve newlines.

Otherwise, it should be the name of a function to call, with the buffer narrowed to the region.

‘<comment>’

Treat the entire region as a comment. If the option muse-publish-comments-p is nil, delete the region, otherwise publish it using the comment syntax of the current publishing style.

‘<contents>’

Publish a Table of Contents. This will either be inserted in-place or at the beginning of the document, depending on your publishing style. It does not have a delimiting tag.

By default, only 2 levels of headings will be included in the generated Table of Contents. To change this globally, customize the muse-publish-contents-depth option. To change this only for the current tag, use the “depth” argument.

‘<div>’

Insert a <div> tag into HTML documents, and do not insert anything special for other non-HTML publishing formats.

If the “style” argument is provided, include it with the published <div> tag. Likewise for the “id” argument.

‘<example>’

Publish the region in monospace, preserving the newlines in the region. This is useful for snippets of code.

‘<include>’

Insert the given file at the current location during publishing. The basic use of this tag is as follows, replacing “included_file” with the name of the file that you want to include.

          <include file="included_file">

The “markup” argument controls how this section is marked up.

If it is omitted, publish the included text with the normal Muse rules.

If "nil", do not mark up the included text at all.

If "example", treat the included text as if it was surrounded by the <example> tag.

If "src", treat the included text as if it was surrounded by the <src> tag. You should also specify the “lang” attribute if doing this.

If "verse", treat the included text as if it was surrounded by the <verse> tag, to preserve newlines.

Otherwise, it should be the name of a function to call after inserting the file with the buffer narrowed to the section inserted.

‘<lisp>’

Evaluate the Emacs Lisp expressions between the initial and ending tags. The result is then inserted into the document, so you do not need to explicitly call insert. All text properties are removed from the resulting text.

This tag takes the “markup” argument. See the description of <command> for details.

‘<literal>’

Make sure that the text enclosed by this tag is published without escaping it in any way. This is useful for inserting markup directly into the published document, when Muse does not provide the desired functionality.

‘<markup>’

Mark up the text between the initial and ending tags. The markup command to use may be specified by the “function” argument. The standard Muse markup routines are used by default if no “function” argument is provided.

This is useful for marking up regions in headers and footers. One example that comes to mind is generating a published index of all of the files in the current project by doing the following.

          <markup><lisp>(muse-index-as-string t t)</lisp></markup>

‘<perl>’

Run the perl language interpreter on the region, replacing the region with the result of the command.

This tag takes the “markup” argument. See the description of <command> for details.

‘<python>’

Run the python language interpreter on the region, replacing the region with the result of the command.

This tag takes the “markup” argument. See the description of <command> for details.

‘<quote>’

Publish the region as a blockquote. This will either be inserted in-place or at the beginning of the document, depending on your publishing style. It does not have a delimiting tag.

‘<ruby>’

Run the ruby language interpreter on the region, replacing the region with the result of the command.

This tag takes the “markup” argument. See the description of <command> for details.

‘<src>’

Publish the region using htmlize. The language to use may be specified by the “lang” attribute.

Muse will look for a function named lang-mode, where lang is the value of the “lang” attribute.

This tag requires htmlize 1.34 or later in order to work. If this is not satisfied, or the current publishing style is not HTML-based, Muse will publish the region like an <example> tag.

‘<verbatim>’

This is used when you want to prevent Muse from trying to interpret some markup. Surround the markup in <verbatim> and </verbatim>, and it will not be interpreted.

This tag was used often in previous versions of Muse because they did not support whole-document escaping of specials. Now, it will only be needed for other tags, and perhaps footnotes as well.

‘<verse>’

Preserve the newlines in the region. In formats like HTML, newlines are removed by default, hence the need for this tag. In other publishing styles, this tag may cause the text to be indented slightly in a way that looks nice for poetry and prose.