\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename ../info/psgml.info
@settitle psgml
@c @setchapternewpage odd
@syncodeindex fn cp
@syncodeindex vr cp
@synindex ky cp
@c %**end of header
@c $Id: psgml.texi,v 1.1.1.1 1996/12/18 03:36:10 steve Exp $

@ifinfo
Documentation for PSGML, a major mode for SGML.

Copyright 1994 Lennart Staflin
     
Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

@ignore
Permission is granted to process this file through TeX
and print the results, provided the printed document
carries a copying permission notice identical to this
one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified
versions of this manual under the conditions for
verbatim copying, and provided that the entire
resulting derived work is distributed under the terms
of a permission notice identical to this one.

Permission is granted to copy and distribute
translations of this manual into another language,
under the above conditions for modified versions,
except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

@end ifinfo

@titlepage

@title Editing SGML with Emacs and PSGML
@author Lennart Staflin
     
@c  The following two commands
@c  start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1994 Lennart Staflin

@c Published by ...

Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

@ignore
Permission is granted to process this file through TeX
and print the results, provided the printed document
carries a copying permission notice identical to this
one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified
versions of this manual under the conditions for
verbatim copying, and provided that the entire
resulting derived work is distributed under the terms
of a permission notice identical to this one.

Permission is granted to copy and distribute
translations of this manual into another language,
under the above conditions for modified versions,
except that this permission notice may be stated in a
translation approved by the Free Software Foundation.
@end titlepage

@node  Top, Introduction, (dir), (dir)
@comment  node-name,  next,  previous,  up
@ifinfo
@top PSGML

PSGML is a major mode for editing SGML documents, with special
additions for HTML.  This is the DRAFT documentation for PSGML
version 1.0.
@end ifinfo

@menu
* Introduction::                Introduction
* Install::                     How to install PSGML
* Invoke::                      How to invoke PSGML
* Entity manager::              The Entity Manager
* Validate::                    Running an external SGML parser
* SGML declaration::            Using an SGML declaration
* Managing the DTD::            Specifying what DTD to use
* Edit::                        Commands for editing
* Display::                     Appearance of text in the buffer
* Bugs::                        Reporting bugs
* Index::                       
@end menu

@c ------------------------------------------------------------------

@node  Introduction, Install, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Introduction
@cindex CONCUR
@cindex DATATAG
@cindex LINK
@cindex RANK
@cindex SGML Declaration

PSGML is a major mode for editing SGML documents, and includes a number
of features for working specifically with HTML.  It works with GNU Emacs
19.19 and later or with Lucid Emacs 19.9 and later.  PSGML contains a
simple SGML parser and can work with any DTD.  Functions provided
includes menus and commands for inserting tags with only the
contextually valid tags, identification of structural errors, editing of
attribute values in a separate window with information about types and
defaults, and structure based editing.

SGML, a language for encoding the structure of a document, is an ISO
standard: ISO 8879:1986 ``Information processing -- Text and office
systems -- Standard Generalized Markup Language (SGML)''.

A good introduction to SGML is @cite{A Gentle Introduction to SGML}
produced by Text Encoding Initiative (this is really chapter 2 of TEI
P3). This can be found on
@file{ftp://ftp.ifi.uio.no/pub/SGML/TEI/P3SG.DOC}.

A SGML document has three major parts, in order:

@enumerate
@item
SGML Declaration (@samp{<!SGML "ISO 8879:1986" @dots{} >})
@item
Document Type Declaration (@samp{<!DOCTYPE @var{name} @dots{} >})
@item
Document Element (@samp{<@var{name}> @dots{} </@var{name}>})
@end enumerate

The SGML declaration contains general information about character sets,
concrete syntax, and SGML features used. PSGML does not use the SGML
Declaration, it can be left out, and if included is ignored. Many SGML
systems allow the SGML declaration to be defaulted.  PSGML always use
the Concrete Reference Syntax but without limitations on
lengths. Features used has to be indicated with variables (@pxref{SGML
declaration}).

The document type declaration specifies the valid elements and entities
and how they can be nested. A document type is usually needed, but can
reside in another file (@pxref{Managing the DTD}).

The system declaration for PSGML:
@format
SYSTEM "ISO 8879:1986"
   CHARSET
     BASESET  "ISO 646-1983//CHARSET
               International Reference Version (IRV)//ESC 2/5 4/0"
     DESCSET  0 128 0
     CAPACITY PUBLIC  "ISO 8879:1986//CAPACITY Reference//EN"
   FEATURES
     MINIMIZE DATATAG NO  OMITTAG  YES   RANK     NO  SHORTTAG YES
     LINK     SIMPLE  NO  IMPLICIT NO    EXPLICIT NO
     OTHER    CONCUR  NO  SUBDOC   YES 1 FORMAL   YES
     SCOPE    DOCUMENT
     SYNTAX   PUBLIC  "ISO 8879:1986//SYNTAX Reference//EN"
@c     SYNTAX   PUBLIC  "ISO 8879:1986//SYNTAX Core//EN"
     VALIDATE
              GENERAL NO  MODEL    NO   EXCLUDE  NO  CAPACITY NO
              NONSGML NO  SGML     NO   FORMAL   NO
     SDIF     PACK    NO  UNPACK   NO
@end format


@c -------------------------------------------------------------------------
@node Install, Invoke, Introduction, Top
@comment  node-name,  next,  previous,  up
@chapter Installing PSGML

Place the @file{*.el} and the @file{*.elc} files in a directory where
Emacs can find it (i.e. one of the directories in the @code{load-path}
variable, you can add a directory to this variable in your
@file{.emacs}.)  If you obtained PSGML without @file{*.elc} files, you
can create them by letting Emacs byte compile the @file{*.el} files (use
@kbd{M-x byte-compile-file}).  Parsing SGML in Emacs Lisp is slow and
needs all the speed it can get.

Put the following line in your .emacs:

@lisp
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
@end lisp

You may also want to set up search paths for external entities,
@xref{Entity manager}.

The @file{psgml.info} is the documentation for PSGML in the info format.
You can read this with the Emacs command @kbd{C-u C-h i}.  You can also
install the file in your systems info directory and edit the
@file{dir} file to include @file{psgml.info} in the menu.

The info file @file{psgml.info} is created from the texinfo file
@file{psgml.texi}.  The texinfo file can also be used to create a hard
copy of the documentation.  To do this you need the @TeX{} program and a
copy of @file{texinfo.tex}.




@c --------------------------------------------------------------------------
@node  Invoke, Entity manager, Install, Top
@comment  node-name,  next,  previous,  up
@chapter How to invoke PSGML
@cindex invoke
@cindex start up
@cindex major mode

@findex sgml-mode
PSGML defines a major mode called @code{sgml-mode}.  Files with
extensions @file{.sgml}, @file{.sgm} or @file{.dtd} will
automatically be edited in SGML mode.  To edit some other file in
sgml mode, type @kbd{M-x sgml-mode @key{RET}} after finding the
file.

If you can modify the file you can add a @dfn{Local Variables} list
(@pxref{file variables, , Local Variables in Files, emacs, The Emacs
Editor}) to the end of the file.  This can make Emacs
automatically set sgml mode and user options when the file is loaded.
The simplest Local Variables list would look like:

@example
<!--
Local Variables:
mode: sgml
End:
-->
@end example

You can also put a line at the top of the file to tell emacs to use sgml
mode:

@example
<!-- -*- sgml -*- -->
@end example

But remember that you can't have a comment before the @emph{SGML
declaration}.


@c -------------------------------------------------------------------------
@node  Entity manager, Validate, Invoke, Top
@comment node-name,  next,  previous,  up
@chapter The Entity Manager
@cindex public identifier
@cindex system identifier
@cindex external identifier

SGML can refer to an external file (really entity) with an
@emph{external identifier}, this is a @emph{public identifier} or a
@emph{system identifier}.

A typical public identifier looks like

@example
PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN"
@end example

@noindent
where ``ISO 8879:1986'' is the owner, ``ENTITIES'' is the text class and
``Added Latin 1'' is the text description (and ``EN'' is language).

A system identifier looks like

@example
SYSTEM "htmlplus.dtd"
@end example

@noindent where ``htmlplus.dtd'' is a system-specific identifier. 

To map external identifiers to file names, PSGML first searches entity
catalog files and then search the list of file name templates in the
variable @code{sgml-public-map}.

*** Describe the catalog format

The catalog format is according to SGML/Opens resoution on entity
management. The catalog consists of a series of entries and comment. A
comment is delimited by @samp{--} like in a markup declaration.
The entry types recognized are described in the following table.

@table @samp

@item PUBLIC @var{pubid} @var{file}
The @var{file} will be used for the entity text of an entity
with the public identifier @var{pubid}.

@item ENTITY @var{name} @var{file}
The @var{file} will be used for the entity text of an entity
with the name @var{name}. If the @var{name} starts with a @samp{%} the
rest of the name will be matched against parameter entities.

@item DOCTYPE @var{name} @var{file}
The DOCTYPE keyword indicates that an entity manager should use the
associated |storage object identifier| to locate the entity text
(to be used as the external subset) for a doctype declaration whose
document type name is specified by the |entity name spec|.

@item SGMLDECL @var{file}
The SGMLDECL keyword indicates that an entity manager should use
the associated |storage object identifier| to locate the entity
text to be used as the SGML declaration.

@end table

The @code{sgml-public-map} variable can contain a list of file name
templates where @samp{%P} will be substituted with the whole public
identifier, owner is substituted for @samp{%O}, public text class for
@samp{%C}, and public text description for @samp{%D}.  The text class
will be converted to lower case and the owner and description will be
transliterated according to the variable
@code{sgml-public-transliterations}.  The templates in the list is tried
in order until an existing file is found.

Given the public identifier above and the file name template 
@samp{/usr/local/lib/sgml/%o/%c/%d}, the resulting file name is

@example
/usr/local/lib/sgml/ISO_8879:1986/entities/Added_Latin_1
@end example

Note: blanks are transliterated to @samp{_} (and also @samp{/} to
@samp{%}) and the text class is down cased.



@defopt sgml-catalog-files
This is a list of catalog entry files.
The files are in the format defined in the SGML Open Draft Technical
Resolution on Entity Management.  The Emacs variable is initialized from
the environment variable @code{SGML_CATALOG_FILES} or if this variable
is undefined the default is

@lisp
("CATALOG" "/usr/local/lib/sgml/CATALOG")
@end lisp
@end defopt

@defopt sgml-local-catalogs
A list of SGML entity catalogs to be searched first when parsing the
buffer.  This is used in addition to @code{sgml-catalog-files}, and
@code{sgml-public-map}.  This variable is automatically local to the
buffer.
@end defopt

@defopt sgml-public-map
This should be a list of file name templates. This variable is
initialized from the environment variable @code{SGML_PATH}. This is
the same environment variable that @file{sgmls} uses.  If the
environment variable is undefined the default is

@lisp
("%S" "/usr/local/lib/sgml/%o/%c/%d")
@end lisp
@c Mapping from public identifiers to file names.
@end defopt

@c the colon separated list in @code{SGML_PATH} is converted to a lisp list

@c -------------------------------------------------------------------------
@node  Validate, SGML declaration, Entity manager, Top
@comment node-name,  next,  previous,  up
@chapter Running an external SGML parser

@kindex C-c C-v
@findex sgml-validate
PSGML can not validate an SGML document (see below what it can and can't
do).  If you have a validating SGML parser, like @file{sgmls}, you can
run the parser on your file with the command @kbd{C-c C-v}
(@code{sgml-validate}).

Some variables control this function:

@defopt sgml-validate-command
The shell command to validate an SGML document.

This is a @code{format} control string that by default should contain
two `%s' conversion specifications: the first will be replaced by the
value of @code{sgml-declaration} (or the empty string, if nil); the
second will be replaced by the current buffer's file name (or the empty
string, if nil).

If @code{sgml-validate-files} is non-nil, the format string should
contain one `%s' conversion specification for each element of its
result.

The default value is @code{sgml -s %s %s}.
@end defopt

@defopt sgml-validate-files
If non-nil, a function of no arguments that returns a list of file
names.  These file names will serve as the arguments to the
@code{sgml-validate-command} format control string instead of the
defaults.
@end defopt

@defopt sgml-declaration
The name of the SGML declaration file.
@end defopt

@defopt sgml-offer-save
If non-nil, @kbd{C-c C-v} (@code{sgml-validate}) will ask about saving
modified buffers before running the validate command.  The default value
is @code{t}.
@end defopt


@kindex C-c C-o
@findex sgml-next-trouble-spot
The built-in parser can find some markup errors.  The command @kbd{C-c
C-o} (@code{sgml-next-trouble-spot}) is the best way to use the built-in
parser for this.  To check the whole file go to the beginning of the
buffer and use @kbd{C-c C-o}.

Some of the markup errors not found are:

@itemize @bullet
@item
Errors in the SGML declaration.
@item
Errors in attribute specifications.
@item
Markup errors in entity replacement text.
@item
Omitted start-tags for empty elements.
@end itemize


@node SGML declaration, Managing the DTD, Validate, Top
@comment  node-name,  next,  previous,  up
@chapter SGML Declaration
@cindex SHORTTAG
@cindex OMITTAG

PSGML does not understand the SGML declaration, it accepts one in the
file but it is ignored.  If you have the SGML declaration in another
file you can make @file{sgmls} use it when you use the @kbd{C-c C-v}
(@code{sgml-validate}) command (@pxref{Validate}).

PSGML has some options in what features it uses and what markup it
creates.  You have to set these options to make PSGML's behavior
consistent with your SGML declaration and personal preferences.

@defopt sgml-omittag
Set this to @code{t} if the SGML declaration has @samp{OMITTAG YES} and
to @code{nil} otherwise.
@end defopt

@defopt sgml-shorttag
Set this to @code{t} if the SGML declaration has @samp{SHORTTAG YES} and
to @code{nil} otherwise.
@end defopt

@defopt sgml-always-quote-attributes
If non-nil, quote all attribute values inserted after finishing edit
attributes.  If this variable is @code{nil} and @code{sgml-shorttag} is
non-@code{nil}, attribute values that consists of only name characters
will not be quoted.
@end defopt

@defopt sgml-minimize-attributes
Determines minimization of attributes inserted by edit-attributes.  If
non-nil, omit attribute name if the attribute value is from a token
group.  If @code{max}, omit attributes with default value.  Minimization
will only be done if they produce legal SGML (assuming
@code{sgml-omittag} and @code{sgml-shorttag} are set correctly).
@end defopt


@c --------------------------------------------------------------------------
@node Managing the DTD, Edit, SGML declaration, Top
@comment  node-name,  next,  previous,  up
@chapter Document Type Declaration
@cindex DOCTYPE

@findex sgml-parse-prolog
PSGML needs to know about the DTD you are using for many of its commands.
You can use PSGML without specifying a DTD, it will then accept any tags
and assume a content model of @code{ANY} with no omissible tags.

If you have a @samp{DOCTYPE} declaration in your file, PSGML will try to
parse this.  Either the first time you do something that needs to parse
the document or with the command @code{sgml-parse-prolog}.  Big DTDs
take some time to parse.  

@vindex sgml-system-path
@vindex sgml-default-dtd-file
@vindex sgml-parent-document
You can have the @samp{DOCTYPE} declaration in another file either by
setting @code{sgml-parent-document} to the other file or by creating a
saved DTD and setting @code{sgml-default-dtd-file} to that file.  If
@code{sgml-default-dtd-file} contains a relative file name, the
directories in @code{sgml-system-path} will be searched for the file.


@findex sgml-save-dtd
@findex sgml-load-dtd
If parsing the DTD takes too long time you can save the parsed DTD in a
file using the command @kbd{M-x sgml-save-dtd}.  Next time PSGML can
load that file instead of parsing the DTD.  For PSGML to find the saved
DTD you must either save the DTD using the default name or do a @kbd{M-x
sgml-save-options} after saving the DTD.  To directly use an already
parsed and saved DTD, load the file containing the saved DTD with the
command @kbd{M-x sgml-load-dtd}.

When the DTD has been parsed or loaded the name of the document element
will be displayed in the mode line inside brackets.  If there was an
error parsing the DTD or there is no DTD, the mode line will display
@samp{[ANY]}.

@defopt sgml-default-dtd-file
This is the default file name for saved DTD.  This is set by
@code{sgml-mode} to the buffer file name less extension plus the
extension @code{.ced}, if that file exists.  Can be changed in the Local
variables section of the file.
@end defopt

@defopt sgml-parent-document
This can be set to the name (a string) of a file containing the
@samp{DOCTYPE} declaration to use, or a list @code{(@var{filename}
@var{doctypename})}, where @var{filename} is the name of a file
containing the @samp{DOCTYPE} declaration to use, with the modification
that the document type name is @var{doctypename}.
@end defopt

If you change the doctype you must execute @code{sgml-parse-prolog},
changes in the doctype are not automatically recognized.

@defopt sgml-custom-dtd
Menu entries to be added to the DTD menu.  The value should be a list of
entries to be added to the DTD menu.

Every entry should be a list. The first element of the entry is a string
used as the menu entry.  The second element is a string containing a
doctype declaration (this can be nil if no doctype).  The rest of the
list should be a list of variables and values.  For backward
compatibility a single string instead of a variable is assigned to
@code{sgml-default-dtd-file}.  All variables are made buffer local and
are also added to the buffers local variables list.

When an entry is selected from the DTD menu, the doctype declaration will
be inserted, the variables will be set to the values in the entry and a
local variables list will be created in the buffer.

Example:

@example
   (("HTML" nil
     sgml-default-dtd-file "~/sgml/html.ced"
     sgml-omittag nil sgml-shorttag nil)
    ("HTML+" "<!doctype htmlplus system 'htmlplus.dtd'>"
     "~/sgml/htmlplus.ced"
     sgml-omittag t sgml-shorttag nil)
    ("DOCBOOK" "<!doctype docbook system 'docbook.dtd'>"
     "~/sgml/docbook.ced"
     sgml-omittag nil sgml-shorttag t)))
@end example
@end defopt

@c ---------------------------------------------------------------------------
@node  Edit, Display, Managing the DTD, Top
@comment  node-name,  next,  previous,  up
@chapter Commands for editing

@menu
* Insert::                      Inserting Markup
* Complete::                    Markup completion
* Information::                 Showing information
* Indent::                      Indentation according to structure
* Move::                        Move in the element structure
* Attributes::                  Editing attributes
* Change and delete::           Changing and deleting markup
@end menu

@c ------------------------------------------------------------------
@node Insert, Complete, Edit, Edit
@comment  node-name,  next,  previous,  up
@section Inserting Markup

@c erik says "inserts" ??
The commands that insert start-tags works only if the document has an
associated DTD.

Keyboard commands for inserting:

@table @kbd
@kindex C-c <
@findex sgml-insert-tag
@item C-c <
Will ask, for the tag to insert, in the mini-buffer with completion on the 
tags that are valid at point (@code{sgml-insert-tag}).

If the option @code{sgml-balanced-tag-edit} is non-nil, inserting a
start-tag will also insert the corresponding end-tag.  If, in addition,
@code{sgml-auto-insert-required-elements} is non-nil, tags for elements
required between the inserted tags will also be inserted.

The list of valid tags, computed for a position in the buffer, will
contain:

@enumerate
@item
The end-tag for the current element, if it can be ended at the position
and @code{sgml-balanced-tag-edit} is nil.  Furthermore it will contain
end-tags for enclosing elements if the necessary omissible end-tag
declarations have been made in the DTD.

@item
The start-tags of all elements that could occur after point.  If
@code{sgml-omittag-transparent} is nil, the above will be limited to the
elements that can occur within the current element.
@end enumerate


@kindex C-c C-e
@findex sgml-insert-element
@item C-c C-e
Insert start and end-tags for an element (@code{sgml-insert-element}).
The name of the element is read from the mini-buffer with completion on
valid elements.

If @code{sgml-omittag-transparent} is nil, the list of valid elements
will only contain the elements that can be in the content of the current
element.

Required elements in the content will be automatically inserted if the
option @code{sgml-auto-insert-required-elements} is non-nil.

@kindex C-c C-r
@findex sgml-tag-region
@item C-c C-r
Makes the region into a new element (@code{sgml-tag-region}).  Reads
element name from mini-buffer with completion as for @kbd{C-c C-e}.

@kindex C-c /
@findex sgml-insert-end-tag
@item C-c /
Inserts an end-tag for the current element (@code{sgml-insert-end-tag}).

@kindex C-c RET
@findex sgml-split-element
@item C-c RET
Split the current element at point.  If repeated, the containing element
will be split before the beginning of then current element.

Typical use is to start a new paragraph element when inside a paragraph.

@kindex C-c +
@findex sgml-insert-attribute
@item C-c +
Read attribute name and value from mini-buffer and insert attribute
specification (@code{sgml-insert-attribute}).  If point is immediately
after a start-tag, this command operates on that start-tag.  Otherwise
the command will operate on the element after point.

The attribute name will be read with completion.  If the attribute has a
token list as declared value the attribute value will also be read with
completion.  The prompt for attribute value will typically look like:

@example
Value for @var{attribute} (@var{type} Default: @var{current value}):
@end example

@end table

Menu bar:

@table @samp
@item Markup
Selecting from this menu will insert markup.  The menu contains
sub menus with tags and with entities, some other markup and a user
defined section.

Sub menus:

@item Insert element
Pops up a menu of valid elements and insert start and end-tags for
the selected element.  Selections from the menu works like the @kbd{C-c
C-e} command.

@item Insert start-tag
Pops up a menu of valid start-tags and insert the selected tag.  The
menu has the same start-tags as the completion list for @kbd{C-c <}.

@item Insert end-tag
Pops up a menu of valid end-tags and insert the selected tag. 

@item Tag region
Pops up a menu of valid elements and tag the region with the
selection.  Selections from the menu works like the @kbd{C-c C-r}
command.

@item Insert entity
Menu of all general entities defined in the DTD.

@item Insert attribute
Pops up a menu with all the attributes of an element.  The element is
either the one which start-tag is immediately before point or the
element after point.  Selecting from this menu edits the attribute
specification list for the element.

The menu has a sub menu for every attribute which declared value is a
token list.  The rest of the attributes are collected in one sub menu.
For the token list attributes, selecting a value will insert that
attribute-value pair.  Selecting some other attribute reads the
attribute-value from the mini-buffer and inserts the attribute value
pair.
@end table

@kindex S-@key{mouse-1}
A menu is also available directly with a mouse button click in the
buffer.  In GNU Emacs it is the first mouse button combined with shift
(@kbd{S-@key{mouse-1}}).  In Lucid Emacs it is bound to the third mouse
button.  The mouse button click will pop-up a menu of valid tags or a
menu of attributes if the point is in a start-tag.  The attributes menu
works as the ``Insert attribute'' menu from the menu-bar.  The tags list
is the list of valid tags described above for command @kbd{C-c <}.
Selection from the tags menu works like the @kbd{C-c <} command, with
the following exception:

You can tag a region, with start and end-tag.  There are two ways to
indicate the region to mark:

@enumerate
@item
Use the normal mouse commands to mark region.  

For this to work you must either use @dfn{transient mark mode}
(@pxref{Transient Mark, , Transient Mark Mode, emacs, The Emacs
Editor}) or set the option @code{sgml-tag-region-if-active} to non-nil
(don't set this unless you are sure that you want it).

@item
Alternatively make a secondary selection, this is done by holding down
the meta key and using the mouse buttons.  
@xref{Secondary selection, , , emacs, The Emacs Editor}.
Some window managers intercept these events, which makes it hard use the
secondary selection in Emacs.
@end enumerate

@defopt sgml-balanced-tag-edit
If non-nil, inserting a start-tag will also insert the corresponding
end-tag.
@end defopt

@defopt sgml-auto-insert-required-elements
If non-nil, automatically inserts required elements in the content
of an inserted element.
@end defopt

@defopt sgml-omittag-transparent
If non-nil, will show legal tags inside elements with omissible start-tags
and legal tags beyond omissible end-tags.
@end defopt

@defopt sgml-tag-region-if-active
If non-nil, the @samp{Insert tags} menu will tag a region if the region
is considered active by emacs.  If nil, region must be active and
@code{transient-mark-mode} must be on for the region to be tagged.
@end defopt

@defopt sgml-custom-markup
Menu entries to be added to the Markup menu.  The value should be a list
of lists of two strings.  The first string is the menu line and the
second string is the text inserted when the menu item is selected.  The
second string can contain a @samp{\r} where the cursor should be left.
Also, if a selection is made according to the same rules as for the
@kbd{S-mouse-1} menu, the selection is replaced with the second string
and @samp{\r} is replaced with the selection.

Example:

@example
  (("Version1" "<![%Version1[\r]]>")
   ("New page"  "<?NewPage>"))
@end example
@end defopt


@c -------------------------------------------------------------------------
@node Complete, Information, Insert, Edit
@comment  node-name,  next,  previous,  up
@section Markup completion

@kindex M-TAB
@findex sgml-complete
If you are typing in markup directly, @kbd{M-TAB} will help you by
completing a tag name, an entity name or a markup declaration name.  If
you type @kbd{M-TAB} after a plain word, @code{ispell-complete-word}
will be invoked instead.

If you have typed (@point{} marks the position of point)

@example
&At@point{}
@end example

@noindent and type @kbd{M-TAB} (assuming you use the @file{ISOLat1}
entity set) you get:

@example
&Atilde@point{}
@end example


@c ---------------------------------------------------------------------------
@node Information, Indent, Complete, Edit
@comment  node-name,  next,  previous,  up
@section Showing information

Commands for showing information obtained by parsing the buffer.

@table @kbd
@kindex C-c C-c
@findex sgml-show-context
@item C-c C-c
Shows in the message area: context at point, if in a tag or in mixed
content and the open elements (@code{sgml-show-context}).

@kindex C-c C-w
@findex sgml-what-element
@item C-c C-w
Shows what element the character after point (under the cursor) belongs
to; also shows context of element (@code{sgml-what-element}).

@kindex C-c C-t
@findex sgml-list-valid-tags
@item C-c C-t
List contextually valid tags (@code{sgml-list-valid-tags}).  Displays
information about current element, all valid end-tags, valid start-tags
in current element, and start-tags valid at this point but in other
elements together with the tags omitted.
@end table

You can make the mode-line display the name of the current open element
by setting the @code{sgml-live-element-indicator} variable.  Setting
this will make all commands slower due to the work needed to keep the
mode-line up to date.

@defopt sgml-live-element-indicator
If non-nil, indicate current element in mode line.

NOTE: Setting this implies that every command can cause a parse.  
@end defopt



@c --------------------------------------------------------------------------
@node  Indent, Move, Information, Edit
@comment  node-name,  next,  previous,  up
@section Indentation according to structure

@kindex @key{TAB}
@kindex @key{LFD}
@findex sgml-indent-or-tab
@findex newline-and-indent
You can indent a line according to the depth of element nesting at the
beginning of the line.  To indent the current line use @kbd{@key{TAB}}.
You can also use @kbd{@key{LFD}} (@code{newline-and-indent}) to start a
new line with correct indentation.

@defopt sgml-indent-step
How much to increment indent for every element level.  If nil, no
indentation.

If this is nil, @kbd{@key{TAB}} will insert a tab instead of indenting.
@end defopt

@defopt sgml-indent-data
If non-nil, indent in data/mixed context also.
@end defopt



@c ---------------------------------------------------------------------------
@node  Move, Attributes, Indent, Edit
@comment  node-name,  next,  previous,  up
@section Move in the element structure

These commands move in the element structure.  The commands uses
knowledge of SGML syntax, and if available the specific DTD.

@table @kbd
@kindex C-M-a
@findex sgml-beginning-of-element
@item C-M-a
Move to the (content) beginning of the current element
(@code{sgml-beginning-of-element}).

@kindex C-M-e
@findex sgml-end-of-element
@item C-M-e
Move to the (content) end of the current element (@code{sgml-end-of-element}).

@kindex C-M-f
@findex sgml-forward-element
@item C-M-f
Move forward by element (@code{sgml-forward-element}).

@kindex C-M-b
@findex sgml-backward-element
@item C-M-b
Move backward by element (@code{sgml-backward-element}).

@kindex C-M-u
@findex sgml-backward-up-element
@item C-M-u
Move up to before current element (@code{sgml-backward-up-element}).

@kindex C-c C-n
@findex sgml-up-element
@item C-c C-n
Move up to after current element (@code{sgml-up-element}).

@kindex C-M-d
@findex sgml-down-element
@item C-M-d
Move down to the (content) beginning of the next element
(@code{sgml-down-element}).

@kindex C-c C-d
@findex sgml-next-data-field
@item C-c C-d
Move to the next place where data is allowed (@code{sgml-next-data-field}).
@end table

You can also move to the next place where there is some structural error
with @kbd{C-c C-o} (@pxref{Validate}).


@c ---------------------------------------------------------------------------
@node Attributes, Change and delete, Move, Edit
@comment  node-name,  next,  previous,  up
@section Editing attributes

@findex sgml-edit-attributes
@kindex C-c C-a
If you want to change the attributes of a start-tag you can simply edit
them directly in the buffer.  Or you can place the cursor at or after
the start-tag and use the @code{sgml-edit-attributes} command, available
from the @samp{SGML}-menu or on @kbd{C-c C-a}.  This will create a new
Emacs window with all possible attributes listed in the form

@example
@var{attribute name} = @var{current value}.
@end example

The @var{current value} may be shown as @samp{#DEFAULT} if the attribute
has not been given a value in the start-tag.  The list also contains the
attributes declaration as a comment.  Note also that the @var{current
value} is show without eventual quotes.

@kindex C-c C-d
@kindex @key{TAB}
It is now possible to edit the attribute values.  You can move to the
next attribute with @kbd{@key{TAB}}.  If you want to let an attribute
have its default value use @kbd{C-c C-d}, this will insert a
@samp{#DEFAULT} in the value field.

If Emacs is running in an X window, the @samp{#DEFAULT} will be
underlined to distinguish it from normal values.

@kindex C-c C-c
Finish the editing with @kbd{C-c C-c}; this will replace the attribute
values in the main buffer with those edited.  Note that values will be
quoted as needed.

If you want to abort the editing, you can remove the window with
@kbd{C-x 0} or if you want it neat, kill the buffer and remove the
window.

Some other keys are:
@table @kbd
@kindex C-a
@findex sgml-edit-attrib-field-start
@item C-a
Go to the beginning of the value field
(@code{sgml-edit-attrib-field-start}).

@kindex C-e
@findex sgml-edit-attrib-field-end
@item C-e
Go to the end of the value field
(@code{sgml-edit-attrib-field-end}).

@kindex C-c C-k
@findex sgml-edit-attrib-clear
@item C-c C-k
Clear the value field
(@code{sgml-edit-attrib-clear}).

@kindex C-c C-d
@findex sgml-edit-attrib-default
@item C-c C-d
Set the value field to @samp{#DEFAULT}
(@code{sgml-edit-attrib-default}).  This is a special value that will
make the attribute be implied.
@end table


@c --------------------------------------------------------------------------
@node Change and delete,  , Attributes, Edit
@comment  node-name,  next,  previous,  up
@section Changing and deleting markup

@table @kbd
@kindex C-c =
@findex sgml-change-element-name
@item C-c =
Change the name of the current element (@code{sgml-change-element-name}).
Tries to translate attribute specifications.  An attribute will be
translated to an attribute with the same name.  If the new element has
no attribute with the same name, the attribute will be ignored.  If
there is an attribute with the same name but different declared content,
a warning is given.

ID attributes are handled specially, an attribute with declared value ID
will always be translated to the attribute with declared value ID.

@kindex C-c C-k
@findex sgml-kill-markup
@item C-c C-k
Kill next tag, markup declaration or process instruction
(@code{sgml-kill-markup}).

@kindex C-M-k
@findex sgml-kill-element
@item C-M-k
Kill the element following the cursor (@code{sgml-kill-element}).

@kindex C-c -
@findex sgml-untag-element
@item C-c -
Remove tags from current element (@code{sgml-untag-element}).

@kindex C-c #
@findex sgml-make-character-reference
@item C-c #
Convert character after point to a character reference
(@code{sgml-make-character-reference}).  If called with a numeric
argument, convert a character reference back to a normal character.

@kindex C-c C-q
@findex sgml-fill-element
@item C-c C-q
Fills an element as a paragraph (@code{sgml-fill-element}).  This is a
substitute for the normal @code{fill-paragraph}.  The command uses
heuristics to decide what should be a paragraph.

@enumerate
@item
If point is in an element content, recursively fill the sub-elements.
@item
Find the biggest element with mixed content containing point.
@item
If the above element is mixed but contains elements with pure element
content then fill what is between the pure elements as paragraphs and
fill the pure elements recursively.
@end enumerate


@findex sgml-normalize
@item M-x sgml-normalize
Normalize the document in the buffer.  This will

@enumerate
@item
insert missing tags,
@item
replace minimized tags with full tags,
@item
fix attribute specification lists according to options set.
@end enumerate

There is one option for the normalize command.  With its default value,
normalize may actually change the data content of some elements.  But
only by removing some white-space from the end of elements with omitted
end-tags.
@end table

@defopt sgml-normalize-trims
If non-nil, @code{sgml-normalize} will trim off white space from end of
element when adding end-tag.

Default: @code{t}.
@end defopt


@c ---------------------------------------------------------------------------
@node Display, Bugs, Edit, Top
@comment  node-name,  next,  previous,  up
@chapter Appearance of text in the buffer

@menu
* Fold::                        Folding editing
* Highlight::                   Highlighting markup
@end menu

@c ---------------------------------------------------------------------------
@node  Fold, Highlight, Display, Display
@comment  node-name,  next,  previous,  up
@section Folding editing

With these commands you can make parts of the text temporarily invisible
to make it easier to see the overall structure of your text.  

When folding a region all the lines but the first will be invisible.
The first line of the region will still be visible with an ellipsis at
the end.

@xref{Outline Mode, , , emacs, The Emacs Editor}.

@table @kbd
@kindex C-c C-f C-r
@findex sgml-fold-region
@item C-c C-f C-r
The region between point and mark will be folded (@code{sgml-fold-region}).

@kindex C-c C-f C-e
@findex sgml-fold-element
@item C-c C-f C-e
The region between the start and end of the current element will be
folded (@code{sgml-fold-element}).

This command can also fold the SGML declaration or the DOCTYPE
declaration.

@kindex C-c C-f C-s
@findex sgml-fold-subelement
@item C-c C-f C-s
Fold all the sub elements of the current element
(@code{sgml-fold-subelement}).

@kindex C-c C-s
@kindex C-c C-u C-l
@findex sgml-unfold-line
@item C-c C-s
@itemx C-c C-u C-l
Unfold the current line, assuming it is the first line of a folded
region (@code{sgml-unfold-line}).

@kindex C-c C-u C-e
@findex sgml-unfold-element
@item C-c C-u C-e
Make all lines in current element visible (@code{sgml-unfold-element}).

@kindex C-c C-u C-a
@findex sgml-unfold-all
@item C-c C-u C-a
Make all lines in current buffer visible (@code{sgml-unfold-all}).

@kindex C-c C-f C-x
@findex sgml-expand-element
@item C-c C-f C-x
Unfold current element and then fold the subelements
(@code{sgml-expand-element}).  If the current element is folded this
expands what is visible.
@end table




@c ---------------------------------------------------------------------------
@node  Highlight,  , Fold, Display
@comment  node-name,  next,  previous,  up
@section Highlighting markup


PSGML can highlight the markup as it parses it by giving the markup a
different @dfn{face} (@pxref{Faces, , Using Multiple Typefaces, emacs,
The Emacs Editor}).  The highlighting will only be done if the variable
@code{sgml-set-face} is non-nil.  The default settings make tags bold
and comments italic, but this can be modified with the variable
@code{sgml-markup-faces}.

@findex sgml-clear-faces
To remove the highlighting type @kbd{M-x sgml-clear-faces}.

@defopt sgml-set-face
If non-nil, psgml will set the face of parsed markup.
@end defopt

@defopt sgml-markup-faces
A list of markup to face mappings.
Each element looks like @code{(@var{markup-type} . @var{face})}.
Possible values for @var{markup-type} is:

@table @code
@item comment
comment declaration
@item doctype
doctype declaration
@item end-tag
end-tag 
@item ignored
ignored marked section
@item ms-start
marked section end, if not ignored
@item ms-end
marked section start, if not ignored 
@item pi
processing instruction
@item sgml
SGML declaration
@item start-tag
start-tag
@item entity
entity reference
@item shortref
short reference
@end table
@end defopt

@c ------------------------------------------------------------------
@node Bugs, Index, Display, Top
@comment  node-name,  next,  previous,  up
@chapter Bugs


If you encounter something that you think is a bug, please report
it.  Try to include a clear description of the undesired behaviour.
A test case that exhibits the bug, would also be useful.

You can report a bug with the command @kbd{M-x sgml-submit-bug-report}.

When PSGML needs contextual information it parses the document up to
the point. During the parsing, it builds a parse tree.  The parse
tree is used to initialize the next parse, to avoid having to parse
things already parsed.  Changes to the buffer is supposed to prune
the tree of all outdated information.  But if you get strange
complaints from the parser, try and back up a bit and use @kbd{C-c
C-o} (@code{sgml-next-trouble-spot}).



@c ------------------------------------------------------------------
@node Index,  , Bugs, Top
@comment    node-name,         next,       previous, up
@chapter Index
     
@printindex cp

@bye