<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head><meta http-equiv="pragma" content="no-cache">
<title>
The Mason Book
</title>
<link rel="stylesheet" type="text/css" href="tppmsgs/msgs0.htm#1" tppabs="http://www.masonbook.com/masonbook.mcss?no_style=0">
</head>

<body>

<div class="bodybox">

 <div class="titlebox">

  <div class="titleboximage">
   <a href="tppmsgs/msgs0.htm#2" tppabs="http://www.masonbook.com/"><img src="cover_small.jpg" tppabs="http://www.masonbook.com/i/cover_small.jpg" width="110" height="144" class="smallcover" alt="Small cover"></a>
  </div>

  <div class="titleboxtext">

   <span class="booktitle">Embedding Perl in HTML with Mason</span><br>
   <span class="bookauthors">Dave Rolsky<br>Ken Williams</span>

  </div>

 </div>

 <div class="mainbox">
  <div class="mainbox2">

   <div class="menubox">
    <h4 id="here">Here</h4>


    <a href="tppmsgs/msgs0.htm#4" tppabs="http://www.masonbook.com/index.mhtml">Home</a><br>
    <a href="tppmsgs/msgs0.htm#5" tppabs="http://www.masonbook.com/news/">News</a><br>
    <b>Read it online</b><br>
    <a href="tppmsgs/msgs0.htm#6" tppabs="http://www.masonbook.com/source/">Example Code</a><br>
    <a href="tppmsgs/msgs0.htm#7" tppabs="http://www.masonbook.com/authors.mhtml">Authors</a><br>
    <a href="tppmsgs/msgs0.htm#8" tppabs="http://www.masonbook.com/errata.mhtml">Errata</a><br>
    <a href="tppmsgs/msgs0.htm#9" tppabs="http://www.masonbook.com/quotes.mhtml">Praise</a><br>
    <a href="tppmsgs/msgs0.htm#10" tppabs="http://www.masonbook.com/contact.mhtml">Contact us</a><br>
    <a href="tppmsgs/msgs0.htm#11" tppabs="http://www.masonbook.com/buy.mhtml">Buy the book!</a>


    <h4 class="menu">There</h4>
    <a href="tppmsgs/msgs0.htm#12" tppabs="http://www.masonhq.com/">Mason HQ</a><br>
    <a href="tppmsgs/msgs0.htm#13" tppabs="http://www.oreilly.com/">O'Reilly</a><br>
    <a href="tppmsgs/msgs0.htm#14" tppabs="http://perl.apache.org/">mod_perl</a>
   </div>

<p class="book-menu">
<a href="index.mhtml.htm" tppabs="http://www.masonbook.com/book/index.mhtml">Table of Contents</a>
|
<a href="foreword.mhtml.htm" tppabs="http://www.masonbook.com/book/foreword.mhtml">Foreword</a>
|
<a href="preface.mhtml.htm" tppabs="http://www.masonbook.com/book/preface.mhtml">Preface</a>
<br>
Chapters: 
<a href="chapter-1.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-1.mhtml">1</a>
<a href="chapter-2.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-2.mhtml">2</a>
<a href="chapter-3.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-3.mhtml">3</a>
<a href="chapter-4.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-4.mhtml">4</a>
<a href="chapter-5.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-5.mhtml">5</a>
<a href="chapter-6.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-6.mhtml">6</a>
<a href="chapter-7.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-7.mhtml">7</a>
<a href="chapter-8.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-8.mhtml">8</a>
<a href="chapter-9.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-9.mhtml">9</a>
<a href="chapter-10.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-10.mhtml">10</a>
<a href="chapter-11.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-11.mhtml">11</a>
<a href="chapter-12.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-12.mhtml">12</a>
<br>
Appendices:
<a href="appendix-a.mhtml.htm" tppabs="http://www.masonbook.com/book/appendix-a.mhtml">A</a>
<a href="appendix-b.mhtml.htm" tppabs="http://www.masonbook.com/book/appendix-b.mhtml">B</a>
<b>C</b>
<a href="appendix-d.mhtml.htm" tppabs="http://www.masonbook.com/book/appendix-d.mhtml">D</a>
<br>
<a href="glossary.mhtml.htm" tppabs="http://www.masonbook.com/book/glossary.mhtml">Glossary</a>
|
<a href="colophon.mhtml.htm" tppabs="http://www.masonbook.com/book/colophon.mhtml">Colophon</a>
|
<a href="copyright.mhtml.htm" tppabs="http://www.masonbook.com/book/copyright.mhtml">Copyright</a>
</p>




<hr width="80%" align="left">

<a name="TOC-ANCHOR-0"></a>
<h1>Appendix C: Text Editors That Understand Mason</h1><p class="content">
<a name="APP-C"></a>

</p>
<p class="content">
In order to write Mason components, you don't need anything fancy. You can do
just fine with any old ramshackle <a name="perlhtmlmason-IDXTERM-1229"></a>
<a name="perlhtmlmason-IDXTERM-1230"></a>
<a name="perlhtmlmason-IDXTERM-1231"></a>
<a name="perlhtmlmason-IDXTERM-1232"></a>
<a name="perlhtmlmason-IDXTERM-1233"></a>
 text editor -- even (horrors!) a word processor that can save as plain text
will do.
</p>
<p class="content">
However, an editor that helps you manage the details of the document you're
creating can be a nice mini-luxury. Several different editors can easily be
trained to understand the structure of Mason components, with varying degrees
of assistance (or interference, depending on how much help you're looking for).
In most cases, this is due to the work of Mason developers who created syntax
definitions and offered them to the general public. If you find shortcomings,
the polite thing to do is to drop a note to the developer, offering a fix if
possible.
</p>
<a name="TOC-ANCHOR-1"></a>
<h2>Emacs</h2><p class="content">
<a name="APP-C-SECT-1"></a>

</p>
<p class="content">
Both authors of this book are enthusiastic users of <a name="perlhtmlmason-IDXTERM-1234"></a>
 Emacs and its wonderful cperl-mode for editing plain <a name="IXT-C-285"></a>
 Perl code, courtesy of Ilya <a name="IXT-C-286"></a>
 Zakharevich. However, while one can just turn cperl-mode on for an entire
Mason component and get some basic syntax highlighting, brace matching, and
indentation, the result is necessarily clumsy, since large parts of the
component aren't Perl code.
</p>
<p class="content">
Michael Abraham <a name="IXT-C-287"></a>
 Shulman, a Mason contributor from way back, developed a much nicer solution.
His Multiple-Major-Mode Mode (mmm-mode) is a way to combine cperl-mode and
html-mode (or sgml-mode, if you prefer), each in the correct region of the
component. Of course, like a true hubristic programmer, Michael addressed the
larger problem: mmm-mode is actually a framework for allowing several major
modes to coexist in a single buffer. Mason syntax definitions are provided, but
there are also definitions for embedding JavaScript in HTML documents,
embedding HTML code in Perl here-docs, embedding Perl in HTML using Embperl,
and more.
</p>
<p class="content">
Note that since this is a book on Mason and not a book on Emacs and Lisp, we're
just going to give you installation and configuration instructions as if they
were magical incantations. If you know alternate ways to achieve the same ends,
you'll probably be fine using them.
</p>
<p class="content">
To use mmm-mode's mason-mode, you'll need to download mmm-mode from <a href="tppmsgs/msgs0.htm#67" tppabs="http://mmm-mode.sourceforge.net/">http://mmm-mode.sourceforge.net/</a> and install the <u>.el</u> files as described in the <u>README</u> file.<sup><a href="#FOOTNOTE-ANCHOR-1">1</a></sup><a name="RETURN-ANCHOR-1"></a> Create a file called <u>.emacs</u> in your home directory if it doesn't already exist, and add the statement <code>(require 'mmm-auto)</code> to it. Then you can manually invoke mason-mode while editing a component by
first turning on html-mode (type <code>Meta-x</code><sup><a href="#FOOTNOTE-ANCHOR-2">2</a></sup><a name="RETURN-ANCHOR-2"></a><code> html-mode</code> and press Return) for the outer region, then turning on mason-mode for the
Mason sections (type <code>Meta-x</code><code>mmm-ify-by-class</code>, press Return, type <code>mason</code>, and press Return). mmm-mode will then scan your component to figure out which
sections are which, turning on cperl-mode in the sections that contain Perl
code.
</p>
<p class="content">
If you want mason-mode to start up automatically whenever you edit files with a
certain suffix, say <u>.mas</u>, you can add a few lines to your <u>.emacs</u> file after the <code>(require</code><code>'mmm-auto)</code> line, as in <a href="appendix-c.mhtml.htm#APP-C-EX-1" tppabs="http://www.masonbook.com/book/appendix-c.mhtml#APP-C-EX-1">Example C-1</a>.
</p>

<p class="content">
<a name="APP-C-EX-1"></a>
<div class="example">
<span class="caption">Example C-1.  mmm-mode
 configuration for Mason by extension</span>
<div class="example-code">
<pre>  (require 'mmm-auto)
  (setq mmm-global-mode 'maybe)
  (add-to-list 'auto-mode-alist '(&quot;\\.mas\\'&quot; . html-mode))
  (mmm-add-mode-ext-class 'html-mode &quot;\\.mas\\'&quot; 'mason)
</pre>
</div>
</div>

</p>
<p class="content">
Alternately, if you'd like to enable mmm-mode for all HTML files in a certain
directory, you could use the code in <a href="appendix-c.mhtml.htm#APP-C-EX-2" tppabs="http://www.masonbook.com/book/appendix-c.mhtml#APP-C-EX-2">Example C-2</a>.
</p>

<p class="content">
<a name="APP-C-EX-2"></a>
<div class="example">
<span class="caption">Example C-2.  mmm-mode
 configuration for Mason by directory</span>
<div class="example-code">
<pre>  (require 'mmm-auto)
  (setq mmm-global-mode 'maybe)
  (add-to-list 'auto-mode-alist '(&quot;/usr/local/apache/htdocs&quot; . sgml-mode))
  (mmm-add-mode-ext-class 'sgml-mode &quot;/usr/local/apache/htdocs&quot; 'mason)
</pre>
</div>
</div>

</p>
<p class="content">
As of this writing, mmm-mode doesn't scan your Mason component continually, so
if you type <code>&lt;&amp; &amp;&gt;</code> in your component, the inside of that tag won't be treated as a cperl-mode
region until you rescan the file. You can rescan by typing <code>Control-c %</code><code>Control-b</code>. If you know of a way to automatically keep the regions current while typing,
be sure to drop a line to Michael. His email address is in the mmm-mode <em>README</em> file.
</p>
<p class="content">
You can download  Emacs from several different places on the Internet, but the original
distribution is available at <a href="tppmsgs/msgs0.htm#68" tppabs="http://www.gnu.org/software/emacs/">http://www.gnu.org/software/emacs/</a>. Precompiled binaries for your system may also be available from other
sources, greatly simplifying the installation process if you're not using Unix.
</p>
<a name="TOC-ANCHOR-2"></a>
<h2>Vim</h2><p class="content">
<a name="APP-C-SECT-2"></a>

</p>
<p class="content">
Not to be outdone in the so-called editor wars, <a name="IXT-C-288"></a>
 Vim has some pretty slick Mason syntax highlighting of its own. Vim is a
widely used variant of the standard Unix editor <em>vi</em>. Vim stands for &quot;<em>vi</em> improved,&quot; and syntax highlighting is one of several major improvements
offered by Vim.
</p>
<p class="content">
The Mason syntax module is part of the standard distribution of Vim, so if you
have a fairly modern version of Vim (Version 6.0 or later should be fine), you
should already have all the necessary files. To invoke Mason highlighting while
you're editing a Mason component, you can enter the command <code>:set syntax=mason</code>. This will turn on Perl syntax for the Perl portions of the component and HTML
syntax for the other parts.
</p>
<p class="content">
If you want Mason syntax highlighting to start automatically when you edit
Mason components, you have a few options. First, Vim will automatically turn on
Mason highlighting when you begin editing a file that starts with the string <code>&lt;%args&gt;</code>. This is nice, because it both simplifies configuration and encourages you to
standardize the structure of your components.
</p>
<p class="content">
Another alternative is to configure Vim to invoke Mason highlighting when you
begin editing files ending with a certain suffix like <u>.mas</u>. To do this, you can add the following directives to your own <u>.vimrc</u> file (usually located in your home directory):
</p>
<div class="example-code">
<pre>  au syntax mason so /usr/local/share/vim/vim60ax/syntax/mason.vim
  au BufNewFile,BufRead *.mas set ft=mason</pre>
</div><p class="content">
Alternatively, you could edit Vim's <u>filetype.vim</u> file (usually located in <u>/usr/local/vim60/share/vim/vim60/</u>, though it depends on where Vim is installed on your system) to contain the
following line:
</p>
<div class="example-code">
<pre>  au BufNewFile,BufRead *.mas setf mason</pre>
</div><p class="content">
For more information on Vim configuration, consult the thorough Vim
documentation. If you add something significant to the Vim Mason support, be
sure to contact the maintainer of the Mason syntax file to see whether he'd be
interested in integrating your changes into the main  distribution.<sup><a href="#FOOTNOTE-ANCHOR-3">3</a></sup><a name="RETURN-ANCHOR-3"></a>
</p>

<h4>Footnotes</h4>
<a name="FOOTNOTE-ANCHOR-1"></a>
<p class="content">
1. Debian users can find an mmm-mode package in Woody and Sid. -- <a href="#RETURN-ANCHOR-1">Return</a>.
</p>
<a name="FOOTNOTE-ANCHOR-2"></a>
<p class="content">
2. If you don't know what the Meta key is, you can probably use your keyboard's
Escape key instead. -- <a href="#RETURN-ANCHOR-2">Return</a>.
</p>
<a name="FOOTNOTE-ANCHOR-3"></a>
<p class="content">
3. The maintainer is currently Andrew Smith, <a href="mailto:andrewdsmith@yahoo.com">andrewdsmith@yahoo.com</a>. -- <a href="#RETURN-ANCHOR-3">Return</a>.
</p>
<hr>
<p class="book-menu">
<a href="index.mhtml.htm" tppabs="http://www.masonbook.com/book/index.mhtml">Table of Contents</a>
|
<a href="foreword.mhtml.htm" tppabs="http://www.masonbook.com/book/foreword.mhtml">Foreword</a>
|
<a href="preface.mhtml.htm" tppabs="http://www.masonbook.com/book/preface.mhtml">Preface</a>
<br>
Chapters: 
<a href="chapter-1.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-1.mhtml">1</a>
<a href="chapter-2.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-2.mhtml">2</a>
<a href="chapter-3.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-3.mhtml">3</a>
<a href="chapter-4.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-4.mhtml">4</a>
<a href="chapter-5.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-5.mhtml">5</a>
<a href="chapter-6.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-6.mhtml">6</a>
<a href="chapter-7.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-7.mhtml">7</a>
<a href="chapter-8.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-8.mhtml">8</a>
<a href="chapter-9.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-9.mhtml">9</a>
<a href="chapter-10.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-10.mhtml">10</a>
<a href="chapter-11.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-11.mhtml">11</a>
<a href="chapter-12.mhtml.htm" tppabs="http://www.masonbook.com/book/chapter-12.mhtml">12</a>
<br>
Appendices:
<a href="appendix-a.mhtml.htm" tppabs="http://www.masonbook.com/book/appendix-a.mhtml">A</a>
<a href="appendix-b.mhtml.htm" tppabs="http://www.masonbook.com/book/appendix-b.mhtml">B</a>
<b>C</b>
<a href="appendix-d.mhtml.htm" tppabs="http://www.masonbook.com/book/appendix-d.mhtml">D</a>
<br>
<a href="glossary.mhtml.htm" tppabs="http://www.masonbook.com/book/glossary.mhtml">Glossary</a>
|
<a href="colophon.mhtml.htm" tppabs="http://www.masonbook.com/book/colophon.mhtml">Colophon</a>
|
<a href="copyright.mhtml.htm" tppabs="http://www.masonbook.com/book/copyright.mhtml">Copyright</a>
</p>

<p>
These HTML pages were created by running <a
href="book_as_html" tppabs="http://www.masonbook.com/book/book_as_html">this script</a> against the <a
href="mason-book.tar.gz" tppabs="http://www.masonbook.com/book/mason-book.tar.gz">pseudo-POD source</a>.
</p>





  </div>

 </div>

</div>

</body>
</html>
