path: root/en_US/emacs.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id: emacs.xml,v 1.4 2007/03/08 03:00:44 pfrields 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>
    
  <section id="sn-installing-psgml">
    <title>Installing PSGML</title>
    <para>To install PSGML, use the <command>yum</command> command:</para>
    <screen><userinput>yum install psgml</userinput></screen>
  </section>
    <section id="sn-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><![CDATA[
;; 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 "&mdash;"))))      

(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>
      If you have a wheel mouse and are using Emacs version 21, you can add the
      following to your <filename>.emacs</filename> file so your wheel will work
      in <application>Emacs</application>:
    </para>
    
    <screen><computeroutput><![CDATA[
;; 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><![CDATA[
;; 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>

-->

    </section>   


     <section id="sn-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><![CDATA[
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>
      
    </section>   
  
    <section id="sn-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>&lt;!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>&lt;parentfile&gt;</replaceable>.xml</command> (where
	      <replaceable>&lt;parentfile&gt;</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>
      
    </section>

    <section id="sn-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>

    </section>
    
    <section id="sn-emacs-basic-commands">
      <title>Basic Emacs Commands</title>
      
      <para>
	The <keycap>Meta</keycap> key is usually the <keycap>Alt</keycap> key.
      </para>
      
      <segmentedlist id="tb-emacs-commands">
      <title>Emacs Commands</title>
      <segtitle>Shortcut</segtitle>
      <segtitle>Description</segtitle>
      <seglistitem>
	<seg><keycombo>
	    <keycap>Meta</keycap><keycap>x</keycap></keycombo>
	  sgml-parse-prolog, <keycap>Enter</keycap></seg>
	<seg>Parse DTD</seg>
      </seglistitem>
      <seglistitem>
	<seg><keycombo><keycap>Meta</keycap><keycap>x</keycap>
	  </keycombo>sgml-save-dtd, <keycap>Enter</keycap></seg>
	<seg>Save the Parse DTD</seg>
      </seglistitem>
      <seglistitem>
	<seg><keycombo> <keycap>Meta</keycap><keycap>x</keycap>
	  </keycombo>sgml-load-dtd, <keycap>Enter</keycap></seg> 
	<seg>Load DTD</seg>
      </seglistitem>
      <seglistitem>
	<seg><keycombo> <keycap>Ctrl</keycap> <keycap>c</keycap>
	  </keycombo>, <keycombo> <keycap>Shift</keycap>
	    <keycap></keycap></keycombo>, <keycap>Tab</keycap></seg>
	<seg>Display list of valid tags</seg>
      </seglistitem>
      <seglistitem>
	<seg><keycombo><keycap>Ctrl</keycap> <keycap>c</keycap>
	  </keycombo>, <keycombo> <keycap>Shift</keycap>
	    <keycap></keycap> </keycombo>, type beginning of tag,
	  <keycap>Tab</keycap></seg>
	<seg>Complete the tag</seg>
      </seglistitem>
      <seglistitem>
	<seg><keycombo><keycap>Ctrl</keycap> <keycap>g</keycap>
	  </keycombo></seg>
	<seg>Cancel a command in the minibuffer</seg>
      </seglistitem>
      <seglistitem>
	<seg><keycombo><keycap>Ctrl</keycap> <keycap>c</keycap>
	  </keycombo>, <keycap>/</keycap></seg>
	<seg>Close tag</seg>		
      </seglistitem>
      <seglistitem>
	<seg><keycombo><keycap>Ctrl</keycap> <keycap>a</keycap>
	  </keycombo></seg>
	<seg>Move cursor to beginning of line</seg>
      </seglistitem>
      <seglistitem>
	<seg><keycombo><keycap>Ctrl</keycap><keycap>e</keycap>
	  </keycombo></seg>
	<seg>Move cursor to the end of the line</seg>
      </seglistitem>
      <seglistitem>
	<seg><keycombo><keycap>Ctrl</keycap><keycap>Home</keycap>
	  </keycombo></seg>	
	<seg>Move cursor to the beginning of the file</seg>		
      </seglistitem>
      <seglistitem>
	<seg><keycombo><keycap>Ctrl</keycap><keycap>End</keycap>
	  </keycombo></seg>	
	<seg>Move cursor to the end of the file</seg>		
      </seglistitem>
      <seglistitem>
	<seg><keycombo><keycap>Ctrl</keycap><keycap>k</keycap>
	  </keycombo></seg>
	<seg>Cut line</seg>
      </seglistitem> 
      <seglistitem>
	<seg><keycombo><keycap>Ctrl</keycap> <keycap>y</keycap>
	  </keycombo></seg>
	<seg>Paste line</seg>
      </seglistitem>
      <seglistitem>
	<seg><keycombo><keycap>Ctrl</keycap> <keycap>s</keycap>
	  </keycombo></seg>
	<seg>Search forward in the file</seg>
      </seglistitem>
      <seglistitem>
	<seg><keycombo><keycap>Ctrl</keycap><keycap>r</keycap>
	  </keycombo></seg>
	<seg>Search backwards in the file</seg>
      </seglistitem>
      <seglistitem>
	<seg><keycombo><keycap>Meta</keycap><keycap>$</keycap>
	  </keycombo></seg>
	<seg>Check spelling of current word</seg>
      </seglistitem>
      <seglistitem>
	<seg><keycombo><keycap>Meta</keycap><keycap>x</keycap>
	  </keycombo> ispell-word, <keycap>Enter</keycap></seg>
	<seg>Check spelling of current word</seg>
      </seglistitem>
      <seglistitem>
	<seg><keycombo><keycap>Meta</keycap><keycap>x</keycap>
	  </keycombo> ispell-buffer, <keycap>Enter</keycap></seg>
	<seg>Check spelling of current buffer</seg>
      </seglistitem>
      <seglistitem>
	<seg><keycombo><keycap>Ctrl</keycap><keycap>x</keycap>
	  </keycombo>, <keycombo><keycap>Ctrl</keycap><keycap>f</keycap>
	  </keycombo></seg>	
	<seg>Open file</seg>		
      </seglistitem>
      <seglistitem>
	<seg><keycombo><keycap>Ctrl</keycap><keycap>x</keycap>
	  </keycombo>, <keycombo><keycap>Ctrl</keycap><keycap>s</keycap>
	  </keycombo></seg>
	<seg>Save file</seg>		
      </seglistitem>
      <seglistitem>
	<seg><keycombo><keycap>Ctrl</keycap><keycap>x</keycap>
	  </keycombo>, <keycombo><keycap>Ctrl</keycap><keycap>c</keycap>
	  </keycombo></seg>
	<seg>Exit <application>Emacs</application> and prompt to save
	  files if necessary</seg>
      </seglistitem>
      <seglistitem>
	<seg><keycombo><keycap>Meta</keycap> <keycap>q</keycap>
	  </keycombo></seg>
	<seg>Fill paragraph</seg>
      </seglistitem>
      <seglistitem>
	<seg><keycombo><keycap>Ctrl</keycap><keycap>c</keycap>
	  </keycombo>, <keycombo><keycap>Ctrl</keycap><keycap>a</keycap>
	  </keycombo></seg>
	<seg>Edit attributes for a tag (for example, you can edit the
	  <computeroutput>url</computeroutput> attribute of the
	  <computeroutput>ulink</computeroutput> tag)</seg>
      </seglistitem>
      <seglistitem>
	<seg><keycombo><keycap>Ctrl</keycap> <keycap>c</keycap>
		  </keycombo>,
	  <keycombo><keycap>Ctrl</keycap><keycap>c</keycap>
	  </keycombo></seg>
	<seg>Exit edit attributes</seg>
      </seglistitem>
      </segmentedlist>

    </section>

    <section id="sn-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>

      <section id="sn-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>&lt;</keycap>. At the bottom of the
	  <application>Emacs</application> window, you will see:
	</para>
<screen>
<computeroutput>Tag: &lt;</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>&lt;</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:
&lt;keycap&gt;                 &lt;keycode&gt;
&lt;keycombo&gt;               &lt;keysym&gt;
</computeroutput>
</screen>

      </section>
      <section id="sn-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>
      
      </section>

      <section id="sn-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>
      </section>
      
    </section>

    <section id="sn-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>
	  &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>
	<listitem>
	  <para>Read <citetitle>Editing XML with Emacs and PSGML</citetitle>
	    in <filename>/usr/share/doc/psgml-<replaceable>&lt;version&gt;</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>
	    &mdash; <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>
	    &mdash; <citetitle>PSGML Tricks</citetitle></para>
	</listitem>
      </itemizedlist>

    </section>
  </chapter>