2.3. Emacs/PSGML tips

Preparing Cogent Documentation :
	Chapter 2. Making Edits in doc/i/

You can edit SGML source code with any text editor, but I recommend Emacs running in PSGML mode. This mode reads in the DocBook document type definition (DTD), and uses it to help you write well-formed SGML/XML. For example, you can color-code tags, quickly modify SGML markup, and validate your documents with it.

Here are some tips to help you get the most out of Emacs in PSGML mode.

2.3.1. Settings in `.emacs`

The following settings facilitate tagging, and color the SGML tags, making it easier to distinguish text from tags.

(add-hook 'sgml-mode-hook   ; make all this stuff SGML-specific
        (function (lambda()

; Create faces to assign to markup categories.
(make-face 'sgml-comment-face)
(make-face 'sgml-start-tag-face)
(make-face 'sgml-end-tag-face)

; Assign attributes to faces.
(set-face-foreground 'sgml-comment-face "SeaGreen")
(set-face-foreground 'sgml-start-tag-face "OrangeRed")
(set-face-foreground 'sgml-end-tag-face "OrangeRed")

; Assign faces to markup categories.
(setq sgml-markup-faces
      '((comment . sgml-comment-face)
	(start-tag . sgml-start-tag-face)
	(end-tag . sgml-end-tag-face)))

; Tell PSGML to use the face settings.
(setq sgml-set-face t)

; Only allows valid elements to be inserted.
(setq sgml-omittag-transparent t)

; PSGML automatically inserts required elements.
(setq sgml-auto-insert-required-elements t)

; Enable abbreviations
(setq-default abbrev-mode t)
(read-abbrev-file "~/.abbrev_defs")
(setq save-abbrevs t)

)))

2.3.2. Some important Emacs/PSGML key bindings

There are many key bindings in Emacs/PSGML mode, but you should be able work quite well with just these:

C-c C-v (sgml-validate) validates a document. It must be done from the main document file, the one with the DTD declaration at the top. (For our documents that's usually doc/o/*/main.sgml.)
C-c C-r (sgml-tag-region) tags a region of marked text. The system prompts for a tag name and will not accept an invalid one. You can use the Tab key for auto-fill for the name.
C-c C-e (sgml-insert-element) prompts for a tag name, and then puts an empty element (start and end tags) at the point at the cursor location. The system checks for valid entries, and offers auto-fill.
C-c = (sgml-change-element-name) only works if the cursor is inside the element's start or end tag. It prompts for a new tag name and changes the element to what you enter. The system checks for valid entries, and offers auto-fill.
C-c - (sgml-untag-element) removes the tags of an element. The cursor must be inside the element's start or end tag.
ESC C-k (sgml-kill-element) removes the entire element with all its children, text, and tags intact. This is useful for moving whole chunks of tagged text within and between documents. The cursor must be positioned before the start tag of the element.
C-c RET (sgml-split-element) inserts an end tag for the current element followed by a beginning tag for the same kind of element, effectively splitting the element at that point. This is an easy way to make two paragraphs. The cursor must be between (and not inside) the start and end tags of the element.


2.2. Elements and tags		2.4. Entities