path: root/en_US/docs-emacs-nxml.xml

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" 
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- *************** Bring in Fedora entities *************** -->
<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "fdp-entities.ent">
%FEDORA-ENTITIES-EN;

]>

  <chapter id="ch-emacs-nxml">
  <title>Emacs and nXML Mode</title>
    
  <indexterm>
    <primary>nXML</primary>
  </indexterm>
    
  <indexterm>
    <primary>Emacs</primary>
  </indexterm>

  <indexterm>
    <primary>Emacs</primary>
    <secondary>nXML mode</secondary>
  </indexterm>

  <para>
    You can also use the nXML mode available for
    <application>Emacs</application> to make it even easier to write in DocBook
    XML format. nXML mode provides context-sensitive editing using completion,
    real time validity error checking, syntax highlighting and indentation. All
    you need to do is install an RPM!!
  </para>

  <note>
    <title>Early stages</title>
    <para>
	Please be aware the nxml-mode for <application>Emacs</application> is
      quite new, so there are a few things that the advanced user might notice
      when using it with other documents types. If you keep an eye on the
      mailing-list, you can keep up to date with these, as well as ask
      questions. For more details, check out <xref
	linkend="s1-emacs-nxml-readme"></xref>.
    </para>
  </note>

    
  <sect1 id="s1-nxml-rpm">
    <title>Getting the nXML RPM</title>

    <indexterm>
      <primary>nXML</primary>
      <secondary>RPM</secondary>
    </indexterm>
      
    <indexterm>
      <primary>nXML RPM</primary>
    </indexterm>
      
    <para>
      To use nXML mode with emacs, you will need to install the nXML RPM
      available from <ulink
	url="http://people.redhat.com/twaugh/ftp/docbook/nxml-mode/">Tim
	Waugh's</ulink> website or the source from <ulink
	url="http://www.thaiopensource.com/download/">http://www.thaiopensource.com/download/</ulink>. 
      The source requires a lot more work to setup, therefore we will only be
      concentrating on the RPM version.
    </para>

    <para>
	Information on where to get the source is available in <xref
        linkend="s1-emacs-additional-resources"></xref>.
    </para>
      
  </sect1>

  <sect1 id="s1-nxml-examples">
    <title>Examples</title>
      
    <para>
      Compared to PSGML mode there are only couple of commands that you need.
      This speeds up writing with <application>Emacs</application> considerably,
      which means you can concentrate more on the content of your article.
    </para>

    <sect2 id="s2-nxml-commands">
      <title>Commands</title>
	
      <para>
	To create a tag, type <userinput>&lt;</userinput> and then type the
	keyword. To complete the keyword, press <command>Ctrl-Ret</command>,
	then add the last <userinput>></userinput>. To close a tag, type
	<userinput>&lt;/</userinput>.
      </para>

      <important>
	<title>Important</title>
	<para>
	  When you open a document that doesn't have a DOCTYPE declaration at
	  the top of the file, you will get this message and tag completion
	  won't work because nXML will not know what format you are writing.
	</para>
      </important>

      <para>
	To load the schema, type <command>Ctrl-c</command>, then
	<command>Ctrl-s</command> and navigate to
	<filename>/usr/share/emacs/site-lisp/nxml-mode/schema/</filename> and
	load <filename>docbook.rnc</filename>. <application>Emacs</application>
	will then prompt you to save it in the current working directory.
      </para>

	  
      <tip>
	<title>Tip</title>
	<para>
	    The commands already discussed are the only differences between
	  using <application>Emacs</application> with PSGML mode and
	  <application>Emacs</application> with nXML mode. You will still need
	  to use all the same commands as discussed in <xref
	    linkend="s1-emacs-basic-commands"></xref>.
	</para>
      </tip>
    </sect2>
  </sect1>

  <sect1 id="s1-emacs-nxml-additional-resources">
    <title>Additional Resources</title>

    <para> Additional Emacs and nXML references are available at the following
      locations:
    </para>

    <itemizedlist>
      <listitem>
	<para><ulink
	    url="http://www.thaiopensource.com/download/">http://www.thaiopensource.com/download/</ulink> 
	  &mdash; <citetitle>Author's download area</citetitle>
	</para>
      </listitem>
      <listitem>
	<para><ulink
	    url="http://wks.uts.ohio-state.edu/unix_course/intro-135.html">http://wks.uts.ohio-state.edu/unix_course/intro-135.html</ulink> 
	  &mdash; <citetitle>Emacs Quick Reference Guide</citetitle>
	</para>
      </listitem>
      <listitem> 
	<para>Emacs reference card that comes with the
	  <filename>emacs</filename> package. You can print it out as a
	  reference. &mdash;
	  <filename>/usr/share/emacs/<replaceable>&lt;version&gt;</replaceable>/etc/refcard.ps</filename>
	</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 id="s1-emacs-nxml-readme">
    <title>nXML README File</title>

    <note>
      <title>Note</title>
      <para>
	This file can be found in the directory you extracted the source into,
	or in
	<filename>/usr/share/doc/nxml-mode-<replaceable>&lt;version&gt;</replaceable>/</filename> 
	if you installed the RPM.
      </para>
    </note>

    <para>README file:</para>

    <para>
      This is a new major mode for GNU Emacs for editing XML documents. It
      supports editing well-formed XML documents and also provides
      schema-sensitive editing of XML documents using RELAX NG Compact Syntax.
    </para>
      
    <para>
      To use this, you need GNU Emacs version 21.x, preferably 21.3. GNU Emacs
      version 20 will not work properly, nor will XEmacs. To get started, do the
      following:
    </para>

    <screen>
      <command>M-x load-file RET rng-auto.el RET</command>
    </screen>
      
    <para>
      This defines the necessary autoloads.  Now, visit a file containing an XML
      document, and do the following:
    </para>

    <screen> <command>M-x nxml-mode</command>
    </screen>

    <para>
      Now do 
    </para>
	
    <screen>
      <command>C-h m</command>
    </screen>

    <para>
      For information on how to use nxml-mode.  The beginnings of a manual are
      in nxml-mode.info.  You can read this using:
    </para>

    <screen>
      <command>C-u M-x info RET nxml-mode.info RET</command>
    </screen>

    <para>
      It's also installed as an entry at the end of the top-level info
      directory.  So you can read it with <command>C-h i</command> as usual.
    </para>

    <para>
      You can use <filename>test.valid.xml</filename> and
      <filename>test.invalid.xml</filename> as examples of valid and invalid XML
      documents.
    </para>

    <para>
      To get things automatically loaded each time you start Emacs, add:
    </para>

    <screen>
      <computeroutput> (load "~/nxml-mode-200YMMDD/rng-auto.el")
      </computeroutput>
    </screen>

    <para>
      to your <filename>.emacs</filename>, where
      <computeroutput>~/nxml-mode-200YMMDD</computeroutput> is the directory
      containing the <filename>.elc</filename> files.  Note that
      <filename>rng-auto.el</filename> does not load all of the nxml-mode code;
      it merely sets things up so that all the features of nxml-mode will be
      autoloaded properly.  You should not try to autoload
      <filename>rng-auto.el</filename> itself.
    </para>

    <para>
      To use nxml-mode automatically for files with an extension of
      <filename>xml</filename>, <filename>xsl</filename>,
      <filename>rng</filename> or <filename>xhtml</filename>, add the following
      to your <filename>.emacs</filename> file:
    </para>

    <screen>
      <computeroutput> (setq auto-mode-alist (cons
	'("\\.\\(xml\\|xsl\\|rng\\|xhtml\\)\\'" . nxml-mode) auto-mode-alist))
      </computeroutput>
    </screen>

    <para>
      If you edit XML using iso-8859-N encodings other than iso-8859-1 and you
      are running Emacs 21.3 or later, then I recommend enabling
      unify-8859-on-decoding-mode, by adding the following to your
      <filename>.emacs</filename> file:
    </para>

    <screen>
      <computeroutput>(unify-8859-on-decoding-mode)</computeroutput>
    </screen>

    <para>
      To get validation and schema-sensitive editing, you need a RELAX NG
      Compact Syntax (RNC) schema for you document. The schema directory
      includes some schemas for popular document types.
    </para>

    <para>
      For more on RELAX NG, refer to <ulink
	url="http://relaxng.org/">http://relaxng.org/</ulink>.
    </para>

    <para>
      For a tutorial on RELAX NG Compact Syntax, refer to <ulink
	url="http://relaxng.org/compact-tutorial.html">http://relaxng.org/compact-tutorial.html</ulink>
    </para>

    <para>
      For automatically creating RNC schemas, I recommend my Trang program:
      <ulink
	url="http://www.thaiopensource.com/relaxng/trang.html">http://eee.thaiopensource.com/relaxng/trang.html"</ulink>
    </para>

    <para>
	You can use this to
	
<itemizedlist>
	<listitem>
	  <para>
	    Infer an RNC schema from an instance document
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Convert a DTD to an RNC schema
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Convert a RELAX NG XML syntax schema to an RNC schema
	  </para>
	</listitem>
</itemizedlist>
    </para>

    <para>
      To convert a RELAX NG XML syntax (.rng) schema to a RNC schema, you can
      also use the XSLT stylesheet from <ulink
	url="http://www.pantor.com/download.html">http://www.pantor.com/download.html"</ulink>.
    </para>

    <para>
      To convert a W3C XML Schema to an RNC schema, you need first to convert it
      to RELAX NG XML syntax using Sun's RELAX NG converter tool rngconv (built
      on top of MSV). Refer to <ulink
	url="https://msv.dev.java.net/">https://www.dev.java.net/</ulink>.
    </para>

    <para>
      The file <filename>NEWS</filename> describes recent changes.
    </para>

    <para>
      Please use the list <ulink
	url="http://groups.yahoo.com/group/emacs-nxml-mode/">http://groups.yahoo.com/group/emacs-nxml-mode</ulink> 
      for bug reports, discussion. I will announce all new versions there.
    </para>

    <para>
      James Clark
    </para>
    <para>
      jjc@thaiopensource.com
    </para>
  </sect1>
  </chapter>