++ed by:
Author image Marco Pessotto
and 1 contributors


Text::Amuse - Generate HTML and LaTeX documents from Emacs Muse markup.


Version 1.76


Typical usage which should illustrate all the public methods

    use Text::Amuse;
    my $doc = Text::Amuse->new(file => "test.muse");

    # get the title, author, etc. as an hashref
    my $html_directives = $doc->header_as_html;

    # get the table of contents
    my $html_toc = $doc->toc_as_html;

    # get the body
    my $html_body = $doc->as_html;

    # same for LaTeX
    my $latex_directives = $doc->header_as_latex;
    my $latex_body = $doc->as_latex;

    # do we need a \tableofcontents ?
    my $wants_toc = $doc->wants_toc; # (boolean)

    # files attached
    my @images = $doc->attachments;

    # at this point you can inject the values in a template, which is
    # left to the user. If you want an executable, please install
    # Text::Amuse::Compile.


new (file => $file, partial => \@parts, include_paths => \@paths)

Create a new Text::Amuse object. You should pass the named parameter file, pointing to a muse file to process. Please note that you can't pass a string. Build a wrapper going through a temporary file if you need to pass strings.

Optionally, accept a partial option pointing to an arrayref of integers, meaning that only those chunks will be needed.

The beamer output doesn't take partial in account.

Optionally, accept a include_paths argument, with an arrayref of directories to search for included files.



Accessor to the Text::Amuse::Document object. [Internal]


Accessor to the file passed in the constructor (read-only)


Return an hashref where the keys are the chunk indexes and the values are true, undef otherwise.


Return a list of directory to look into for included files


Return the list of files included

HTML output


Output the HTML document (and cache it in the object)


The directives of the document in HTML (title, authors, etc.), returned as an hashref.

Please note that the keys are not escaped nor manipulated.


Return the HTML formatted ToC, as a string.


Return a list of strings, each of them is a html page resulting from the splitting of the as_html output. Linked footnotes as inserted at the end of each page.


Return an internal representation of the ToC

LaTeX output


Output the (Xe)LaTeX document (and cache it in the object), as a string.


Return a list of strings, each of them is a LaTeX chunk resulting from the splitting of the as_latex output.


Output the document as LaTeX, but wrap each section which doesn't contain a comment ; noslide inside a frame.


Return true if a ToC is needed because we found some headings inside.


Normally returns true. If partial output, only if the pre string was passed.

Preamble is the title page, or the title/author/date chunk.


Normally returns true. If partial output, only if the post string was passed.

Postamble is the metadata of the text.


The LaTeX formatted header, as an hashref. Keys are not interpolated in any way.



Report the attachments (images) found, as a list.


The language code of the document. This method will looks into the header of the document, searching for the keys lang or language, defaulting to en.


Same as above, but returns the human readable version, notably used by Babel, Polyglossia, etc.


Return a convenience hashref with the header fields set to true when they are defined in the document.

This way, in the template you can write doc.header_defined.subtitle without doing crazy things like doc.header_as_html.subtitle.size which relies on virtual methods.


Always return undef, because in the current implementation you can't switch language in the middle of a text. But could be implemented in the future. It should return an arrayref or undef.


Always return undef. When and if implemented, it should return an arrayref or undef.


Return a validated version of the #hyphenation header, if present, or the empty string.


Return true if the language is RTL (ar, he, fa -- so far)


Return true if the document use direction switches.


Return the direction (rtl or ltr) of the document, based on the language


Return the script of the language.

Implemented for Russian, Macedonian, Farsi, Arabic, Hebrew. Otherwise return Latin.


The updated manual can be found at http://www.amusewiki.org/library/manual or https://github.com/melmothx/amusewiki-site/blob/master/m/ml/manual.muse

See the section "Differences between Text::Amuse and Emacs Muse".

Inline markup

Underlining has been dropped.

Emphasis and strong can also be written with tags, like <em>emphasis</em>, <strong>strong</strong> and <code>code</code>.

Added tag <sup> and <sub> for superscript and subscript.

Inline logic

Asterisk and equal symbols (*, **, *** =) are interpreted as markup elements if they are paired (an opening one and a closing one).

The opening one must be preceded by something which is not an alphanumerical character (or at the beginning of the line) and followed by something which is not a space.

The closing one must be preceded by something which is not a space, and followed by something which is not an alphanumerical character (or at the end of the line).

Block markup

The only tables supported are the native one (with ||| as separator).

Since version 0.60, the code blocks, beside the example tag, can also be written as:

   if ($perl) {...}

Borrowed from the Creole markup.


Embedded lisp code and syntax highlight is not supported.

Esoteric stuff like citing from other resources is not supported.

The scope of this module is not to replicate all the features of the original implementation, but to use the markup for a wiki (as opposed as a personal and private wiki).


Marco Pessotto, <melmothx at gmail.com>


Please report any bugs or feature requests to the author's email or just use the CPAN's RT. If you find a bug, please provide a minimal muse file which reproduces the problem (so I can add it to the test suite).


You can find documentation for this module with the perldoc command.

    perldoc Text::Amuse

Repository available at GitHub: https://github.com/melmothx/text-amuse


The original documentation for the Emacs Muse markup can be found at: http://mwolson.org/static/doc/muse/Markup-Rules.html

Text::Amuse::Compile ships an executable to compile muse files.

Amusewiki, http://amusewiki.org, a wiki/publishing engine which uses this module under the hood (and for which this module was written and is maintained).


This module is free software and is published under the same terms as Perl itself.