emacs/nxhtml/nxhtml/doc/nxhtml.html

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   3 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   4 <html xmlns="http://www.w3.org/1999/xhtml">
   5   <head>
   6     <title>nXhtml - an Emacs mode for Web Development</title>
   7     <link href="wd/grapes/nxhtml-grapes.css" rel="StyleSheet" type="text/css" />
   8     <style type="text/css">
   9       #special {
  10           background-color: red;
  11       }
  12     </style>
  13 <style type="text/css">
  14
  15
  16 #getit {
  17     max-width: 800px;
  18 }
  19
  20 #getit span { display: none; }
  21 /* This seems to be impossible with CSS2 since the containing block
  22    can not be floated. Why did they design it that way?
  23 #getit, #getit dl { display: block; }
  24 #getit a:hover span {
  25     display: block;
  26     position: absolute;
  27     left: 200;
  28     top: 0;
  29 }
  30 */
  31
  32 #getit a {
  33     /* Image */
  34     display: block;
  35     background: transparent url("img/getitbuttons.png") 0 0 no-repeat;
  36     overflow: hidden;
  37     width: 200px;
  38     /* Text placement and size, etc */
  39     text-align: center;
  40     padding-top: 11px;
  41     font-size: 12px;
  42     font-weight: 600;
  43     padding-bottom: 9px;
  44     text-decoration: none;
  45     white-space: nowrap;
  46     border: none;
  47 }
  48 #getit dt {
  49     display: block;
  50     padding: 0;
  51     margin: 0;
  52     float: left;
  53     letter-spacing: 0;
  54 }
  55 #getit a:hover {
  56     background-position: 0 -35px;
  57     color: yellow;
  58 }
  59
  60 #useit {
  61     position: absolute;
  62     top: 150px;
  63     left: 100px;
  64     width: 85px;
  65     z-index: 100;
  66     border: none;
  67     font-size: 9px;
  68 }
  69 /* I can't get rid of the underline. Firefox bug or my bug? */
  70 #useit a { text-decoration: none; }
  71 #useit img {
  72     text-decoration: none;
  73     overflow: hidden;
  74     border: solid 2px #990033;
  75 }
  76 div#useit { text-decoration: none; }
  77 #useit img:hover {
  78     background: url("img/use-nXhtml-trans2.png") 0 0 no-repeat;
  79 }
  80
  81 #quicklnk a {
  82     color: #cd3700;
  83     font-weight: bold;
  84     font-size: 1.2em;
  85 }
  86 #quicklnk a:hover {
  87     background-color: yellow;
  88 }
  89
  90 </style>
  91   </head>
  92   <body>
  93       <div id="useit">
  94         <!-- title is for Firefox -->
  95         <a href="http://ourcomments.org/Emacs/nXhtml/doc/nxhtml.html"
  96            title="Get nXhtml for Emacs"
  97            ><img alt="Get nXhtml for Emacs" src="img/use-nXhtml-trans2.png" width="78" height="29" /></a>
  98         Above is a little banner you can put on your site if you want to.
  99       </div>
 100
 101     <div id="container">
 102       <div id="hdr">
 103         <br />
 104         <span style="color:#FF0;font-size:14px; font-weight: 600;"> <i>&nbsp;Enjoying editing web files!</i> </span>
 105         <br />
 106       </div>
 107
 108       <div id="lftcol">
 109         <!-- Table of contents BEGIN -->
 110         <!-- Table of contents min=2 max=3 -->
 111         <table id="PAGETOC"><tr><td>
 112           <span class="tochead">On THIS Page:</span>
 113           <ul>
 114             <li><a href="#summary">Introduction to nXhtml</a></li>
 115             <li class="liul"><ul>
 116               <li><a href="#featsum">Features</a></li>
 117               <li><a href="#qg">The Quick Guide</a></li>
 118               <li><a href="#toolset">What you may use more</a></li>
 119             </ul></li>
 120             <li><a href="#completion">Completion</a></li>
 121             <li class="liul"><ul>
 122               <li><a href="#complex-compl">More Helpful Completion</a></li>
 123               <li><a href="#ask-compl">But How Do I Ask nXhtml for Alternatives?</a></li>
 124               <li><a href="#region-compl">The Region and Completion</a></li>
 125               <li><a href="#errors">And if I Do Not Follow the Advices?</a></li>
 126             </ul></li>
 127             <li><a href="#xmlpath">Where am I? - XML Path</a></li>
 128             <li><a href="#sites">Why it is Useful that nXhtml has Sites</a></li>
 129             <li><a href="#mlinks">Why the Links Look Like Links</a></li>
 130             <li><a href="#tocs">Did You Notice the Table of Contents at the Top?</a></li>
 131             <li><a href="#tidy">But I Can't Use this Cause my Files are HTML</a></li>
 132             <li><a href="#php">And what about Multiple Modes like PHP?</a></li>
 133             <li class="liul"><ul>
 134               <li><a href="#dtd-needed">But I Have no DTD Links in my PHP Files?</a></li>
 135               <li><a href="#multi-colors">Why Are Colors Different in Multiple Modes?</a></li>
 136               <li><a href="#part2">More Multiple Modes</a></li>
 137               <li><a href="#tips-multi">Tips When Using Multiple Modes</a></li>
 138             </ul></li>
 139             <li><a href="#file-assoc">File Associations within Emacs</a></li>
 140             <li><a href="#bloggin">Not for Me, I Am Only Blogging</a></li>
 141             <li><a href="#bloggin">And Other Goodies...</a></li>
 142           </ul>
 143         </td></tr></table>
 144         <!-- END of Table of contents -->
 145       </div>
 146
 147       <div id="getit">
 148         <dl>
 149           <dt>
 150             <a href="http://ourcomments.org/Emacs/nXhtml/tut/tutorials.html" title="Tutorials">Tutorials</a>
 151           </dt>
 152           <dt>
 153             <a href="https://answers.launchpad.net/nxhtml/+faqs" title="nXhtml FAQ">nXhtml FAQ</a>
 154           </dt>
 155           <dt>
 156             <a href="nxhtml-changes.html">News about nXhtml
 157             <span>Details</span></a>
 158           </dt>
 159           <dt>
 160             <a href="http://www.emacswiki.org/cgi-bin/wiki/NxhtmlMode"
 161                >nXhtml page at EmacsWiki</a>
 162           </dt>
 163           <dt>
 164             <a id="download" href="http://ourcomments.org/cgi-bin/emacsw32-dl-latest.pl">Download nXhtml</a>
 165           </dt>
 166           <dt>
 167             <a href="https://launchpad.net/nxhtml" title="Bazaar repository">nXhtml at Launchpad</a>
 168           </dt>
 169         </dl>
 170       </div>
 171
 172       <div id="rgtcol">
 173         <h1 id="mainheader">nXhtml - Emacs Utilities for Web Development</h1>
 174
 175         <h2 id="summary">Introduction to nXhtml</h2>
 176         <p>
 177           nXhtml is an addon to Emacs for editing XHTML, PHP and similar things.  It is not
 178           very well-known, but it looks like at least <a
 179           href="http://drewyates.net/nxml-nxhmtl-emacs-mode-for-ruby-on-rails-rhtml">Drew
 180           Yates</a> has found it useful:
 181         </p>
 182         <blockquote>
 183           <p style="font-style:italic">
 184             nXML mode and the subsequent nXHTML mode for emacs are godsends ...
 185           </p>
 186         </blockquote>
 187         <p>
 188           And that was before I fixed all the bugs ...
 189         </p>
 190
 191         <h3 id="featsum">Features</h3>
 192         <p>
 193           One of the main parts of nXhtml is nxhtml-mode, a GNU <a
 194           href="http://en.wikipedia.org/wiki/Emacs">Emacs</a> major
 195           mode that builds on <a
 196           href="http://www.thaiopensource.com/nxml-mode/">nxml-mode</a>.
 197           It knows about XHTML syntax and can check this as
 198           you type.  It can also tell you what tags and attributes you
 199           can use at a certain point and help you insert them.
 200         </p>
 201         <p>
 202           That feature, which we call <a
 203           href="#completion">completion</a>, is one of the main
 204           features of this mode.  Another important feature is the
 205           ability to mix several languages in one buffer and get the
 206           correct syntax highlighting and indentation for each of
 207           them.
 208         </p>
 209         <p>
 210           In nXhtml this is combined with other features to make it
 211           more easy to edit web sites (mostly XHTML based but there is
 212           support for things like PHP too).  Here is a list of important features:
 213         </p>
 214         <ul id="sum-ul">
 215           <li>
 216             Completion and syntax checking for XHTML.
 217             <ul>
 218               <li> Some helpful extensions when completing certain tags (like the &lt;a ...> tag for example).</li>
 219               <li> When region is visible tag completion will surround the region with the start tag and end tag.</li>
 220             </ul>
 221           </li>
 222           <li>
 223             Multiple major modes, which means it can handle for example PHP, JSP, eRuby and Django while allowing XHTML completion.
 224             (Notice however that not all major modes you may need for this comes with nXhtml.)
 225           </li>
 226           <li>
 227             Link handling:
 228             <ul>
 229               <li> Easier insertion of tags with links.</li>
 230               <li> Following links to edit or view.</li>
 231               <li> Moving between links.</li>
 232               <li> Moving files and automatically update affected links.</li>
 233               <li> Copy link to id location and paste it back as a relative link.</li>
 234               <li> Link checking in current site (local links only)</li>
 235             </ul>
 236           </li>
 237           <li>
 238             The concept of a site. This is used in many places.  A
 239             site is here a directory tree with additional properties, like
 240             remote ftp and http addresses.  A directory could belong to
 241             many sites.
 242           </li>
 243           <li>
 244             Make a remote copy of site:
 245             <ul>
 246               <li> Uploading of single files</li>
 247               <li> Uploading of whole or part of site</li>
 248               <li> Editing of remote files.</li>
 249               <li> Ediff of local vs remote file.</li>
 250               <li> Easy viewing of local and remote files in web browser.</li>
 251             </ul>
 252           </li>
 253           <li>
 254             Table of contents
 255             <ul>
 256               <li>Creating table of contents for a page.</li>
 257               <li>Creating table of contents for a site.</li>
 258               <li>
 259                 Merging of pages and table of contents for a site (see
 260                 example, notice that the table of content easily can be
 261                 navigated using the keyboard).
 262               </li>
 263             </ul>
 264           </li>
 265           <li> Support for folding.</li>
 266           <li> Using <a href="http://www.w3.org/People/Raggett/tidy/">Tidy</a> to convert HTML to XHTML.</li>
 267           <li> Help for XHTML tags and CSS attributes.</li>
 268           <li> Edit a fragment of an XHTML file (for blogging for example).</li>
 269           <li> ... and more of course ...</li>
 270           <!-- <li> Adding a popup menu to [apps] to access these features.</li> -->
 271         </ul>
 272
 273         <h3 id="qg">The Quick Guide</h3>
 274         <p>
 275           Below are some short notes to get you started using nXhtml.
 276           (Maybe you should start by taking a look at the
 277           <a href="http://ourcomments.org/Emacs/nXhtml/tut/tutorials.html" title="Tutorials">Tutorials</a>?)
 278         </p>
 279         <dl>
 280           <dt>GNU Emacs 22 or later</dt>
 281           <dd>
 282             <p>
 283             You need GNU Emacs 22 (which was released 2007-06-02) or later.
 284             </p>
 285           </dd>
 286           <dt>Installation</dt>
 287           <dd>
 288             <ul>
 289               <li>
 290                 Download nXhtml as a zip file <a href="http://ourcomments.org/cgi-bin/emacsw32-dl-latest.pl">here</a>
 291                 or download
 292                 <a href="http://ourcomments.org/Emacs/EmacsW32.html">EmacsW32</a>.
 293               </li>
 294               <li>
 295                 If you got nXhtml with <a
 296                 href="http://ourcomments.org/Emacs/EmacsW32.html">EmacsW32</a>
 297                 you should use the menus <em>Options - Customize
 298                 EmacsW32</em> and there just set <em>nxhtml-load</em>.
 299               </li>
 300               <li>
 301                 If you downloaded the zip file with nXhtml then unzip it anywhere and
 302                 then follow the instructions in
 303                 <em>nxhtml/README.txt</em>.
 304               </li>
 305             </ul>
 306             <p>
 307               After this files with extensions for example .html will open in nxhtml-mode.
 308             </p>
 309             <p>
 310               To make nXhtml run faster you can also byte compile the files.
 311               You do that with <i>M-x nxhtmlmaint-start-byte-compilation</i>.
 312             </p>
 313           </dd>
 314
 315           <dt id="nxhtml-menu">The nXhtml Menu</dt>
 316           <dd>
 317             <p>
 318               To reach many of the features in nXhtml you can use the
 319               <b>nXhtml menu</b>.  If you do not see that when in a buffer
 320               then you can always do <em>M-x nxhtml-minor-mode</em> which
 321               will turn it on (or off) for that buffer.
 322             </p>
 323             <p>
 324               But please notice also the <b>XML menu</b> which
 325               contains the nXml menu! (Remember that nXhtml is based
 326               on nXml.) When you are using nxhtml-mode this menu is
 327               visible when you are in the XHTML parts of a buffer.
 328             </p>
 329           </dd>
 330
 331           <!-- <dt id="turn-on-some">Turn on Some Things</dt> -->
 332           <!-- <dd> -->
 333           <!--   <p> -->
 334           <!--     There is a good chance that you want to turn on some -->
 335           <!--     things that makes nXhtml work more automatic. They are -->
 336           <!--     in the <a href="#nxhtml-menu">nXhtml menu</a> for -->
 337           <!--     turning them on temporarily.  Later, when you have -->
 338           <!--     tested, you may want to turn them on permanently, which -->
 339           <!--     you can do from the menus by choosing <em>nXhtml - -->
 340           <!--     nXhtml Help and Setup - Quick Customize nXhtml</em>. -->
 341           <!--   </p> -->
 342           <!-- </dd> -->
 343
 344           <dt>XHTML Completion and Validation</dt>
 345           <dd>
 346             <p>
 347               nXhtml knows a good deal about XHTML tags and attributes when you are using <em>nxhtml-mode</em>.
 348               It can assist you in different ways:
 349             </p>
 350             <ul>
 351               <li>
 352                 Completion
 353               </li>
 354               <li>
 355                 Validation
 356               </li>
 357             </ul>
 358             <p>
 359               <b>Completion</b> means that you ask Emacs to give you choices to complete what you are currently writing.
 360               For example you may have written &lt;b and want to know what tags beginning this way can actually be used at that place in the document.
 361               You ask Emacs in nxhtml-mode this by calling the function nxml-complete.
 362               This is normally bound to M-Tab.
 363             </p>
 364             <p>
 365               On some systems, for example MS Windows with an
 366               unpatched Emacs this is inconvenient and clashes with
 367               Alt-Tab that the window manager uses. There is however a
 368               little utility that comes with nXhtml that let you use
 369               just Tab for completion, <i>tabkey2-mode</i>. Turn this on with
 370             </p>
 371             <p style="padding-left:2em;">
 372               M-x tabkey2-mode
 373             </p>
 374             <p>
 375               After this the first Tab press will still do
 376               indentation, but the second can do completion.
 377             </p>
 378             <p>
 379               <b>Validation</b> means checking that what you have
 380               written in nxhtml-mode follows the XHTML specifications.
 381               If it does not there will be a red underline at the
 382               places where something is wrong.  To see what is wrong
 383               move to this (for example with C-c C-n). A message in
 384               the minibuffer will tell you the error.
 385             </p>
 386             <p>
 387               Notice that the modeline also tells if the document is
 388               valid. Most of the times it will however say
 389               <em>Invalid</em> maybe just because you are editing and have
 390               not yet finished.
 391             </p>
 392             <p>
 393               For files mixing XHTML with codes, like PHP, you can use
 394               something I call <a href="#dtd-needed">Fictive XHTML
 395               Validation Headers</a>.  That allows you to use XHTML
 396               completion even if those files does not have the XHTML
 397               headers needed.
 398             </p>
 399           </dd>
 400           <dt>Multiple Major Modes</dt>
 401           <dd>
 402             <p>
 403               nXhtml can automatically divide the buffer into chunks
 404               with relevant different major modes (i e languages, like
 405               PHP, XHTML etc). This is useful for editing PHP,
 406               JSP, eRuby, Django and similar. See <a href="#php">And
 407               what about Multiple Modes like PHP?</a> for more information.
 408             </p>
 409           </dd>
 410           <dt>Links</dt>
 411           <dd>
 412             <p>
 413               The links you put in your XHTML documents actually works
 414               like links with nxhtml-mode too. To follow a link you
 415               can use <em>C-c RET RET</em>.  (There are other
 416               possibilities too, they all begin with <em>C-c RET</em>.)
 417             </p>
 418           </dd>
 419           <dt>Sites and Uploading</dt>
 420           <dd>
 421             <p>
 422               If you want to upload your XHTML files, image files etc
 423               you can do that from within Emacs.  There are entries
 424               for this in the <a href="#nxhtml-menu">nXhtml menu</a>.
 425             </p>
 426           </dd>
 427           <dt>Keyboard shortcuts (aka keybindings in Emacs)</dt>
 428           <dd>
 429             <p>
 430               When you start to use a new program you often wonder
 431               about which keybindings there are to use.  If you have
 432               not used Emacs before you may feel quite lost because
 433               you have looked in all documentation and you have not
 434               seen any list of keybindings.
 435             </p>
 436             <p>
 437               Well, that is how it often is in Emacs. Get use to it ...
 438             </p>
 439             <p>
 440               But do not panic. Because there is help, probably even
 441               better than you are used to - in Emacs dynamic help
 442               system. A help system that change if you for example add
 443               a keybinding yourself.  Try the command <i>C-h b</i> (or <i>F1
 444               b</i>). This list all the keybindings (in their priority
 445               order) that are active where you are in Emacs.
 446             </p>
 447             <p>
 448               You can also try <i>C-h m</i> which gives information about
 449               minor modes and the current major mode. There is
 450               sometimes information about the keybindings there too.
 451             </p>
 452           </dd>
 453           <dt>Some More You Can Do ...</dt>
 454           <dd>
 455             <p>
 456               See <a href="#summary">Introduction</a> above.
 457               Look into the <a href="#nxhtml-menu">nXhtml menu</a>.
 458               And then of course learn some of all the things you can do using the power of Emacs.
 459             </p>
 460           </dd>
 461         </dl>
 462         <p>
 463         </p>
 464         <h3 id="toolset">What you may use more</h3>
 465         <p>
 466           If find it very conventient to combine nXhtml with Firefox
 467           add-on Firebug. I think Firebug is very handy for finding CSS
 468           problem.
 469         </p>
 470         <p>
 471           <a href="http://www.spreadfirefox.com/node&id=0&t=306"><img border="0"
 472           alt="Firefox 3" title="Firefox 3"
 473           src="http://sfx-images.mozilla.org/affiliates/Buttons/firefox3/110x32_get_ffx.png"/></a>
 474
 475           <a href="http://www.getfirebug.com/?link=2" title="Firebug
 476           is a free web development tool for
 477           Firefox"><img src="http://www.getfirebug.com/images/firebug2.png"
 478           border="0" alt="Firebug - Web Development Evolved"/></a>
 479         </p>
 480         <p>
 481           And of course, another good resource is Russ Weakley's <a
 482           href="http://css.maxdesign.com.au/">CSS-based tutorials</a>.
 483           Russ co-chairs the <a
 484           href="http://webstandardsgroup.org/">Web Standards Group</a>
 485           and seems to know this well.
 486         </p>
 487         <p>
 488           I am sure you know about it, but just in case, here is WDG's
 489           <a href="http://htmlhelp.com/design/accessibility/">Guide to Accessibility</a>
 490           and their
 491           <a href="http://htmlhelp.com/design/accessibility/tips.html">Accessibility Tips</a>.
 492         </p>
 493
 494         <h2 id="completion">Completion</h2>
 495         <div align="right">
 496           <img align="right"
 497                src="img/popup-compl.png"
 498                alt="Popup menu style completion"
 499                title="Popup menu style completion"
 500                style="border: thin dotted #00ff00;
 501                       margin-left: 2em;
 502                       margin-top: 0em;
 503                       margin-bottom: 1em;"
 504                width="371" height="483" />
 505         </div>
 506         <p>
 507           Completion in nXhtml Mode lets you ask Emacs <i>"What can I
 508           type here?"</i>.  The most important part, the content, can
 509           Emacs not help you with yet.  However when it comes to XHTML and
 510           such things that you really want to get past as easy as
 511           possible, then nXhtml mode can assist you.
 512         </p>
 513         <p>
 514           Perhaps you wonder with <i>"With what?"</i> Well, completion
 515           works like this: You position point in your XHML file where you
 516           want to write.  Now you ask nXhtml what XHTML code you can
 517           write there.  nXhtml may answer that it can't help you, that
 518           happens in some cases.
 519         </p>
 520         <p>
 521           But most often nXhtml can help you. It knows about tags and
 522           where they fit, and it knows about tag attributes.  When nXhtml
 523           can helpt you it will give you choices you can select from.  It
 524           may display the choices in a popup menu like in the pictures to
 525           the left, or it may use something like the picture below shows.
 526           It is actually exactly the same question that is asked in these
 527           two cases.  You decide by <i>customizing</i> nXhtml mode in Emacs which
 528           way it should display the choices.  The way below is the
 529           standard Emacs way to do display choices.  It is fast once you know it, but
 530           the popup menus are of course more familiar to computer users
 531           today.
 532         </p>
 533         <img alt="Emacs style completion" src="img/emacs-style-completion.png" width="456" height="406"
 534              />
 535         <p>
 536           That far nXhtml can take you because it knows the DTD for XHTML.
 537           (You may wonder about different versions of XHTML, more about that later.)
 538         </p>
 539
 540         <h3 id="complex-compl">More Helpful Completion</h3>
 541         <p>
 542           For certain attributes nXhtml knows their values because the DTD just allows certain values.
 543           For some other attribute values for which nXhtml can know little
 544           from the DTD alone, like links (src and href attributes) nXhtml
 545           can also be helpful.  If you want a link to a file, for example,
 546           nXhtml lets you browse for the file and then inserts a relative
 547           link to it. It can also look for anchors (ie <b>id</b> attributes).
 548         </p>
 549         <p>
 550           In some cases nXhtml knows more about a tag.
 551           From the DTD it knows that an <b>&lt;img></b> tag should have a <b>src</b> attribute with a value that points to an image.
 552           Therefor it prompts you for the value of the src attribute.
 553           It is the same with the <b>alt</b> attribute that is required.
 554           It even gets the height and width of an image on file if it can and inserts the attributes in the &lt;img> tag.
 555         </p>
 556         <p>
 557           Well, it is better that you test (and perhaps give some feedback?).
 558         </p>
 559         <p>
 560           Normally nXhtml does not care that much. It just tells you that
 561           you when you have broken the DTD rules.  If however you want
 562           nXhtml to do less or more of this kind then you can change the
 563           variable <b>nxhtml-complete-tag-do-also</b> - but that requires
 564           that you knows Emacs lisp.  If you do write something useful for
 565           this, please tell me.
 566         </p>
 567
 568         <h3 id="ask-compl">But How Do I Ask nXhtml for Alternatives?</h3>
 569         <p>
 570           Oh, I nearly forgot. Do you wonder how to ask nXhtml in Emacs for completion alternatives?
 571           That is a nice question to answer.
 572           You give a certain command to Emacs to ask for this.
 573           That can be done by either:
 574         </p>
 575         <ul>
 576           <li>Type <i>M-Tab</i></li>
 577           <li>Do it from the <a href="#nxhtml-menu">nXhtml menu</a>: <i>nXhtml - Completion - Complete tag, attributes etc</i></li>
 578           <li>Or more explicit with a command: <i>M-x nxml-complete</i></li>
 579         </ul>
 580         <p>
 581           You can change <i>M-Tab</i> to whatever you want.  What it
 582           means? Ah, yes, it means <i>"hold down the Meta key and press
 583           Tab"</i>.  That is Emacs jargon and you have to know which key
 584           is the Meta key of course.  I actually use the left Windows key
 585           on my keyboard for Meta.  See <a
 586           href="http://ourcomments.org/Emacs/EmacsW32.html">EmacsW32 home
 587           page</a> for some information about this if you are on MS
 588           Windows.
 589         </p>
 590
 591         <h3 id="region-compl">The Region and Completion</h3>
 592         <p>
 593           This is a small but useful thing (and I added it because some people liked it, it
 594           was not my own idea): If some text is selected (in Emacs jargon
 595           "if region is active and hilighted") and you use completion to
 596           insert a tag then the <em>region will be surrounded by that tag</em>.
 597           If region is active like here:
 598         </p>
 599         <img alt="Region is selected" src="img/region-selected.png" width="584" height="50"
 600              style="border: thin dotted #00ff00;
 601                     vertical-align: top;
 602                     margin-bottom: 1em;" />
 603         <p>
 604           And you then ask for completion:
 605         </p>
 606         <img alt="Ask for tag" src="img/region-selected-completion.png" width="584" height="393"
 607              style="border: thin dotted #00ff00;
 608                     vertical-align: top;
 609                     margin-bottom: 1em;" />
 610         <p>
 611           The result will be that your choice (<em>em</em> here) will surround the region you had selected:
 612         </p>
 613         <img alt="After completion" src="img/region-selected-after.png" width="584" height="61"
 614              style="border: thin dotted #00ff00;
 615                         vertical-align: top;
 616                         margin-bottom: 1em;" />
 617         <p>
 618           Eh? Ah, yes, you are right. I happened to choose the wrong picture for the result. Sorry.
 619         </p>
 620
 621         <h3 id="errors">And if I Do Not Follow the Advices?</h3>
 622         <p>
 623           nXhtml gives you advices about how to handle the XHTML tags, but
 624           it does not force you to follow them.  You can write whatever
 625           you want, but nXhtml anyway observes what you are doing and
 626           checks the XHTML code.  If you do not follow the DTD rules
 627           nXhtml will silently warn you with a red underline, like here
 628           (where I have written <i>image</i> instead of <i>img</i>):
 629         </p>
 630         <img alt="Validation error marking" src="img/validation-error.png" width="375" height="50"
 631              style="border: thin dotted #00ff00;"
 632              />
 633         <p>
 634           (Oh, geeh. Firefox took that before, but not now ...)
 635         </p>
 636
 637         <h2 id="xmlpath" style="clear:both">Where am I? - XML Path</h2>
 638
 639         <p>
 640           If you have for example &lt;div> tags to separate things or long
 641           list you may wonder in which of those you are.  Nxml Mode can
 642           show this. Look in the menus <i>XHTML - XML Path</i> to turn it
 643           on. Here is what it looks like. There is header with the label <i>Path:</i> which here shows that we are in a list with id="sum-ul".
 644           Note also the yellow color of the tag we are in. The whole path up to the top is colored this way.
 645         </p>
 646         <img alt="Showing XML Path" src="img/nxml-where.png" width="456" height="262" />
 647         <p>
 648           A little tip: I found this very useful when I looked at different CSS designs.
 649         </p>
 650
 651         <h2 id="sites">Why it is Useful that nXhtml has Sites</h2>
 652         <p>
 653           I am writing this in nXhtml mode in Emacs.  Just after I had
 654           written a piece or added an image on my pc I update the web
 655           pages on http://OurComments.org/.  I do that very easily because
 656           of the concept of a site.
 657         </p>
 658         <p>
 659           A <b>site in nXhtml</b> is in its simplest form just a local directory tree.
 660           And that is given a name.
 661           In my case I have given it the name <i>nxhtml-doc</i> just to remember what it is about.
 662         </p>
 663         <p>
 664           To that site I have also added information about uploading and
 665           and the http address of the uploaded files.  Now if I add an
 666           image to the site on my pc all I have to do to upload it to the
 667           web site is to open the image in Emacs (yes that is possible,
 668           Emacs knows about the most common image formats) and then just from the menus choose
 669           <i>Web Site - File Transfer - Upload Single File</i>.
 670           That is all.
 671         </p>
 672         <p>
 673           And then I can (from the XHTML file I am editing) use the
 674           command <i>XHTML - File Transfer - View Uploaded File</i> to
 675           check that the web page is ok.
 676         </p>
 677
 678         <h2 id="mlinks">Why the Links Look Like Links</h2>
 679         <p>
 680           As soon as you open an XHTML file in nXhtml mode you will notice that the links you enter looks like links.
 681           They are underlined and blue like in a web browser.
 682           You may think that that is kind of nice, but why do they look like that?
 683         </p>
 684         <p>
 685           It is just because they are links.  You access them a little bit
 686           different in a web browser, just so that it does not interfere
 687           with editing.  And because you may want to do different things
 688           with them.  Take a look at the picture below.  I have positioned
 689           point to a link and then pressed tha App key on my keyboard.
 690           That pops up a menu where I can see what I can do with the link:
 691         </p>
 692         <img alt="Link with popup menu" src="img/links-appmenu.png" width="529" height="189"
 693              style="border: thin dotted #00ff00;"
 694              />
 695         <p>
 696           As you can see I can copy the link (maybe not that useful
 697           often). I can open it - and that means edit the linked file in
 698           Emacs. That is useful.  And then I can view the linked file in a
 699           web browser. Can be useful too.
 700         </p>
 701         <p>
 702           And then I can move between the links.
 703         </p>
 704         <p>
 705           All this is useful, at least for me.  But there are some more
 706           things, in the menus <i>XHTML - Links</i>.  Check them out, you
 707           may like them. They may save you time.
 708         </p>
 709
 710         <h2 id="tocs">Did You Notice the Table of Contents at the Top?</h2>
 711         <p>
 712           Well, you should notice not because it exactly is the worlds
 713           most pretty table of content.  But because it is there.  And I
 714           did not write it.  nXhtml mode wrote it for me.
 715         </p>
 716         <p>
 717           How it works? Just put <b>id</b> attributes on your header tags
 718           (h1-h6).  Then position point where you want the table of
 719           contents.  Tell nXhtml mode to write it by using the menus
 720           <i>XHTML - Table of Contents</i>.
 721         </p>
 722         <p>
 723           When you want to change it just ask nXhtml mode to rewrite it.
 724         </p>
 725         <p>
 726           And you can make it more pretty if you are good at CSS.
 727         </p>
 728
 729         <h2 id="tidy">But I Can't Use this Cause my Files are HTML</h2>
 730         <p>
 731           That is a problem of course.  You need to convert them to XHTML
 732           because that is what the browsers and all other tools are best
 733           at today.
 734         </p>
 735         <p>
 736           But don't worry.  Didn't I tell you that nXhtml knows about <a
 737           href="http://tidy.sourceforge.net/">Tidy For XHTML</a>?  (It
 738           even comes together with nXhtml if you get it with EmacsW32.)
 739         </p>
 740         <p>
 741           Tidy can convert your HTML files to XHTML.
 742           Just open a file in nXhtml mode then use the <i>Tidy</i>
 743           menu and choose what you want to do there.
 744         </p>
 745         <p>
 746           If you do it file-by-file you can compare the "tidied" XHTML
 747           version of the file and your old version side by side (using
 748           Emacs Ediff command actually - an interactive way to compare).
 749           You can also tidy a whole directory tree at once.
 750         </p>
 751
 752         <h2 id="php">And what about Multiple Modes like PHP?</h2>
 753         <p>
 754           nXhtml mode can handle multiple modes in a buffer.  The
 755           benefits of nXml style completion can still be used.  This
 756           can even be done when there is no header in the file that
 757           tells what DTD to use for the completion.
 758         </p>
 759         <p>
 760           Mumamo, which is part of nXhtml, implements what it
 761           calls <i>multi major modes</i> for handling multiple major
 762           modes in a buffer.  Instead of turning on a major mode for a
 763           buffer you turn on a multi major mode and Mumamo will handle
 764           the rest.  Multi major modes has names like nxhtml-mumamo,
 765           html-mumamo, django-nxhtml-mumamo etc.
 766         </p>
 767         <p>
 768           When point is in a PHP part then the major mode is switched
 769           to php-mode, with all that means.  Here you can see how that
 770           looks:
 771         </p>
 772         <img alt="In PHP part" src="img/php-in-nxhtml.png" width="448" height="294" />
 773         <p>
 774           If you move the point outside of those &lt;?php ... ?&gt; areas
 775           then the mode is automatically switched to nxhtml-mode
 776           instead.  Now you can use the power of nxhtml-mode and
 777           do for example completion, like here:
 778         </p>
 779         <img alt="In XHTML part" src="img/php-in-nxhtml-2.png" width="450" height="294" />
 780         <p>
 781           The switching is done with a short delay so that it does not
 782           interfere with your normal editing. That's it. (But maybe
 783           there should be a better php-mode?  Does someone has any
 784           better than the one that comes with nXhtml now?)
 785         </p>
 786
 787         <h3 id="dtd-needed">But I Have no DTD Links in my PHP Files?</h3>
 788         <p>
 789           Ah, yes. Good question. You are right. nXhtml mode needs a
 790           DTD to be able to help you with XHTML and completion.  I
 791           thought it was impossible for a normal human to get that
 792           working.
 793         </p>
 794         <p>
 795           But it turned out to be surpricingly simple and it works
 796           quite nicely now.  The first time you do completion of XHTML
 797           code in a buffer where you do not have the needed XHTML
 798           headers nXhtml mode will ask you for what it calls a
 799           <em>fictive XHTML validation header</em>.  After that completion
 800           should work as usual.  A fictive XHTML validation header in nXhtml
 801           mode is something that is used in the background for
 802           validation. It is not inserted in the buffer, but may be shown on the screen like this:
 803         </p>
 804         <img alt="fictive XHTML validation header" src="img/xml-validation-header.png" width="448" height="374" />
 805         <p>
 806           nXhtml does its best to guess what fictive XHTML Validation Header
 807           the buffer needs, but if the default fictive XHTML validation header
 808           does not fit you can customize the choices.
 809         </p>
 810         <p>
 811           Note: Do not try to set the XML schema directly when the XHTML
 812           headers are missing in the buffer. Use a fictive XHTML
 813           validation header instead.
 814         </p>
 815
 816         <h3 id="multi-colors">Why Are Colors Different in Multiple Modes?</h3>
 817         <p>
 818           It has been necessary to replace the nxml-mode style
 819           fontification with the sgml-mode style.  All other features
 820           of nXml/nXhtml modes should still work however.
 821           In all other cases the normal fontification colors are used.
 822         </p>
 823         <p>
 824           Or perhaps you mean the background colors? These are just a
 825           visual aid about the dividing into chunks with different
 826           major modes and they can be turned off. Do <em>M-x
 827           customize-group RET mumamo RET</em>.
 828         </p>
 829
 830         <h3 id="part2">More Multiple Modes</h3>
 831         <p>
 832           nXhtml mode handles for example embedded style sheets the
 833           same way as it handles PHP chunks:
 834         </p>
 835         <!--
 836         <img alt="CSS embedded in XHTML" src="img/embedded-xhtml.png" width="448" height="294" />
 837         -->
 838         <img alt="CSS embedded in XHTML" src="img/style-in-nxhtml.png" width="448" height="278" />
 839         <p>
 840           Currently it can handle PHP, CSS, JavaScript, eRuby, JSP and
 841           some other minor cases.  If you can program in elisp it is
 842           not a very big deal adding support for other embedded
 843           languages.  (I do not use all the languages above myself so
 844           please give me feedback if there is something you think
 845           could be done better.)
 846         </p>
 847         <p>
 848           Please notice also that each major mode handles completion
 849           in its own ways.  The popup style completion is currently
 850           only used by nXhtml mode, not the other major modes even if
 851           they are on the same page.
 852         </p>
 853         <p>
 854           The use of multi major modes is not constrained to nXhtml.
 855           You can use that when editing other files too. To see what
 856           multi major modes are currently defined in your Emacs
 857           session see the
 858           variable <i>mumamo-defined-turn-on-functions</i>.
 859         </p>
 860
 861         <h3 id="tips-multi">Tips When Using Multiple Modes</h3>
 862         <p>
 863           The routines dividing into chunks with different major modes is not that very supersmart.
 864           They do not know much about the languages of the major modes.
 865           So if you write something like this:
 866         </p>
 867         <pre>
 868           &lt;?php
 869             echo '&lt;'?xml version="1.0" encoding="utf-8"?'>';
 870           ?&gt;
 871         </pre>
 872         <p>
 873           it will get very, very confused. If you are not fond of that
 874           you better write it like this instead:
 875         </p>
 876         <pre>
 877           &lt;?php
 878             echo '&lt;'; echo '?xml version="1.0" encoding="utf-8"?'; echo '>';
 879           ?&gt;
 880         </pre>
 881         <p>
 882           For a similar problem <a href="nxhtml-changes.html#php-attribute-values">attribute values computed by PHP</a>.
 883         </p>
 884         <p>
 885           When editing PHP sometimes the validation of the XHTML part
 886           gets quite upset.  You may even think that it is unuseful
 887           (since trying to complete gives you nothing), but it is not.
 888           Here is what you can do:
 889         </p>
 890         <ul>
 891           <li>
 892             Turn on <em>Fictive XHTML Validation Header</em> from
 893             menus. (In <em>nXhtml - Completion</em>.)  That will try
 894             to guess a how to start validation. It shows a fictive
 895             header at the top of the buffer to show you what is goind
 896             on (nothing is inserted in the buffer).
 897           </li>
 898           <li>
 899             If you do not think the red underlines you get are very
 900             pretty then you can hide them.  Use the menus again,
 901             <em>Hide Validation Errors</em>.
 902           </li>
 903         </ul>
 904         <p>
 905           And maybe you do not think the background colors when using
 906           Multiple Major Modes is very smart?  Then just go ahead and
 907           remove them. Customize.
 908           <em>M-x customize-group RET mumamo RET</em>.
 909         </p>
 910
 911         <h2 id="file-assoc">File Associations within Emacs</h2>
 912         <p>
 913           Some file associations are changed within Emacs to get
 914           multiple modes to work without requiring the user to do
 915           anything.  Good for a new user I guess, but I understand
 916           that old Emacs users may want more control over this.  If
 917           you are one of them then please look in
 918           <em>nxhtml-autoload.el</em> which is where the associations
 919           are made.
 920         </p>
 921
 922         <h2 id="bloggin">Not for Me, I Am Only Blogging</h2>
 923         <p>
 924           Not for you?
 925           Ah, wait a minute.
 926           Blogging, that is exactly one of the things that I myself use this for.
 927         </p>
 928         <p>
 929           When you blog you only write part of an XHTML page, so you
 930           may think that all the nicities of nXhtml mode like
 931           validation and completion does not work.  They do.  (If you
 932           wonder how, then please read <a href="#dtd-needed">But I
 933           Have No DTD Links In My PHP Files</a>. Though you do not
 934           have to read this to start using nXhtml for writing blog
 935           texts and comments.)
 936         </p>
 937         <p>
 938           The setup for blogging is simple
 939         </p>
 940         <ol>
 941           <li>
 942             <a href="http://www.mozilla.com/en-US/firefox/">Firefox</a> - which you of course already use ...
 943           </li>
 944           <li>
 945             The <a href="https://addons.mozilla.org/en-US/firefox/addon/4125">It's All Text</a> add-on to Firefox.
 946             It should use Emacs client:
 947             <p>
 948             <img alt="It's All Text preferences" src="img/itsalltext-pref.png" width="371" height="352" />
 949             </p>
 950           </li>
 951           <li>
 952             And finally: Customize the little elisp library that comes with nXhtml:
 953             <p style="padding-left:2em; font-size: 1em; font-weight: 600;">
 954                       M-x customize-group RET as-external RET
 955             </p>
 956             You just need to turn <i>as-external</i> on there.
 957           </li>
 958         </ol>
 959         <p>
 960           With this setup you just press F2 in any text area in
 961           Firefox and then you got the text to edit in Emacs - using
 962           nXhtml for completion etc. Finish and save with <b>C-x
 963           #</b>.
 964         </p>
 965
 966 <!--         <img alt="Edit part of an XHTML file" src="img/edit-part.png" width="448" height="390" /> -->
 967
 968         <h2 id="bloggin">And Other Goodies...</h2>
 969         <p>
 970           There are a lot of other things in the package too, please
 971           see the nXhtml menu in Emacs.  You can for example find a
 972           n-back-game (if you do not know what it is now, do not
 973           worry, just try it and you will learn - and understand why I
 974           put it there).
 975         </p>
 976       </div>
 977
 978       <hr align="left" class="footer" />
 979       <p class="footer">
 980         Copyright &copy; 2008 OurComments.org
 981         <br style="margin:0; padding:0; line-height: 0;" />
 982         Design thanks to <a href="http://www.oswd.org/">OSWD</a>
 983         <br />
 984       </p>
 985     </div>
 986   </body>
 987 </html>