renaming rh-guidelines to writing-guidelines

1 files changed, 340 insertions, 0 deletions

diff --git a/en_US/emacs-nxml.xml b/en_US/emacs-nxml.xml
new file mode 100644
index 0000000..5cc9dac
--- /dev/null
+++ b/en_US/emacs-nxml.xml
@@ -0,0 +1,340 @@
+<!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>