diff options
| -rw-r--r-- | acknowledgments-en.xml | 5 | ||||
| -rw-r--r-- | docs-emacs-nxml-en.xml | 300 | ||||
| -rw-r--r-- | docs-intro-en.xml | 5 | ||||
| -rw-r--r-- | documentation-guide-en.xml | 9 |
4 files changed, 315 insertions, 4 deletions
diff --git a/acknowledgments-en.xml b/acknowledgments-en.xml index a5703e4..2477797 100644 --- a/acknowledgments-en.xml +++ b/acknowledgments-en.xml @@ -19,4 +19,9 @@ figure tag example. </para> + <para> + A patch from Gavin Henry (ghenry at suretecsystems.com) has been applied to + add the <xref linkend="ch-emacs-nxml"></xref>. + </para> + </chapter> diff --git a/docs-emacs-nxml-en.xml b/docs-emacs-nxml-en.xml new file mode 100644 index 0000000..ae2c7d3 --- /dev/null +++ b/docs-emacs-nxml-en.xml @@ -0,0 +1,300 @@ + <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 DockBook 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 <application>nXML rpm</application></title> + + <indexterm> + <primary>nXML</primary> + <secondary>rpm</secondary> + </indexterm> + + <indexterm> + <primary><application>nXML rpm</application></primary> + </indexterm> + + <para> + In order 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/">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 Emacs 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, just type <userinput><</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></</userinput>. + </para> + + <important> + <title>Using vacuous schema</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>Don't forget</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> — <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> + — <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. — + <filename>/usr/share/emacs/<replaceable><version></replaceable>/etc/refcard.ps</filename> + </para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="s1-emacs-nxml-readme"> + <title>nXML README file</title> + + <note> + <para> + This file can be found in the directory you extracted the source into, or in <filename>/usr/share/doc/nxml-mode-<replaceable><version></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 + </para> + + <para> + <command> M-x load-file RET rng-auto.el RET</command> + </para> + + <para> + This defines the necessary autoloads. Now, visit a file containing + an XML document, and do + </para> + + <para> + <command>M-x nxml-mode</command> + </para> + + <para> + Now do + </para> + + <para> + <command>C-h m</command> + </para> + + <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> + + + <para> + <command>C-u M-x info RET nxml-mode.info RET</command> + </para> + + <para> + It's also installed as an entry at the end of the top-level info + directory. So you can read it with <computeroutput>C-h i</computeroutput> as usual. + </para> + <para> + You can use test.valid.xml and test.invalid.xml as examples of valid + and invalid XML documents. + </para> + + <para> + To get things automatically loaded each time you start Emacs, add + + <screen> + <computeroutput> +(load "~/nxml-mode-200YMMDD/rng-auto.el") + </computeroutput> + </screen> + + to your .emacs, where ~/nxml-mode-200YMMDD 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 xml, +xsl, rng or xhtml, add + </para> + + <screen> + <computeroutput> +(setq auto-mode-alist + (cons '("\\.\\(xml\\|xsl\\|rng\\|xhtml\\)\\'" . nxml-mode) + auto-mode-alist)) + </computeroutput> + </screen> + <para> + to your .emacs. + </para> + + <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 + </para> + + <para> + <command>(unify-8859-on-decoding-mode)</command> + </para> + + <para> + to your <filename>.emacs.</filename> + </para> + + <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, see <ulink url="http://relaxng.org">http://relaxng.org</ulink> + </para> + + <para> + For a tutorial on RELAX NG Compact Syntax, see <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). See <ulink url="https://msv.dev.java.net/">https://www.dev.java.net/</ulink> + </para> + + <para> + The file NEWS 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> + + + + + + + + + diff --git a/docs-intro-en.xml b/docs-intro-en.xml index 905edde..19e586f 100644 --- a/docs-intro-en.xml +++ b/docs-intro-en.xml @@ -1,4 +1,4 @@ -<!-- $Id: docs-intro-en.xml,v 1.1 2003/09/22 16:34:23 tfox Exp $ --> +<!-- $Id: docs-intro-en.xml,v 1.2 2004/01/19 23:14:46 tfox Exp $ --> <preface id="ch-intro"> <title>Introduction</title> @@ -29,6 +29,9 @@ <listitem> <para>Emacs with PSGML mode (optional, but recommended)</para> </listitem> + <listitem> + <para>Emacs with nXML mode (optional, but also recommended)</para> + </listitem> </itemizedlist> <para> diff --git a/documentation-guide-en.xml b/documentation-guide-en.xml index 733b502..31e1ede 100644 --- a/documentation-guide-en.xml +++ b/documentation-guide-en.xml @@ -1,4 +1,4 @@ -<!-- $Id: documentation-guide-en.xml,v 1.4 2003/11/25 21:03:40 tfox Exp $ --> +<!-- $Id: documentation-guide-en.xml,v 1.5 2004/01/19 23:14:46 tfox Exp $ --> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ @@ -10,7 +10,7 @@ <!ENTITY DISTRO "Fedora Core"> <!-- Set the distro name --> <!ENTITY IG "&DISTRO; Installation Guide"> <!-- Always use for Installation Guide --> -<!ENTITY BOOKID "documentation-guide-0.1.1 (2003-09-16)"> <!-- change version of manual and date here --> +<!ENTITY BOOKID "documentation-guide-0.1.1 (2004-01-19)"> <!-- change version of manual and date here --> <!ENTITY LEGALNOTICE SYSTEM "../common/legalnotice-en.xml"> @@ -19,6 +19,7 @@ <!ENTITY GETTINGFILES SYSTEM "docs-getting-files-en.xml"> <!ENTITY GUIDELINES SYSTEM "docs-rh-guidelines-en.xml"> <!ENTITY EMACS SYSTEM "docs-emacs-en.xml"> +<!ENTITY EMACS-NXML SYSTEM "docs-emacs-nxml-en.xml"> <!ENTITY TAGS SYSTEM "docs-xml-tags-en.xml"> <!ENTITY TUTORIAL SYSTEM "docs-tutorial-en.xml"> <!ENTITY CONVERTING SYSTEM "docs-converting-en.xml"> @@ -32,7 +33,7 @@ <bookinfo> <title>&NAME-TITLE; Documentation Guide</title> <copyright> - <year>2003</year> + <year>2003,2004</year> <holder>&FORMAL-RHI;</holder> <holder>Tammy Fox</holder> <holder>Johnray Fuller</holder> @@ -64,6 +65,8 @@ &EMACS; + &EMACS-NXML; + &TAGS; &TUTORIAL; |