"Fossies" - the Fresh Open Source Software Archive

Member "xemacs-packages/lisp/mmm-mode/README.Mason" (22 Dec 2008, 5299 Bytes) of archive /linux/misc/xemacs-sumo-2010-07-27.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 -*-text-*-
    2                 Using MMM Mode for Mason: An Overview
    3                 =====================================
    4 
    5   Since many users of MMM Mode use it for Mason <www.masonhq.com>, and
    6   since the Mason submode class is the most complex one supplied, a
    7   few comments regarding its usage are in order.  Even if you don't
    8   use Mason, this file may be of interest to you as an example of MMM
    9   usage and possible problems.
   10 
   11 INSTALLATION AND LOADING
   12 
   13   For general installation and information, see the README file and
   14   the texinfo documentation.  The submode class for Mason components
   15   is called `mason' and is automatically loaded from `mmm-mason.el'
   16   the first time it is used.
   17 
   18 MODES AND EXTENSIONS
   19 
   20   If you want to have mason submodes automatically in all Mason files,
   21   you can use `mmm-mode-ext-classes-alist'; the details depend on what
   22   you call your Mason components and what major mode you use.  Some
   23   example elements of `mmm-mode-ext-classes-alist' follow, with
   24   comments on the corresponding naming scheme.
   25 
   26   (html-mode "\\.html\\'" mason)         ;; Any .html file in html-mode
   27   (hm--html-mode nil mason)              ;; Any buffer in hm--html-mode
   28   (sgml-mode nil mason)                  ;; Any buffer in sgml-mode
   29   (nil "\\.\\(mason\\|html\\)\\'" mason) ;; All .mason and .html files
   30   (nil "\\.m[dc]\\'" mason)              ;; All .md and .mc files
   31   (nil "\\`/var/www/mason/" mason)       ;; Any file in the directory
   32   (nil nil mason)                        ;; All buffers.
   33 
   34   In order for any of these to work, you must set `mmm-global-mode' to
   35   a non-nil value, such as `t' or `maybe' (the two of which mean
   36   different things; see the documentation).  This can be done with a
   37   line in .emacs such as the following:
   38 
   39   (setq mmm-global-mode 'maybe)
   40 
   41   If you use an extension for your Mason files that emacs does not
   42   automatically place in your preferred HTML Mode (be it html-mode,
   43   sgml-html-mode, hm--html-mode, or whatever), you will probably want
   44   to associate that extension with your HTML Mode (this is a feature
   45   of emacs, not MMM Mode).  An example is shown below.
   46 
   47   (add-to-list 'auto-mode-alist '("\\.mason\\'" . html-mode))
   48 
   49   This also goes for "special" Mason files such as autohandlers and
   50   dhandlers.  The code below tells emacs to use html-mode for files
   51   named `autohandler' and `dhandler'.
   52 
   53   (add-to-list 'auto-mode-alist '("\\(auto\\|d\\)handler\\'" . html-mode))
   54 
   55   An alternate solution is to change the names of your autohandlers
   56   and dhandlers so that emacs recognizes them as HTML automatically.
   57   Similar code can be used to recognize all files in a given directory
   58   as HTML and/or Mason.
   59 
   60 CPERL PROBLEMS
   61 
   62   There are certain problems with CPerl mode in submode regions.  (Not
   63   to say that the original perl-mode would do any better--it hasn't
   64   been much tried.)  First of all, the first line of a Perl section
   65   is usually indented as if it were a continuation line.  A fix for
   66   this is to start with a semicolon on the first line.  The insertion
   67   key commands do this whenever the Mason syntax allows it.
   68 
   69   <%perl>;
   70   print $var;
   71   </%perl>
   72 
   73   In addition, some users have reported that the CPerl indentation
   74   sometimes does not work.  This problem has not yet been tracked
   75   down, however, and more data about when it happens would be helpful.
   76 
   77 PSGML PROBLEMS
   78 
   79   Some people have reported problems using PSGML with Mason.  Adding
   80   the following line to a .emacs file should suffice to turn PSGML off
   81   and cause emacs to use a simpler HTML mode:
   82 
   83   (autoload 'html-mode "sgml-mode" "HTML Mode" t)
   84 
   85   Earlier versions of PSGML may require instead the following fix:
   86 
   87   (delete '("\\.html$" . sgml-html-mode) auto-mode-alist)
   88   (delete '("\\.shtml$" . sgml-html-mode) auto-mode-alist)
   89 
   90   Other users report using PSGML with Mason and MMM Mode without
   91   difficulty.  If you don't have problems and want to use PSGML, you
   92   may need to replace `html-mode' in the suggested code with
   93   `sgml-html-mode'.  (Depending on your version of PSGML, this may not
   94   be necessary.)  Similarly, if you are using XEmacs and want to use
   95   the alternate HTML mode `hm--html-mode', replace `html-mode' with
   96   that symbol.
   97 
   98   One problem that crops up when using PSGML with Mason is that even
   99   ignoring the special tags and Perl code (which, as I've said,
  100   haven't caused me any problems), Mason components often are not a
  101   complete SGML document.  For instance, my autohandlers often say
  102 
  103   <body>
  104     <% $m->call_next %>
  105   </body>
  106 
  107   in which case the actual components contain no doctype declaration,
  108   <html>, <head>, or <body>, confusing PSGML.  One solution I've found
  109   is to use the variable `sgml-parent-document' in such incomplete
  110   components; try, for example, these lines at the end of a component.
  111 
  112   %# Local Variables:
  113   %# sgml-parent-document: ("autohandler" "body" nil ("body"))
  114   %# sgml-doctype: "/top/level/autohandler"
  115   %# End:
  116 
  117   This tells PSGML that the current file is a sub-document of the file
  118   `autohandler' and is included inside a <body> tag, thus alleviating
  119   its confusion, and also instructs it where to find the doctype
  120   declaration (assuming your top-level autohandler has one).  This
  121   alleviates most problems for me.  I admit to not understanding PSGML
  122   internals very well, so YMMV.