This is psgml.info, produced by makeinfo version 4.2 from
/Users/lenst/src/psgml/doc/psgml.texi.
START-INFO-DIR-ENTRY
* PSGML: (psgml). PSGML, a major mode for SGML documents.
END-INFO-DIR-ENTRY
Documentation for PSGML, a major mode for SGML.
Copyright 1994, 1996, 1998 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.
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.
File: psgml.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
PSGML
*****
PSGML is a major mode for editing SGML documents. This is the
DRAFT documentation for PSGML version 1.4.
* 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
* Miscellaneous options::
* Bugs:: Reporting bugs
* Index::
File: psgml.info, Node: Introduction, Next: Install, Prev: Top, Up: Top
Introduction
************
PSGML is a major mode for editing SGML and XML documents. It
works with GNU Emacs 19.34, 20.3 and later or with XEmacs 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 `A Gentle Introduction to SGML'
produced by Text Encoding Initiative (this is really chapter 2 of TEI
P3). This can be found on
`ftp://ftp.ifi.uio.no/pub/SGML/TEI/P3SG.DOC'.
A SGML document has three major parts, in order:
1. SGML Declaration (`')
2. Document Type Declaration (`')
3. Document Element (` ... ')
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 (*note
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 (*note Managing the DTD::).
The system declaration for PSGML:
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"
VALIDATE
GENERAL NO MODEL NO EXCLUDE NO CAPACITY NO
NONSGML NO SGML NO FORMAL NO
SDIF PACK NO UNPACK NO
File: psgml.info, Node: Install, Next: Invoke, Prev: Introduction, Up: Top
Installing PSGML
****************
To install PSGML you first need to uncompress and unpack the source
archive. This is done with the `gunzip' and `tar' commands.
gunzip psgml-1.2.0.tar.gz; tar xf psgml-1.2.0.tar
This should create a subdirectory to the current directory with the
source code. This directory contains a `configure' command (see the
file INSTALL for more information about configure). You can use the
`configure' command to configure the package or you can load the file
`psgml-maint' and execute the `psgml-compile-files' command.
Place the `*.el' and the `*.elc' files in a directory where Emacs
can find it (i.e. one of the directories in the `load-path' variable,
you can add a directory to this variable in your `.emacs'.)
If you use the `configure' approach, compile psgml with `make' and
the you can run `make install' to install it in the system library
`site-lisp'. The location of `site-lisp' is figured out by
`configure', but you can change it in the `Makefile'.
Put the following line in your .emacs:
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t)
(autoload 'xml-mode "psgml" "Major mode to edit XML files." t)
You may also want to set up search paths for external entities,
*Note Entity manager::.
The `psgml.info' is the documentation for PSGML in the info format.
You can read this with the Emacs command `C-u C-h i'. You can also
install the file in your systems info directory and edit the `dir'
file to include `psgml.info' in the menu.
The info file `psgml.info' is created from the texinfo 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 `texinfo.tex'.
File: psgml.info, Node: Invoke, Next: Entity manager, Prev: Install, Up: Top
How to invoke PSGML
*******************
PSGML defines major modes called `sgml-mode' and `xml-mode'.
Files with extensions `.sgml', `.sgm' or `.dtd' will automatically be
edited in SGML mode. To edit some other file in SGML mode, type `M-x
sgml-mode ' after finding the file. To edit XML files, type
`M-x xml-mode '.
If you can modify the file you can add a "Local Variables" list
(*note Local Variables in Files: (emacs)file variables.) 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:
You can also put a line at the top of the file to tell emacs to
use sgml mode:
For XML replace `sgml' with `xml' in the above examples. But
remember that you can't have a comment before the _SGML declaration_
or the _XML declaration_.
File: psgml.info, Node: Entity manager, Next: Validate, Prev: Invoke, Up: Top
The Entity Manager
******************
SGML can refer to an external file (really entity) with an
_external identifier_, this is a _public identifier_ or a _system
identifier_, or both.
A typical public identifier looks like
PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN"
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
SYSTEM "htmlplus.dtd"
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 `sgml-public-map'.
The catalog format is according to SGML/Opens resolution on entity
management. The catalog consists of a series of entries and
comments. A comment is delimited by `--' like in a markup
declaration. The entry types recognized are described in the
following table.
`public PUBID FILE'
The FILE will be used for the entity text of an entity with the
public identifier PUBID.
`entity NAME FILE'
The FILE will be used for the entity text of an entity with the
name NAME. If the NAME starts with a `%' the rest of the name
will be matched against parameter entities.
`doctype NAME FILE'
The FILE will be used for the entity text of an entity used as
external subset of a document declaration with NAME as document
type name.
`sgmldecl FILE'
Used to specify a default SGML declaration. Recognized but not
used by PSGML other than to pass to an external validation
command (`sgml-validate-command').
When PSGML is looking for the file containing an external entity,
the following things will be tried in order:
1. Try the system identifier, as a file name, if there is a system
identifier and the variable
`sgml-system-identifiers-are-preferred' is non-`nil' and there
is no elements containing `%s' in `sgml-public-map'. If the
system identifier is a relative file name it will be relative to
the directory containing the defining entity.
2. Look thru each catalog in `sgml-local-catalogs' and
`sgml-catalog-files' in order. For each catalog look first for
entries matching the public identifier, if any. Then look for
other matching entries in the order they appear in the catalog.
Currently an entry will be ignored if it is matching but its
file is non-existent or unreadable. (This is under
reconsideration, perhaps it should signal error instead).
3. Try the system identifier, if any, as a file name. If
`sgml-system-identifiers-are-preferred' is `nil' and there is no
elements containing `%s' in `sgml-public-map'.
4. Try the entries in `sgml-public-map'. Using the catalogs are
preferred. The `sgml-public-map' may disappear in a future
version of PSGML (not soon though).
The `sgml-public-map' variable can contain a list of file name
templates where `%P' will be substituted with the whole public
identifier, owner is substituted for `%O', public text class for
`%C', and public text description for `%D'. The text class will be
converted to lower case and the owner and description will be
transliterated according to the variable
`sgml-public-transliterations'. The templates in the list is tried
in order until an existing file is found. The `sgml-public-map' is
modeled after `sgmls' environment variable `SGML_PATH' and psgml
understand the following substitution characters: %%, %N, %P, %S, %Y,
%C, %L, %O, %T, and %V. The default value of `sgml-public-map' is
taken from the environment variable `SGML_PATH'.
Given the public identifier above and the file name template
`/usr/local/lib/sgml/%o/%c/%d', the resulting file name is
/usr/local/lib/sgml/ISO_8879:1986/entities/Added_Latin_1
Note: blanks are transliterated to `_' (and also `/' to `%') and
the text class is down cased.
- User Option: 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 `SGML_CATALOG_FILES' or if this variable is
undefined the default is
("CATALOG" "/usr/local/lib/sgml/CATALOG")
- User Option: sgml-local-catalogs
A list of SGML entity catalogs to be searched first when parsing
the buffer. This is used in addition to `sgml-catalog-files',
and `sgml-public-map'. This variable is automatically local to
the buffer.
- User Option: sgml-system-identifiers-are-preferred
If `nil', PSGML will look up external entities by searching the
catalogs in `sgml-local-catalogs' and `sgml-catalog-files' and
only if the entity is not found in the catalogs will a given
system identifier be used. If the variable is non-nil and a
system identifier is given, the system identifier will be used
for the entity. If no system identifier is given the catalogs
will searched.
- User Option: sgml-public-map
This should be a list of file name templates. This variable is
initialized from the environment variable `SGML_PATH'. This is
the same environment variable that `sgmls' uses. If the
environment variable is undefined the default is
("%S" "/usr/local/lib/sgml/%o/%c/%d")
File: psgml.info, Node: Validate, Next: SGML declaration, Prev: Entity manager, Up: Top
Running an external SGML parser
*******************************
PSGML can not validate an SGML document (see below what it can and
can't do). If you have a validating SGML parser, like `sgmls', you
can run the parser on your file with the command `C-c C-v'
(`sgml-validate').
Some variables control this function:
- User Option: sgml-validate-command
The shell command to validate an SGML document.
This is a `format' control string that by default should contain
two `%s' conversion specifications: the first will be replaced
by the value of `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 `sgml-validate-files' is non-nil, the format string should
contain one `%s' conversion specification for each element of
its result.
If sgml-validate-command is a list, then every element should be
a string. The strings will be tried in order and `%'-sequences
in the string will be replaced according to the list below, if
the string contains `%'-sequences with no replacement value the
next string will be tried.
`%b'
means the visited file of the current buffer
`%s'
means the SGML declaration specified in the
sgml-declaration variable
`%d'
means the file containing the DOCTYPE declaration, if not
in the buffer
The default value is `nsgmls -s %s %s'.
- User Option: 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
`sgml-validate-command' format control string instead of the
defaults.
- User Option: sgml-declaration
The name of the SGML declaration file.
- User Option: sgml-offer-save
If non-nil, `C-c C-v' (`sgml-validate') will ask about saving
modified buffers before running the validate command. The
default value is `t'.
The built-in parser can find some markup errors. The command `C-c
C-o' (`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 `C-c C-o'.
Some of the markup errors not found are:
* Errors in the SGML declaration.
* Errors in attribute specifications.
* Omitted start-tags for empty elements.
File: psgml.info, Node: SGML declaration, Next: Managing the DTD, Prev: Validate, Up: Top
SGML Declaration
****************
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 `sgmls' use it when you use the `C-c C-v'
(`sgml-validate') command (*note 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.
- User Option: sgml-omittag
Set this to `t' if the SGML declaration has `OMITTAG YES' and to
`nil' otherwise.
- User Option: sgml-shorttag
Set this to `t' if the SGML declaration has `SHORTTAG YES' and
to `nil' otherwise.
- User Option: sgml-namecase-general
Set this to `t' if the SGML declaration has `NAMECASE GENERAL
YES' and to `nil' otherwise. I.e., this controls whether names,
except entity names, will be case insensitive (translated to
upper case).
- User Option: sgml-always-quote-attributes
If non-nil, quote all attribute values inserted after finishing
edit attributes. If this variable is `nil' and `sgml-shorttag'
is non-`nil', attribute values that consists of only name
characters will not be quoted.
- User Option: 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 `max', omit
attributes with default value. Minimization will only be done
if they produce legal SGML (assuming `sgml-omittag' and
`sgml-shorttag' are set correctly).
File: psgml.info, Node: Managing the DTD, Next: Edit, Prev: SGML declaration, Up: Top
Document Type Declaration
*************************
PSGML needs to know about the DTD you are using for many of its
commands. If you do not have a `DOCTYPE' declaration in your file,
PSGML will try assume that there is one of the form
where NAME is the value of `sgml-default-doctype-name', if the
value is non-`nil', else the GI of the first tag will be used.
PSGML will try to parse the document type declaration the first
time you do something that needs to parse the document or immediately
if the variable `sgml-auto-activate-dtd' is `t'. You can also
initiate the parsing of the document type declaration with the command
`sgml-parse-prolog'. Big DTDs take some time to parse.
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 `[ANY]' (*** this is not really correct! a DTD will be
established even if there are missing entities, it may even be empty).
* Menu:
* Precompiled DTD Subsets::
* Using a Split Document::
* Inserting a DOCTYPE::
* Information from the DTD::
* Customizing DTD::
File: psgml.info, Node: Precompiled DTD Subsets, Next: Using a Split Document, Prev: Managing the DTD, Up: Managing the DTD
Precompiled DTD Subsets
=======================
If parsing the DTD takes too long time you can arrange to have
PSGML cache an internal complied version of the DTD. Caching can be
done of DTD fragments in favourable situations. It is possible to
have an external DTD subset cached but still have an internal DTD
subset as long as the internal subset does not define parameter
entities that affect the parsing of the external subset (*** what is
the exact conditions?, probably you can't use the cached external
subset if the internal subset defines parameter entities that are
also defined in the external subset with another value).
To enable caching you have to create special catalog files,
hereafter called ECAT files due to (temporary) lack of imagination.
These catalogs have similar syntax to the entity catalogs and there
are two variables containing lists of catalogs to search:
`sgml-ecat-files' and `sgml-local-ecat-files'. The ECAT files can
contain the following types of entries:
`file DTDFILE ENTITYDEF CFILE'
The DTDFILE is the name of a file containing a DTD subset that
should be cached in CFILE. The ENTITYDEF is optional and if
given have the following syntax:
[ NAME1 LITERAL1 NAME2 LITERAL2 ... ]
Using ENTITYDEF will modify the DTD subset by defining the
parameter entity with name NAME1 to be LITERAL1, .... The
cached version of the subset will be created with those entity
definitions, and when PSGML search for a matching cached subset
will check that the parameter entities in ENTITYDEF has been
defined with those values before trying to use `cfile'.
`public PUBID ENTITYDEF CFILE'
Cache the DTD subset with public identifier PUBID in file CFILE.
- User Option: sgml-recompile-out-of-date-cdtd
If non-`nil', out of date compiled DTDs will be automatically
recompiled. If the value is `ask', PSGML will ask before
recompiling. A `nil' value will cause PSGML to silently load an
out of date compiled DTD. A DTD that refers to undefined
external entities is always out of date, thus in such case it
can be useful to set this variable to `nil'.
Previous versions of PSGML have had another way of speeding up DTD
parsing. This code remains in this version of PSGML, but is not
actively maintained and may disappear in the future.
You can save the parsed DTD in a file using the command `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 `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 `M-x sgml-load-dtd'.
- User Option: sgml-default-dtd-file
This is the default file name for saved DTD. This is set by
`sgml-mode' to the buffer file name less extension plus the
extension `.ced', if that file exists. Can be changed in the
Local variables section of the file.
File: psgml.info, Node: Using a Split Document, Next: Inserting a DOCTYPE, Prev: Precompiled DTD Subsets, Up: Managing the DTD
Using a Split Document
======================
You can have the `DOCTYPE' declaration in another file by setting
`sgml-doctype' to the other file.
- User Option: sgml-parent-document
Used when the current file is part of a bigger document.
The variable describes how the current file's content fit into
the element hierarchy. The variable should have the form
(PARENT-FILE CONTEXT-ELEMENT* TOP-ELEMENT (HAS-SEEN-ELEMENT*)?)
PARENT-FILE
is a string, the name of the file containing the document
entity.
CONTEXT-ELEMENT
is a string, that is the name of an element type. It can
occur 0 or more times and is used to set up exceptions and
short reference map. Good candidates for these elements
are the elements open when the entity pointing to the
current file is used.
TOP-ELEMENT
is a string that is the name of the element type of the top
level element in the current file. The file should contain
one instance of this element, unless the last (lisp)
element of sgml-parent-document is a list. If it is a
list, the top level of the file should follow the content
model of top-element.
HAS-SEEN-ELEMENT
is a string that is the name of an element type. This
element is satisfied in the content model of top-element.
File: psgml.info, Node: Inserting a DOCTYPE, Next: Information from the DTD, Prev: Using a Split Document, Up: Managing the DTD
Inserting a DOCTYPE
===================
*** Describe the DTD menu in general. Describe customized entries
for special DTDs. Mention `C-c C-u C-d' for inserting a DOCTYPE from
keyboard.
If you change the doctype you must execute `sgml-parse-prolog',
changes in the doctype are not automatically recognized.
- User Option: 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 `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:
(("HTML" nil
sgml-default-dtd-file "~/sgml/html.ced"
sgml-omittag nil sgml-shorttag nil)
("HTML+" ""
"~/sgml/htmlplus.ced"
sgml-omittag t sgml-shorttag nil)
("DOCBOOK" ""
"~/sgml/docbook.ced"
sgml-omittag nil sgml-shorttag t)))
File: psgml.info, Node: Information from the DTD, Next: Customizing DTD, Prev: Inserting a DOCTYPE, Up: Managing the DTD
Information from the DTD
========================
PSGML can list various information about the current DTD. The
following commands can be used via `M-x' and can also be found in the
DTD menu.
`sgml-describe-dtd'
Display information about the current DTD.
`sgml-describe-element-type'
Describe the properties of an element type as declared in the
current DTD.
`sgml-describe-entity'
Describe the properties of an entity as declared in the current
DTD.
`sgml-list-elements'
Will list all elements and the attributes declared for the
element.
`sgml-list-attributes'
Will list all attributes declared and the elements that use them.
`sgml-list-terminals'
Will list all elements that can contain data.
`sgml-list-occur-in-elements'
Will list all element types and where it can occur.
`sgml-list-content-elements'
Will list all element types and the element types that can occur
in its content.
File: psgml.info, Node: Customizing DTD, Prev: Information from the DTD, Up: Managing the DTD
Customizing DTD
===============
PSGML can be customized by process instructions starting with
"PSGML" in the DTD. Generally this associates some information with
element types. E.g., if `sgml-fill-element' should skip the element
type or if the content should be displayed with a special font.
The general syntax is
`'
Note: in XML the ending delimiter is `?>', in SGML mode a trailing
`?' will be ignored if preceded by a space.
Where GI is the element type, PROP is a propery described below,
and VALUE is the value for the property. The first part from `PSGML'
to GI is read with current setting for `NAMECASE GENERAL', i.e., case
insensitive for normal SGML but case sensitive in XML mode. The PROP
and VALUE is read using Emacs Lisp conventions, i.e. case sensitive
and VALUE is a lisp expression (not evaluated).
Example
Properties
`nofill'
Set to either `t' or `nil'. If `t' the elements of this type
will be ignored when filling with `sgml-fill-element'. Note
that Emacs normal filling functions will not honor this.
`font'
Set to the name of an Emacs face. Should be a face that exists in
Emacs. E.g. `bold', `italic', `fixed-pitch'. The content of
elements of this type will be displayed in that face.
`attnames'
Set to a list of attribute names. E.g., `attnames=("ID" "CLASS"
"ONCLICK")'. This controls the attributes included when using the
`sgml-edit-attributes' (`C-c C-a') command. Only the attributes
in the list will be included and in that order. You can also end
the list with a `*' to include all attributes, but the listed
attributes will be on the top. E.g., `attnames=("ID" "CLASS"
"ONCLICK" *)'. Note: that the attribute names need to be
written with the correct case and in string quotes.
`structure'
Control if element is included in `sgml-show-structure' (`C-c
C-s'). If set to `t', the element is included and if set to
`ignore' it will not be included. *Note Showing information:
Information.
`help-text'
Should be a string. The string will be displayed by
`sgml-show-current-element-type' (`C-c C-t').
File: psgml.info, Node: Edit, Next: Display, Prev: Managing the DTD, Up: Top
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
* Translating characters and entities::
File: psgml.info, Node: Insert, Next: Complete, Prev: Edit, Up: Edit
Inserting Markup
================
The commands that insert start-tags works only if the document has
an associated DTD.
Keyboard commands for inserting:
`C-c <'
Will ask, for the tag to insert, in the mini-buffer with
completion on the tags that are valid at point
(`sgml-insert-tag').
If `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:
1. The end-tag for the current element, if it can be ended at
the position. Furthermore it will contain end-tags for
enclosing elements if the necessary omissible end-tag
declarations have been made in the DTD.
2. The start-tags of all elements that could occur after
point. If `sgml-omittag-transparent' is nil, the above
will be limited to the elements that can occur within the
current element.
`C-c C-e'
Insert start and end-tags for an element
(`sgml-insert-element'). The name of the element is read from
the mini-buffer with completion on valid elements. If
`sgml-insert-end-tag-on-new-line' is non-nil or the element has
element content, the end-tag will be inserted on a new line
after the start-tag.
If `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 `sgml-auto-insert-required-elements' is non-nil.
When the content model demands an element but there is more than
one to choose from, a comment can be inserted with the available
choices if the option `sgml-insert-missing-element-comment' is
non-nil.
`C-c C-i'
Inserts a new element in the current element where it is legal.
Prompts for element name with completion. The completion list
contains all elements that could be added to the current element
somewhere, without making the content invalid. This assumes that
the content is valid to begin with. Currently this list only has
regular elements, not inclusions. The new element will be
inserted as late as possible in the current element (unless
prefix argument is given, then as early as possible.)
`C-c C-r'
Makes the region into a new element (`sgml-tag-region'). Reads
element name from mini-buffer with completion as for `C-c C-e'.
`C-c /'
Inserts an end-tag for the current element
(`sgml-insert-end-tag').
`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.
`C-c +'
Read attribute name and value from mini-buffer and insert
attribute specification (`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:
Value for ATTRIBUTE (TYPE Default: CURRENT VALUE):
`C-c C-u C-m'
Give keyboard access to the customized part of the Markup menu.
Emacs will prompt for the markup to insert using the menu line as
selector. (See SGML-CUSTOM-MARKUP below.)
Menu bar:
`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:
`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 `C-c C-e' command.
`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 `C-c
<'.
`Insert end-tag'
Pops up a menu of valid end-tags and insert the selected tag.
`Tag region'
Pops up a menu of valid elements and tag the region with the
selection. Selections from the menu works like the `C-c C-r'
command.
`Insert entity'
Menu of all general entities defined in the DTD.
`Add Element to Element'
Pops up a menu of all elements valid somewhere in the current
element. The menu contains all elements that could be added to
the current element somewhere, without making the content
invalid. The new element will be inserted as late as possible in
the current element.
`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.
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
(`S-'). 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 `C-c
<'. Selection from the tags menu works like the `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:
1. Use the normal mouse commands to mark region.
For this to work you must either use "transient mark mode"
(*note Transient Mark Mode: (emacs)Transient Mark.) or set the
option `sgml-tag-region-if-active' to non-nil (don't set this
unless you are sure that you want it).
2. Alternatively make a secondary selection, this is done by
holding down the meta key and using the mouse buttons. *Note
Secondary selection: (emacs)Secondary selection. Some window
managers intercept these events, which makes it hard use the
secondary selection in Emacs.
- User Option: sgml-balanced-tag-edit
If non-nil, inserting a start-tag using the context menu will
also insert the corresponding end-tag.
- User Option: sgml-auto-insert-required-elements
If non-nil, automatically inserts required elements in the
content of an inserted element.
- User Option: sgml-omittag-transparent
If non-nil, will show legal tags inside elements with omissible
start-tags and legal tags beyond omissible end-tags.
- User Option: sgml-tag-region-if-active
If non-nil, the `Insert tags' menu will tag a region if the
region is considered active by emacs. If nil, region must be
active and `transient-mark-mode' must be on for the region to be
tagged.
- User Option: 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 `\r' where
the cursor should be left. Also, if a selection is made
according to the same rules as for the `S-mouse-1' menu, the
selection is replaced with the second string and `\r' is
replaced with the selection.
Example:
(("Version1" "")
("New page" ""))
- User Option: sgml-insert-missing-element-comment
If non-nil, and sgml-auto-insert-required-elements also true,
`sgml-insert-element' will insert a comment if there is an
element required but there is more than one to choose from.
- User Option: sgml-insert-end-tag-on-new-line
If non-nil, `sgml-insert-element' will put the end-tag on a new
line after the start-tag. Useful on slow terminals if you find
the end-tag after the cursor irritating.
File: psgml.info, Node: Complete, Next: Information, Prev: Insert, Up: Edit
Markup completion
=================
If you are typing in markup directly, `M-TAB' will help you by
completing a tag name, an entity name or a markup declaration name.
If you type `M-TAB' after a plain word, `ispell-complete-word' will
be invoked instead.
If you have typed (-!- marks the position of point)
&At-!-
and type `M-TAB' (assuming you use the `ISOLat1' entity set) you get:
Ã-!-
File: psgml.info, Node: Information, Next: Indent, Prev: Complete, Up: Edit
Showing information
===================
Commands for showing information obtained by parsing the buffer.
`C-c C-c'
Shows in the message area: context at point, if in a tag or in
mixed content and the open elements (`sgml-show-context'). The
form of the string is controled by the user option
`sgml-show-context-function'.
`C-c C-w'
Shows what element the character after point (under the cursor)
belongs to; also shows context of element (`sgml-what-element').
`C-c C-t'
Show information about the current element type and the valid
element following the point.
`C-c C-s'
Show the major element structure in a separate buffer (`*Document
structure*'). That buffer can be used to navigate the document,
like an Occur buffer (*note Other Search-and-Loop Commands:
(emacs)Other Repeating Search.). The structure shows container
elements and the text of the first child element (if it is not a
container). This works best for document types which uses
containers and title structure (e.g. `
Heder
..
'). PSGML uses a heuristic rule to identify container
elements: it should have element content and be non empty. You
can configure exceptions from this rule using a process
instruction in the DTD (*note Customizing DTD::).
To include an element type EL1 that would otherwise be excluded:
To exclude an element type EL2 that would otherwise be included:
List contextually valid tags (`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.
- User Option: sgml-show-context-function
The value shold be a function that generates a string from an
element and the current markup type (if any). There are two
ready made functions for this. The function
`sgml-show-context-standard', the default, generates a string
like `#PCDATA in para in chapter in book'. The function
`sgml-show-context-backslash' generates a string like
`book\chapter\para'.
File: psgml.info, Node: Indent, Next: Move, Prev: Information, Up: Edit
Indentation according to structure
==================================
You can indent a line according to the depth of element nesting at
the beginning of the line. To indent the current line use `'.
You can also use `' (`newline-and-indent') to start a new line
with correct indentation.
- User Option: sgml-indent-step
How much to increment indent for every element level. If nil, no
indentation.
If this is nil, `' will insert a tab instead of indenting.
- User Option: sgml-indent-data
If non-nil, indent in data/mixed context also.
File: psgml.info, Node: Move, Next: Attributes, Prev: Indent, Up: Edit
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.
`C-M-a'
Move to the (content) beginning of the current element
(`sgml-beginning-of-element').
`C-M-e'
Move to the (content) end of the current element
(`sgml-end-of-element').
`C-M-f'
Move forward by element (`sgml-forward-element').
`C-M-b'
Move backward by element (`sgml-backward-element').
`C-M-u'
Move up to before current element (`sgml-backward-up-element').
`C-c C-n'
Move up to after current element (`sgml-up-element').
`C-M-d'
Move down to the (content) beginning of the next element
(`sgml-down-element').
`C-c C-d'
Move to the next place where data is allowed
(`sgml-next-data-field').
You can also move to the next place where there is some structural
error with `C-c C-o' (*note Validate::).
File: psgml.info, Node: Attributes, Next: Change and delete, Prev: Move, Up: Edit
Editing attributes
==================
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 `sgml-edit-attributes' command,
available from the `SGML'-menu or on `C-c C-a'. This will create a
new Emacs window with all possible attributes listed in the form
ATTRIBUTE NAME = CURRENT VALUE.
The CURRENT VALUE may be shown as `#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 CURRENT
VALUE is show without eventual quotes.
It is now possible to edit the attribute values. You can move to
the next attribute with `'. If you want to let an attribute
have its default value use `C-c C-d', this will insert a `#DEFAULT'
in the value field.
If Emacs is running in an X window, the `#DEFAULT' will be
underlined to distinguish it from normal values.
Finish the editing with `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
`C-x 0' or if you want it neat, kill the buffer and remove the window.
Some other keys are:
`C-a'
Go to the beginning of the value field
(`sgml-edit-attrib-field-start').
`C-e'
Go to the end of the value field (`sgml-edit-attrib-field-end').
`C-c C-k'
Clear the value field (`sgml-edit-attrib-clear').
`C-c C-d'
Set the value field to `#DEFAULT' (`sgml-edit-attrib-default').
This is a special value that will make the attribute be implied.
File: psgml.info, Node: Change and delete, Next: Translating characters and entities, Prev: Attributes, Up: Edit
Changing and deleting markup
============================
`C-c ='
Change the name of the current element
(`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.
`C-c C-k'
Kill next tag, markup declaration or process instruction
(`sgml-kill-markup').
`C-M-k'
Kill the element following the cursor (`sgml-kill-element').
`C-c -'
Remove tags from current element (`sgml-untag-element').
`C-c #'
Convert character after point to a character reference
(`sgml-make-character-reference'). If called with a numeric
argument, convert a character reference back to a normal
character.
`C-c C-q'
Fills an element as a paragraph (`sgml-fill-element'). This is a
substitute for the normal `fill-paragraph'. The command uses
heuristics to decide what should be a paragraph.
1. If point is in an element content, recursively fill the
sub-elements.
2. Find the biggest element with mixed content containing
point.
3. 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.
`M-x sgml-expand-all-shortrefs'
Short references to text entities are expanded to the
replacement text of the entity other short references are
expanded into general entity references. If argument,
TO-ENTITY, is non-`nil', or if called interactive with numeric
prefix argument, all short references are replaced by generally
entity references.
`M-x sgml-normalize'
Normalize the document in the buffer. This will
1. expand short references,
2. insert missing tags,
3. replace minimized tags with full tags,
4. fix attribute specification lists according to options set.
There is one argument, TO-ENTITY, with the same meaning as for
`sgml-expand-all-shortrefs'.
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.
- User Option: sgml-normalize-trims
If non-nil, `sgml-normalize' will trim off white space from end
of element when adding end-tag.
Default: `t'.
File: psgml.info, Node: Translating characters and entities, Prev: Change and delete, Up: Edit
Translating between characters and entity references
====================================================
Set the variable `sgml-display-char-list-filename' to a file that
contains mappings between all characters present in the presentation
character set, and their "standard replacement text" names, e.g. "å"
-> "[aring ]", e.t.c.
The default value for this variable is `iso88591.map'.
Then use the functions (also in the Modify menu)
`sgml-charent-to-display-char'
`sgml-display-char-to-charent'
to translate between entities and characters.
File: psgml.info, Node: Display, Next: Miscellaneous options, Prev: Edit, Up: Top
Appearance of text in the buffer
********************************
* Menu:
* Fold:: Folding editing
* Hiding markup::
* Highlight:: Highlighting markup
File: psgml.info, Node: Fold, Next: Hiding markup, Prev: Display, Up: Display
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.
*Note Outline Mode: (emacs)Outline Mode.
`C-c C-f C-r'
The region between point and mark will be folded
(`sgml-fold-region').
`C-c C-f C-e'
The region between the start and end of the current element will
be folded (`sgml-fold-element').
This command can also fold the SGML declaration or the DOCTYPE
declaration.
`C-c C-f C-s'
Fold all the sub elements of the current element
(`sgml-fold-subelement').
`C-c C-s'
`C-c C-u C-l'
Unfold the current line, assuming it is the first line of a
folded region (`sgml-unfold-line').
`C-c C-u C-e'
Make all lines in current element visible
(`sgml-unfold-element').
`C-c C-u C-a'
Make all lines in current buffer visible (`sgml-unfold-all').
`C-c C-f C-x'
Unfold current element and then fold the subelements
(`sgml-expand-element'). If the current element is folded this
expands what is visible.
File: psgml.info, Node: Hiding markup, Next: Highlight, Prev: Fold, Up: Display
Hiding markup
=============
*** Describe hide-tags
File: psgml.info, Node: Highlight, Prev: Hiding markup, Up: Display
Highlighting markup
===================
PSGML can highlight the markup giving the markup a different "face"
(*note Using Multiple Typefaces: (emacs)Faces.). The highlighting
will only be done if the variable `sgml-set-face' is non-`nil'. The
default settings make tags bold and comments italic, but this can be
modified with the variable `sgml-markup-faces'. When highlighting is
on PSGML will parse after every command until the whole buffer has
been parsed or user event occurs.
To remove the highlighting type `M-x sgml-clear-faces'.
- User Option: sgml-set-face
If non-nil, psgml will set the face of parsed markup.
- User Option: sgml-markup-faces
A list of markup to face mappings. Each element looks like
`(MARKUP-TYPE . FACE)'. Possible values for MARKUP-TYPE is:
`comment'
comment declaration
`doctype'
doctype declaration
`end-tag'
end-tag
`ignored'
ignored marked section
`ms-start'
marked section end, if not ignored
`ms-end'
marked section start, if not ignored
`pi'
processing instruction
`sgml'
SGML declaration
`start-tag'
start-tag
`entity'
entity reference
`shortref'
short reference
File: psgml.info, Node: Miscellaneous options, Next: Bugs, Prev: Display, Up: Top
Miscellaneous options
*********************
*** describe sgml-save-options
- User Option: sgml-ignore-undefined-elements
Start-tags for undefined elements will either be ignored, if
`sgml-ignore-undefined-elements' is `t', or assumed to be
acceptable in the current element and defined with `O O ANY'
- User Option: sgml-range-indicator-max-length
Maximum number of characters used from the first and last entry
of a sub-menu to indicate the range of that menu.
This is used for long menus of elements, tags or entities that
are split into `sgml-max-menu-size' big sub-menus.
File: psgml.info, Node: Bugs, Next: Index, Prev: Miscellaneous options, Up: Top
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 `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 `C-c C-o'
(`sgml-next-trouble-spot').
File: psgml.info, Node: Index, Prev: Bugs, Up: Top
Index
*****
* Menu:
* : Indent.
* <1>: Indent.
* : Attributes.
* C-a: Attributes.
* C-c #: Change and delete.
* C-c +: Insert.
* C-c -: Change and delete.
* C-c /: Insert.
* C-c <: Insert.
* C-c =: Change and delete.
* C-c C-a: Attributes.
* C-c C-c <1>: Attributes.
* C-c C-c: Information.
* C-c C-d <1>: Attributes.
* C-c C-d <2>: Move.
* C-c C-d: Attributes.
* C-c C-e: Insert.
* C-c C-f C-e: Fold.
* C-c C-f C-r: Fold.
* C-c C-f C-s: Fold.
* C-c C-f C-x: Fold.
* C-c C-i: Insert.
* C-c C-k <1>: Change and delete.
* C-c C-k: Attributes.
* C-c C-n: Move.
* C-c C-o: Validate.
* C-c C-q: Change and delete.
* C-c C-r: Insert.
* C-c C-s <1>: Information.
* C-c C-s: Fold.
* C-c C-t: Information.
* C-c C-u C-a: Fold.
* C-c C-u C-d: Inserting a DOCTYPE.
* C-c C-u C-e: Fold.
* C-c C-u C-l: Fold.
* C-c C-u C-m: Insert.
* C-c C-v: Validate.
* C-c C-w: Information.
* C-c RET: Insert.
* C-e: Attributes.
* C-M-a: Move.
* C-M-b: Move.
* C-M-d: Move.
* C-M-e: Move.
* C-M-f: Move.
* C-M-k: Change and delete.
* C-M-u: Move.
* case sensitivity: SGML declaration.
* CONCUR: Introduction.
* DATATAG: Introduction.
* DOCTYPE: Managing the DTD.
* DTD <1>: Managing the DTD.
* DTD: Information from the DTD.
* Element: Information from the DTD.
* entity: Information from the DTD.
* entity catalog: Entity manager.
* external identifier: Entity manager.
* invoke: Invoke.
* LINK: Introduction.
* M-TAB: Complete.
* major mode: Invoke.
* NAMECASE GENERAL: SGML declaration.
* newline-and-indent: Indent.
* OMITTAG: SGML declaration.
* public identifier: Entity manager.
* RANK: Introduction.
* S-: Insert.
* SGML Declaration: Introduction.
* sgml-add-element-to-element: Insert.
* sgml-always-quote-attributes: SGML declaration.
* sgml-auto-activate-dtd: Managing the DTD.
* sgml-auto-insert-required-elements: Insert.
* sgml-backward-element: Move.
* sgml-backward-up-element: Move.
* sgml-balanced-tag-edit: Insert.
* sgml-beginning-of-element: Move.
* sgml-catalog-files: Entity manager.
* sgml-change-element-name: Change and delete.
* sgml-charent-to-display-char: Translating characters and entities.
* sgml-clear-faces: Highlight.
* sgml-complete: Complete.
* sgml-custom-dtd: Inserting a DOCTYPE.
* sgml-custom-markup: Insert.
* sgml-declaration: Validate.
* sgml-default-doctype-name: Managing the DTD.
* sgml-default-dtd-file: Precompiled DTD Subsets.
* sgml-describe-dtd: Information from the DTD.
* sgml-describe-element-type: Information from the DTD.
* sgml-describe-entity: Information from the DTD.
* sgml-display-char-to-charent: Translating characters and entities.
* sgml-doctype: Using a Split Document.
* sgml-down-element: Move.
* sgml-ecat-files: Precompiled DTD Subsets.
* sgml-edit-attrib-clear: Attributes.
* sgml-edit-attrib-default: Attributes.
* sgml-edit-attrib-field-end: Attributes.
* sgml-edit-attrib-field-start: Attributes.
* sgml-edit-attributes: Attributes.
* sgml-end-of-element: Move.
* sgml-expand-all-shortrefs: Change and delete.
* sgml-expand-element: Fold.
* sgml-fill-element: Change and delete.
* sgml-fold-element: Fold.
* sgml-fold-region: Fold.
* sgml-fold-subelement: Fold.
* sgml-forward-element: Move.
* sgml-ignore-undefined-elements: Miscellaneous options.
* sgml-indent-data: Indent.
* sgml-indent-or-tab: Indent.
* sgml-indent-step: Indent.
* sgml-insert-attribute: Insert.
* sgml-insert-element: Insert.
* sgml-insert-end-tag: Insert.
* sgml-insert-end-tag-on-new-line: Insert.
* sgml-insert-missing-element-comment: Insert.
* sgml-insert-tag: Insert.
* sgml-kill-element: Change and delete.
* sgml-kill-markup: Change and delete.
* sgml-list-attributes: Information from the DTD.
* sgml-list-content-elements: Information from the DTD.
* sgml-list-elements: Information from the DTD.
* sgml-list-occur-in-elements: Information from the DTD.
* sgml-list-terminals: Information from the DTD.
* sgml-list-valid-tags: Information.
* sgml-load-dtd: Precompiled DTD Subsets.
* sgml-local-catalogs: Entity manager.
* sgml-local-ecat-files: Precompiled DTD Subsets.
* sgml-make-character-reference: Change and delete.
* sgml-markup-faces: Highlight.
* sgml-max-menu-size: Miscellaneous options.
* sgml-minimize-attributes: SGML declaration.
* sgml-mode: Invoke.
* sgml-namecase-general: SGML declaration.
* sgml-next-data-field: Move.
* sgml-next-trouble-spot: Validate.
* sgml-normalize: Change and delete.
* sgml-normalize-trims: Change and delete.
* sgml-offer-save: Validate.
* sgml-omittag: SGML declaration.
* sgml-omittag-transparent: Insert.
* sgml-parent-document: Using a Split Document.
* sgml-parse-prolog: Managing the DTD.
* sgml-public-map: Entity manager.
* sgml-range-indicator-max-length: Miscellaneous options.
* sgml-recompile-out-of-date-cdtd: Precompiled DTD Subsets.
* sgml-save-dtd: Precompiled DTD Subsets.
* sgml-set-face: Highlight.
* sgml-shorttag: SGML declaration.
* sgml-show-context: Information.
* sgml-show-context-function: Information.
* sgml-show-current-element-type: Information.
* sgml-show-structure: Information.
* sgml-split-element: Insert.
* sgml-system-identifiers-are-preferred: Entity manager.
* sgml-tag-region: Insert.
* sgml-tag-region-if-active: Insert.
* sgml-unfold-all: Fold.
* sgml-unfold-element: Fold.
* sgml-unfold-line: Fold.
* sgml-untag-element: Change and delete.
* sgml-up-element: Move.
* sgml-validate: Validate.
* sgml-validate-command: Validate.
* sgml-validate-files: Validate.
* sgml-what-element: Information.
* SHORTTAG: SGML declaration.
* start up: Invoke.
* system identifier: Entity manager.
Tag Table:
Node: Top983
Node: Introduction1778
Node: Install4382
Node: Invoke6226
Node: Entity manager7276
Node: Validate12823
Node: SGML declaration15349
Node: Managing the DTD17107
Node: Precompiled DTD Subsets18406
Node: Using a Split Document21596
Node: Inserting a DOCTYPE23152
Node: Information from the DTD24931
Node: Customizing DTD26022
Node: Edit28382
Node: Insert28951
Node: Complete37699
Node: Information38199
Node: Indent40553
Node: Move41215
Node: Attributes42263
Node: Change and delete44052
Node: Translating characters and entities47006
Node: Display47669
Node: Fold47953
Node: Hiding markup49291
Node: Highlight49434
Node: Miscellaneous options50808
Node: Bugs51518
Node: Index52316
End Tag Table