diff options
Diffstat (limited to 'en_US/emacs.xml')
| -rw-r--r-- | en_US/emacs.xml | 735 |
1 files changed, 735 insertions, 0 deletions
diff --git a/en_US/emacs.xml b/en_US/emacs.xml new file mode 100644 index 0000000..66b4de3 --- /dev/null +++ b/en_US/emacs.xml @@ -0,0 +1,735 @@ +<!-- $Id: emacs.xml,v 1.1 2007/02/03 22:21:58 kwade Exp $ --> +<!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"> + <title>Emacs and PSGML Mode</title> + + <indexterm> + <primary>PSGML</primary> + </indexterm> + + <indexterm> + <primary>Emacs</primary> + </indexterm> + + <indexterm> + <primary>Emacs</primary> + <secondary>PSGML mode</secondary> + </indexterm> + + <para> + You can use the PSGML mode available for Emacs to make it easier to write + in XML format. PSGML mode provides syntax-highlighting, tag completion, + and more. + </para> + + <sect1 id="s1-emacs-file"> + <title>Setting Up Your <filename>.emacs</filename> File</title> + + <indexterm> + <primary>Emacs</primary> + <secondary>configuration file</secondary> + </indexterm> + + <indexterm> + <primary><filename>.emacs</filename></primary> + </indexterm> + + <para> + For Emacs to parse your DocBook documents correctly, you must have a + <filename>.emacs</filename> file. Cut and paste the following into your + existing <filename>.emacs</filename> file or create a new one that + contains the following lines: + +<screen> +<computeroutput> +;; turn on auto-fill in `text-mode' and derived modes +;;(mail, news, etc) +(add-hook 'text-mode-hook 'turn-on-auto-fill) + +;; +;;MODES +;; + +(setq auto-mode-alist (cons '("\\.sgml$" . sgml-mode) auto-mode-alist)) +(setq auto-mode-alist (cons '("\\.sgm$" . sgml-mode) auto-mode-alist)) + +;; +;;XML!! +;; +;;############################################################# + +;; +;;PSGML mode stuff +;; + +(autoload 'sgml-mode "psgml" "My Most Major Mode" t) + +(setq sgml-mode-hook '(lambda () "Defaults for XML mode." (turn-on-auto-fill) +(setq fill-column 80))) + +(defun My-XML-keymap () + (local-set-key [(alt i)] + '(lambda () + (interactive) + (sgml-indent-line) + (sgml-insert-element 'item) + (sgml-indent-line))) + (local-set-key [(alt l)] + '(lambda () + (interactive) + (sgml-insert-element 'list) + (sgml-insert-element 'item) + (sgml-indent-line))) + (local-set-key [(alt p)] + '(lambda () + (interactive) + (sgml-indent-line) + (sgml-insert-element 'para) + (sgml-indent-line))) + (local-set-key [(alt -)] + '(lambda () + (interactive) + (insert "—")))) + +(add-hook 'sgml-mode-hook 'My-XML-keymap) + +;; +;; Fix up indentation of data... +;; + +(setq-default sgml-indent-data t) + +;; +;; XML markup faces. +;; + +(setq-default sgml-set-face t) + + +(make-face 'sgml-comment-face) +(make-face 'sgml-doctype-face) +(make-face 'sgml-end-tag-face) +(make-face 'sgml-entity-face) +(make-face 'sgml-ignored-face) +(make-face 'sgml-ms-end-face) +(make-face 'sgml-ms-start-face) +(make-face 'sgml-pi-face) +(make-face 'sgml-sgml-face) +(make-face 'sgml-short-ref-face) +(make-face 'sgml-start-tag-face) + +(set-face-foreground 'sgml-comment-face "maroon") +(set-face-foreground 'sgml-doctype-face "dark green") +(set-face-foreground 'sgml-end-tag-face "blue2") +(set-face-foreground 'sgml-entity-face "red2") +(set-face-foreground 'sgml-ignored-face "maroon") +(set-face-background 'sgml-ignored-face "gray90") +(set-face-foreground 'sgml-ms-end-face "maroon") +(set-face-foreground 'sgml-ms-start-face "maroon") +(set-face-foreground 'sgml-pi-face "maroon") +(set-face-foreground 'sgml-sgml-face "maroon") +(set-face-foreground 'sgml-short-ref-face "goldenrod") +(set-face-foreground 'sgml-start-tag-face "blue2") + +(setq-default sgml-markup-faces + '((comment . sgml-comment-face) + (doctype . sgml-doctype-face) + (end-tag . sgml-end-tag-face) + (entity . sgml-entity-face) + (ignored . sgml-ignored-face) + (ms-end . sgml-ms-end-face) + (ms-start . sgml-ms-start-face) + (pi . sgml-pi-face) + (sgml . sgml-sgml-face) + (short-ref . sgml-short-ref-face) + (start-tag . sgml-start-tag-face))) + + +(defun docbook-mode () + (sgml-mode) + ) + + + +;; +;;END XML STUFF +;; +;;################################################################## + +;PO mode stuff + +(setq auto-mode-alist + (cons '("\\.pox?\\'" . po-mode) auto-mode-alist)) +(autoload 'po-mode "po-mode") + + + (global-set-key [(f1)] (lambda () (interactive) (manual- + entry (current-word)))) + +</computeroutput> +</screen> + + </para> + + <para> + Do you have a cool wheel mouse? If so, you can add the following to your + <filename>.emacs</filename> file so your wheel will work in + <application>Emacs</application> (must be + <application>Emacs</application> version 21): + </para> + +<screen> +<computeroutput> +;; Enable wheelmouse support by default for emacs 21 +(cond (window-system +(mwheel-install) +)) +</computeroutput> +</screen> + + <para> + If you are using the older version 20 of + <application>Emacs</application>, add the following instead: + </para> + +<screen> +<computeroutput> +;; Enable wheelmouse support by default +(require 'mwheel) +</computeroutput> +</screen> + +<!-- bug #125757 in NEEDINFO state + <para> + If you have a mouse, you can also add the following. It adds popup menus + when the cursor is either on a start tag or in a region where elements + are allowed. + </para> + +<screen> +<computeroutput> +;; Mouse Bindings: right-click to generate context-aware +;; elements/attributes popup menu. +(define-key sgml-mode-map [mouse-3] 'sgml-tags-menu) +</computeroutput> +</screen> + +--> + + </sect1> + + + <sect1 id="s1-emacs-colors"> + <title>Customizing Emacs</title> + + <indexterm> + <primary>Emacs</primary> + <secondary>customizing</secondary> + </indexterm> + + <indexterm> + <primary><filename>.Xresources</filename></primary> + </indexterm> + + <indexterm> + <primary>Emacs</primary> + <secondary>colors</secondary> + </indexterm> + + <indexterm> + <primary>Emacs</primary> + <secondary>font</secondary> + </indexterm> + + <indexterm> + <primary>Emacs</primary> + <secondary>geometry</secondary> + </indexterm> + + <para> + The colors, font, and geometry (default size of window) for Emacs in your + <filename>~/.Xresources</filename> file. The format for the settings is + <computeroutput>emacs.keyword:value</computeroutput> + </para> + + <para> + The following is a sample <filename>~/.Xresources</filename> file. + </para> + <note> + <title>Note</title> + <para>If you have other settings in your + <filename>~/.Xresources</filename>, add the following to the end of + the file. + </para> + </note> + +<screen> +<userinput> +emacs.background: light gray +emacs.foreground: black +emacs.pointerColor: blue +emacs.cursorColor: blue +emacs.bitmapIcon: on +emacs.font: fixed +emacs.geometry: 90x25 +</userinput> +</screen> + <para> + After modifying this file, you must execute the command + </para> +<screen> +<command>xrdb -merge ~/.Xresources</command> +</screen> + <para> + and restart <application>Emacs</application> for the changes to take + place. + </para> + + </sect1> + + <sect1 id="s1-emacs-cedfile"> + <title>Create Recompiled DTD Subset</title> + + <para> + Emacs will perform syntax highlighting and indent correctly on + DocBook XML files if you provide it with the proper Document Type + Declarations (DTD) file. These two features will make your XML file + look pretty and help you spot errors. + </para> + + <para> + To create a loadable Parsed DTD file: + <orderedlist> + <listitem> + <para>Find the parent file for the group of DocBook files. You will + recognize this file by the header <filename><!DOCTYPE article + PUBLIC "-//OASIS//DTD DocBook V4.1//EN"</filename>. An easy way + to find this parent file is to use the command <command>grep + DocBook *.xml</command>. Once you find the parent file, open it + in Emacs with the command <command>emacs + <replaceable><parentfile></replaceable>.xml</command> (where + <replaceable><parentfile></replaceable>.xml is the parent + file you found. + </para> + </listitem> + + <listitem> + <para>Choose <command>DTD -> Parse DTD</command> from the pulldown + menu. + </para> + </listitem> + + <listitem> + <para>You will know the parsing is finished when you see the message + <computeroutput>Fontifying...done</computeroutput> at the bottom + of your screen. Save the parsed DTD to a file by choosing + <command>DTD -> Save Parsed DTD</command> from the pulldown menu. + </para> + </listitem> + + <listitem> + <para>Press <keycap>Enter</keycap> to save the file to the default + filename or rename the file keeping the <filename>.ced</filename> + extension. It can be useful to name it something generic such as + <filename>docbook.ced</filename> so you can refer to it when + opening all DocBook files. This file can also be copied from + directory to directory to be loaded. + </para> + </listitem> + + </orderedlist> + </para> + + <tip> + <title>Tip</title> + <para> + You can also use the Emacs command <command>Meta-x + sgml-parse-prolog</command> to parse the file, and then use the + command <command>Meta-x sgml-save-dtd</command> to save the parsed DTD + to a <filename>.ced</filename> file. + </para> + </tip> + + </sect1> + + <sect1 id="s1-emacs-loadced"> + <title>Load the Parsed DTD</title> + + <para> + Now that you have saved the DTD settings, you can load the + <filename>.ced</filename> file and see the syntax highlighting for your + <filename>.sgml</filename> files. + </para> + + <para> + To load a parsed DTD file: + <orderedlist> + <listitem> + <para>Open an XML file in Emacs. + </para> + </listitem> + + <listitem> + <para>Choose <command>DTD -> Load DTD</command> from the pulldown menu + and choose the file you saved from the previous step. For + instance, choose <filename>docbook.ced</filename>. + </para> + </listitem> + + <listitem> + <para>You will know it is finished when you see the message + <computeroutput>Fontifying...done</computeroutput> at the bottom + of your screen. Loading the parsed DTD might take a long time. + You can start editing the file before it finishes. + </para> + </listitem> + + </orderedlist> + + </para> + + <tip> + <title>Tip</title> + <para> + You can also use the Emacs command <command>Meta-x + sgml-load-dtd</command> to load the parsed DTD. + </para> + </tip> + + </sect1> + + <sect1 id="s1-emacs-basic-commands"> + <title>Basic Emacs Commands</title> + + <para> + The <keycap>Meta</keycap> key is usually the <keycap>Alt</keycap> key. + </para> + + <table frame="all" rowsep="1" colsep="1" id="tb-emacs-commands"> + <title>Emacs Commands</title> + <tgroup rowsep="1" colsep="1" cols="2"> + <colspec colnum="1" colname="shortcut" colwidth="170"/> + <colspec colnum="2" colname="description" colwidth="300"/> + + <thead> + <row> + <entry rowsep="1" colsep="1">Shortcut</entry> + <entry rowsep="1" colsep="1">Description</entry> + </row> + </thead> + <tbody> + <row> + <entry rowsep="1" colsep="1"><keycombo> + <keycap>Meta</keycap><keycap>x</keycap></keycombo> + sgml-parse-prolog, <keycap>Enter</keycap></entry> + <entry>Parse DTD</entry> + </row> + <row> + <entry><keycombo><keycap>Meta</keycap><keycap>x</keycap> + </keycombo>sgml-save-dtd, <keycap>Enter</keycap></entry> + <entry>Save the Parse DTD</entry> + </row> + <row> + <entry><keycombo> <keycap>Meta</keycap><keycap>x</keycap> + </keycombo>sgml-load-dtd, <keycap>Enter</keycap></entry> + <entry>Load DTD</entry> + </row> + <row> + <entry><keycombo> <keycap>Ctrl</keycap> <keycap>c</keycap> + </keycombo>, <keycombo> <keycap>Shift</keycap> + <keycap></keycap></keycombo>, <keycap>Tab</keycap></entry> + <entry>Display list of valid tags</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>c</keycap> + </keycombo>, <keycombo> <keycap>Shift</keycap> + <keycap></keycap> </keycombo>, type beginning of tag, + <keycap>Tab</keycap></entry> + <entry>Complete the tag</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>g</keycap> + </keycombo></entry> + <entry>Cancel a command in the minibuffer</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>c</keycap> + </keycombo>, <keycap>/</keycap></entry> + <entry>Close tag</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>a</keycap> + </keycombo></entry> + <entry>Move cursor to beginning of line</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>e</keycap> + </keycombo></entry> + <entry>Move cursor to the end of the line</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>Home</keycap> + </keycombo></entry> + <entry>Move cursor to the beginning of the file</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>End</keycap> + </keycombo></entry> + <entry>Move cursor to the end of the file</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>k</keycap> + </keycombo></entry> + <entry>Cut line</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>y</keycap> + </keycombo></entry> + <entry>Paste line</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>s</keycap> + </keycombo></entry> + <entry>Search forward in the file</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>r</keycap> + </keycombo></entry> + <entry>Search backwards in the file</entry> + </row> + <row> + <entry><keycombo><keycap>Meta</keycap><keycap>$</keycap> + </keycombo></entry> + <entry>Check spelling of current word</entry> + </row> + <row> + <entry><keycombo><keycap>Meta</keycap><keycap>x</keycap> + </keycombo> ispell-word, <keycap>Enter</keycap></entry> + <entry>Check spelling of current word</entry> + </row> + <row> + <entry><keycombo><keycap>Meta</keycap><keycap>x</keycap> + </keycombo> ispell-buffer, <keycap>Enter</keycap></entry> + <entry>Check spelling of current buffer</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>x</keycap> + </keycombo>, <keycombo><keycap>Ctrl</keycap><keycap>f</keycap> + </keycombo></entry> + <entry>Open file</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>x</keycap> + </keycombo>, <keycombo><keycap>Ctrl</keycap><keycap>s</keycap> + </keycombo></entry> + <entry>Save file</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>x</keycap> + </keycombo>, <keycombo><keycap>Ctrl</keycap><keycap>c</keycap> + </keycombo></entry> + <entry>Exit <application>Emacs</application> and prompt to save + files if necessary</entry> + </row> + <row> + <entry><keycombo><keycap>Meta</keycap> <keycap>q</keycap> + </keycombo></entry> + <entry>Fill paragraph</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>c</keycap> + </keycombo>, <keycombo><keycap>Ctrl</keycap><keycap>a</keycap> + </keycombo></entry> + <entry>Edit attributes for a tag (for example, you can edit the + <computeroutput>url</computeroutput> attribute of the + <computeroutput>ulink</computeroutput> tag)</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>c</keycap> + </keycombo>, + <keycombo><keycap>Ctrl</keycap><keycap>c</keycap> + </keycombo></entry> + <entry>Exit edit attributes</entry> + </row> + </tbody> + </tgroup> + </table> + + </sect1> + + <sect1 id="s1-emacs-examples"> + <title>Examples</title> + + <para> + The table or reference card of Emacs and PSGML commands can be confusing + for beginners. This section provides some examples of how to use them. + </para> + + <sect2 id="s2-emacs-tag-completion"> + <title>Tag Completion</title> + + <note> + <title>Note</title> + <para>This section assumes that you have already loaded the DTD file + (<filename>.ced</filename>). + </para> + </note> + + <para> + Instead of typing a tag each time you need to use it, use + the key combination <keycap>Ctrl</keycap>-<keycap>c</keycap>, + followed by <keycap><</keycap>. At the bottom of the + <application>Emacs</application> window, you will see: + </para> +<screen> +<computeroutput>Tag: <</computeroutput> +</screen> + + <para> + To view a list of available tags, use either the <keycap>Tab</keycap> + or <keycap>?</keycap>. Or, if you know the first few letters of a tag, + you can enter them followed by <keycap>Tab</keycap> for a complete + list of available tags beginning with those letters or for a tag + completion. + </para> + + <para> + Try the following: Type <keycap>Ctrl</keycap>-<keycap>c</keycap> + followed by <keycap><</keycap>. Then enter the letter + <keycap>k</keycap>, followed by <keycap>Tab</keycap>. You may have to + use the <keycap>Tab</keycap> key several times to get a complete list. + </para> + + <para> + The output should look similar to the example below: + </para> + +<screen> +<computeroutput> +Click mouse-2 on a completion to select it. +In this buffer, type RET to select the completion near point. + +Possible completions are: +<keycap> <keycode> +<keycombo> <keysym> +</computeroutput> +</screen> + + </sect2> + <sect2 id="s2-emacs-tag-closing"> + <title>Tag Closure</title> + + <para> + Once you have started the tag of choice, you must close it. The easiest + way to close an open tag is to use the keycombo + <keycap>Ctrl</keycap>-<keycap>c</keycap>, followed by + <keycap>/</keycap>. This will close the closest open tag you have. + </para> + + </sect2> + + <sect2 id="s2-emacs-other"> + <title>Other Emacs Tasks</title> + + <para> + <guilabel>Working with one window</guilabel>: Sometimes in + <application>Emacs</application> the window becomes split (with tags + completions or other text in the bottom window). The easiest way to + get it back so that only your XML and text appear on one screen is to + use the keycombo <keycap>Ctrl</keycap>-<keycap>x</keycap>, followed by + <keycap>1</keycap>. + </para> + + <para> + <guilabel>Saving your work</guilabel>: To save your work, use the + following keycombo, <keycap>Ctrl</keycap>-<keycap>x</keycap> followed by + <keycap>Ctrl</keycap>-<keycap>s</keycap>. + </para> + + <para> + <guilabel>The "clear/quit" command</guilabel>: I have found on some + occasions that I have gotten too far into the tag completion process and + need to just exit back out to my text. The easiest way to do this is the + keycombo <keycap>Ctrl</keycap>-<keycap>g</keycap>. This command quits + what you have been doing within the file, without quitting the file + itself. + </para> + + <para> + <guilabel>Opening a new file</guilabel>: To open a new file, use the + keycombo <keycap>Ctrl</keycap>-<keycap>x</keycap> followed by + <keycap>Ctrl</keycap>-<keycap>f</keycap>. At the bottom of the emacs + window, you will be able to enter in the file name (using + <keycap>Tab</keycap> completion if needed) of the file you wish to + open. + </para> + + <para> + <guilabel>Closing emacs</guilabel>: The easiest way to close + <application>emacs</application> is to use the keycombo + <keycap>Ctrl</keycap>-<keycap>x</keycap> followed by + <keycap>Ctrl</keycap>-<keycap>c</keycap>. If you have not saved your work, + it will prompt you to save the file, otherwise it will just quit the + current emacs session you have been working with. + </para> + </sect2> + + </sect1> + + <sect1 id="s1-emacs-additional-resources"> + <title>Additional Resources</title> + + <para> Additional Emacs and PSGML references are available at the + following locations: + </para> + + <itemizedlist> + <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> + <listitem> + <para>Read <citetitle>Editing XML with Emacs and PSGML</citetitle> + in <filename>/usr/share/doc/psgml-<replaceable><version></replaceable>/psgml.ps</filename>. </para> + </listitem> + <listitem> + <para><ulink + url="http://www.snee.com/bob/sgmlfree/psgmqref.html">http://www.snee.com/bob/sgmlfree/psgmqref.html</ulink> + — <citetitle>Emacs/PSGML Quick Reference</citetitle> is a + reference table of Emacs commands for PSGML mode. + </para> + </listitem> + <listitem> + <para><ulink + url="http://www.snee.com/bob/sgmlfree/emcspsgm.html">http://www.snee.com/bob/sgmlfree/emcspsgm.html</ulink> + — <citetitle>PSGML Tricks</citetitle></para> + </listitem> + </itemizedlist> + + </sect1> + </chapter> + + + + + + + + + |