xemacs-beta: man/psgml.texi comparison

comparison man/psgml.texi @ 2:ac2d302a0011 r19-15b2

Import from CVS: tag r19-15b2

author	cvs
date	Mon, 13 Aug 2007 08:46:35 +0200
parents	376386a54a3c
children	bcdc7deadc19

comparison

equal deleted inserted replaced

-:c0c6a60d29db
+:ac2d302a0011
 @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 $
+@c $Id: psgml.texi,v 1.1.1.2 1996/12/18 03:47:31 steve Exp $
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* PSGML: (psgml).          PSGML, a major mode for SGML documents.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
 @ifinfo
 Documentation for PSGML, a major mode for SGML.
-Copyright 1994 Lennart Staflin
+Copyright 1994, 1996 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.
 @c  The following two commands
 @c  start the copyright page.
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1994 Lennart Staflin
+Copyright @copyright{} 1994, 1996 Lennart Staflin
 @c Published by ...
 Permission is granted to make and distribute verbatim
 copies of this manual provided the copyright notice and
 @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
+PSGML is a major mode for editing SGML documents.  This is the DRAFT
-additions for HTML.  This is the DRAFT documentation for PSGML
+documentation for PSGML version 1.0.
-version 1.0.
 @end ifinfo
 @menu
 * Introduction::                Introduction
 * Install::                     How to install PSGML
 * 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::
 @end menu
+@c *** section about error recovery ??
 @c ------------------------------------------------------------------
 @node  Introduction, Install, Top, Top
 @comment  node-name,  next,  previous,  up
 @cindex DATATAG
 @cindex LINK
 @cindex RANK
 @cindex SGML Declaration
-PSGML is a major mode for editing SGML documents, and includes a number
+PSGML is a major mode for editing SGML documents.  It works with GNU
-of features for working specifically with HTML.  It works with GNU Emacs
+Emacs 19.19 and later or with Lucid Emacs 19.9 and later.  PSGML
-19.19 and later or with Lucid Emacs 19.9 and later.  PSGML contains a
+contains a simple SGML parser and can work with any DTD.  Functions
-simple SGML parser and can work with any DTD.  Functions provided
+provided includes menus and commands for inserting tags with only the
-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
+P3).  This can be found on
+@display
 @file{ftp://ftp.ifi.uio.no/pub/SGML/TEI/P3SG.DOC}.
+@end display
 A SGML document has three major parts, in order:
 @enumerate
 @item
 @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
+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
+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
+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
+@example
 SYSTEM "ISO 8879:1986"
 CHARSET
 BASESET  "ISO 646-1983//CHARSET
 International Reference Version (IRV)//ESC 2/5 4/0"
 DESCSET  0 128 0
 @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
+@end example
 @c -------------------------------------------------------------------------
 @node Install, Invoke, Introduction, Top
 @comment  node-name,  next,  previous,  up
 @chapter Installing PSGML
+To install PSGML you first need to uncompress and unpack the source
+archive.  This is done with the @code{gunzip} and @code{tar} commands.
+@example
+gunzip psgml-1.0a12.tar.gz; tar xf psgml-1.0a12.tar
+@end example
+This should create a subdirectory to the current directory with the
+source code. This directory contains a @code{configure} command (see the
+file INSTALL for more information about configure).  You can use the
+@code{configure} command to configure the package or you can load the
+file @file{psgml-maint} and execute the @code{psgml-compile-files}
+command.
 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
+@file{.emacs}.)
-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
+If you use the @code{configure} approach, compile psgml with @code{make}
-needs all the speed it can get.
+and the you can run @code{make install} to install it in the system
+library @file{site-lisp}.  The files are installed in a subdirectory
+named @file{psgml}.  The location of @file{site-lisp} is figured out by
+@code{configure}, but you can change it in the @file{Makefile}.  You
+need to make sure that this subdirectory is in Emacs @code{load-path}.
 Put the following line in your .emacs:
 @lisp
 (autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
 @comment node-name,  next,  previous,  up
 @chapter The Entity Manager
 @cindex public identifier
 @cindex system identifier
 @cindex external identifier
+@cindex entity catalog
+@c *** sgml-sysid-resolve-functions
 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}.
+@emph{system identifier}, or both.
 A typical public identifier looks like
 @example
 PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN"
 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 resolution on entity
+management.  The catalog consists of a series of entries and comments.  A
-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}
+@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}
+@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
+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}
+@item doctype @var{name} @var{file}
-The DOCTYPE keyword indicates that an entity manager should use the
+The @var{file} will be used for the entity text of an entity
-associated |storage object identifier| to locate the entity text
+used as external subset of a document declaration with @var{name} as
-(to be used as the external subset) for a doctype declaration whose
+document type name.
-document type name is specified by the |entity name spec|.
+@item sgmldecl @var{file}
-@item SGMLDECL @var{file}
+Used to specify a default SGML declaration.  Recognized but not used by
-The SGMLDECL keyword indicates that an entity manager should use
+PSGML other than to pass to an external validation command
-the associated |storage object identifier| to locate the entity
+(@code{sgml-validate-command}).
-text to be used as the SGML declaration.
 @end table
+When PSGML is looking for the file containing an external entity, the
+following things will be tried in order:
+@enumerate
+@vindex sgml-system-identifiers-are-preferred
+@item
+Try the system identifier, as a file name, if there is a system
+identifier and the variable @code{sgml-system-identifiers-are-preferred}
+is non-@code{nil} and there is no elements containing @samp{%s} in
+@code{sgml-public-map}.  If the system identifier is a relative file name
+it will be relative to the directory containing the defining entity.
+@item
+Look thru each catalog in @code{sgml-local-catalogs} and
+@code{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).
+@item
+Try the system identifier, if any, as a file name.
+If @code{sgml-system-identifiers-are-preferred} is @code{nil}
+and there is no elements containing @samp{%s} in @code{sgml-public-map}.
+@item
+Try the entries in @code{sgml-public-map}.  Using the catalogs are
+preferred.  The @code{sgml-public-map} may disappear in a future version
+of PSGML (not soon though).
+@end enumerate
 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.
+in order until an existing file is found.  The @code{sgml-public-map} is
+modeled after @file{sgmls} environment variable @code{SGML_PATH} and
+psgml understand the following substitution characters: %%, %N, %P, %S,
+%Y, %C, %L, %O, %T, and %V.  The the default value of
+@code{sgml-public-map} is taken from the environment variable
+@code{SGML_PATH}.
 Given the public identifier above and the file name template
 @samp{/usr/local/lib/sgml/%o/%c/%d}, the resulting file name is
 @example
 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-system-identifiers-are-preferred
+If @code{nil}, PSGML will look up external entities by searching the
+catalogs in @code{sgml-local-catalogs} and @code{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.
+@end defopt
 @defopt sgml-public-map
-This should be a list of file name templates. This variable is
+This should be a list of file name templates.  This variable is
-initialized from the environment variable @code{SGML_PATH}. This 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")
 @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
+PSGML can not validate an SGML document (see below what it can
-do).  If you have a validating SGML parser, like @file{sgmls}, you can
+and can't do).  If you have a validating SGML parser, like
-run the parser on your file with the command @kbd{C-c C-v}
+@file{sgmls}, you can run the parser on your file with the
-(@code{sgml-validate}).
+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
+This is a @code{format} control string that by default should contain two
-two `%s' conversion specifications: the first will be replaced by the
+@code{%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
+second will be replaced by the current buffer's file name (or the
-string, if nil).
+empty string, if nil).
-If @code{sgml-validate-files} is non-nil, the format string should
+If @code{sgml-validate-files} is non-nil, the format string should contain
-contain one `%s' conversion specification for each element of its
+one @code{%s} conversion specification for each element of its result.
-result.
+If sgml-validate-command is a list, then every element should be a
-The default value is @code{sgml -s %s %s}.
+string.  The strings will be tried in order and @samp{%}-sequences in the
+string will be replaced according to the list below, if the string contains
+@samp{%}-sequences with no replacement value the next string will be tried.
+@table @code
+@item %b
+means the visited file of the current buffer
+@item %s
+means the SGML declaration specified in the sgml-declaration variable
+@item %d
+means the file containing the DOCTYPE declaration, if not in the buffer
+@end table
+The default value is @code{nsgmls -s %s %s}.
 @end defopt
 @defopt sgml-validate-files
-If non-nil, a function of no arguments that returns a list of file
+If non-nil, a function of no arguments that returns a list of
-names.  These file names will serve as the arguments to the
+file names.  These file names will serve as the arguments to the
-@code{sgml-validate-command} format control string instead of the
+@code{sgml-validate-command} format control string instead of
-defaults.
+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
+If non-nil, @kbd{C-c C-v} (@code{sgml-validate}) will ask about
-modified buffers before running the validate command.  The default value
+saving modified buffers before running the validate command.
-is @code{t}.
+The default value is @code{t}.
 @end defopt
 @kindex C-c C-o
 @findex sgml-next-trouble-spot
 @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
+@c --------------------------------------------------------------------------
 @node SGML declaration, Managing the DTD, Validate, Top
 @comment  node-name,  next,  previous,  up
 @chapter SGML Declaration
 @cindex SHORTTAG
 @cindex OMITTAG
 @c --------------------------------------------------------------------------
 @node Managing the DTD, Edit, SGML declaration, Top
 @comment  node-name,  next,  previous,  up
 @chapter Document Type Declaration
 @cindex DOCTYPE
+@cindex DTD
+@vindex sgml-default-doctype-name
+PSGML needs to know about the DTD you are using for many of its commands.
+If you do not have a @samp{DOCTYPE} declaration in your file,
+PSGML will try assume that there is one of the form
+@example
+<!DOCTYPE @var{name} SYSTEM>
+@end example
+where @var{name} is the value of @code{sgml-default-doctype-name}, if
+the value is non-@code{nil}, else the GI of the first tag will be used.
 @findex sgml-parse-prolog
-PSGML needs to know about the DTD you are using for many of its commands.
+@vindex sgml-auto-activate-dtd
-You can use PSGML without specifying a DTD, it will then accept any tags
+PSGML will try to parse the document type declaration the first time
-and assume a content model of @code{ANY} with no omissible tags.
+you do something that needs to parse the document or immediately if the
+variable @code{sgml-auto-activate-dtd} is @code{t}.  You can also
-If you have a @samp{DOCTYPE} declaration in your file, PSGML will try to
+initiate the parsing of the document type declaration with the command
-parse this.  Either the first time you do something that needs to parse
+@code{sgml-parse-prolog}.  Big DTDs take some time 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]}.
+@samp{[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::
+@end menu
+@c ------------------------------------------------------------
+@node  Precompiled DTD Subsets, Using a Split Document, Managing the DTD, Managing the DTD
+@comment  node-name,  next,  previous,  up
+@section 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).
+@vindex sgml-ecat-files
+@vindex sgml-local-ecat-files
+To enable caching you have to create special catalog files, hear after
+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: @code{sgml-ecat-files} and
+@code{sgml-local-ecat-files}.  The ECAT files can contain the following
+types of entries:
+@table @samp
+@item file @var{dtdfile} @var{entitydef} @var{cfile}
+The @var{dtdfile} is the name of a file containing a DTD subset that
+should be cached in @var{cfile}.  The @var{entitydef} is optional and if
+given have the following syntax:
+@example
+[ @var{name1} @var{literal1} @var{name2} @var{literal2} @dots{} ]
+@end example
+Using @var{entitydef} will modify the DTD subset by defining the
+parameter entity with name @var{name1} to be @var{literal1}, @dots{}.  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 @var{entitydef} has been defined with
+those values before trying to use @file{cfile}.
+@item public @var{pubid} @var{entitydef} @var{cfile}
+Cache the DTD subset with public identifier @var{pubid} in file
+@var{cfile}.
+@end table
+@defopt sgml-recompile-out-of-date-cdtd
+If non-@code{nil}, out of date compiled DTDs will be automatically
+recompiled.  If the value is @code{ask}, PSGML will ask before
+recompiling.  A @code{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 @code{nil}.
+@end defopt
+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.
+@findex sgml-save-dtd
+@findex sgml-load-dtd
+@vindex sgml-default-dtd-file
+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}.
 @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
+@c true with system-path
+@c either or by creating a saved DTD and setting
+@c @code{sgml-default-dtd-file} to that file.  If
+@c @code{sgml-default-dtd-file} contains a relative file name, the
+@c directories in @code{sgml-system-path} will be searched for the file.
+@c ------------------------------------------------------------
+@node  Using a Split Document, Inserting a DOCTYPE, Precompiled DTD Subsets, Managing the DTD
+@comment  node-name,  next,  previous,  up
+@section Using a Split Document
+@c *** why not defopt??
+@vindex sgml-doctype
+You can have the @samp{DOCTYPE} declaration in another file by setting
+@code{sgml-doctype} to the other file.
 @defopt sgml-parent-document
-This can be set to the name (a string) of a file containing the
+Used when the current file is part of a bigger document.
-@samp{DOCTYPE} declaration to use, or a list @code{(@var{filename}
-@var{doctypename})}, where @var{filename} is the name of a file
+The variable describes how the current file's content fit into the element
-containing the @samp{DOCTYPE} declaration to use, with the modification
+hierarchy.  The variable should have the form
-that the document type name is @var{doctypename}.
-@end defopt
+@lisp
+(@var{parent-file} @var{context-element}* @var{top-element} (@var{has-seen-element}*)?)
+@end lisp
+@table @var
+@item parent-file
+is a string, the name of the file containing the
+document entity.
+@item 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.
+@item 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.
+@item 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.
+@end table
+@end defopt
+@c ------------------------------------------------------------
+@node  Inserting a DOCTYPE, Information from the DTD, Using a Split Document, Managing the DTD
+@comment  node-name,  next,  previous,  up
+@section Inserting a DOCTYPE
+@kindex C-c C-u C-d
+@findex sgml-custom-dtd
+*** Describe the DTD menu in general.  Describe customized entries for
+special DTDs.  Mention @kbd{C-c C-u C-d} for inserting a DOCTYPE from
+keyboard.
 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
+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
 "~/sgml/docbook.ced"
 sgml-omittag nil sgml-shorttag t)))
 @end example
 @end defopt
+@c ------------------------------------------------------------
+@node  Information from the DTD,  , Inserting a DOCTYPE, Managing the DTD
+@comment  node-name,  next,  previous,  up
+@section Information from the DTD
+@cindex DTD
+@cindex Element
+PSGML can list various information about the current DTD.
+The following commands can be used via @kbd{M-x} and
+can also be found in the DTD menu.
+@table @code
+@findex sgml-general-dtd-info
+@item sgml-general-dtd-info
+Display information about the current DTD.
+@findex sgml-describe-element-type
+@item sgml-describe-element-type
+Describe the properties of an element type as declared in the current DTD.
+@cindex entity
+@findex sgml-describe-entity
+@item sgml-describe-entity
+Describe the properties of an entity as declared in the current DTD.
+@findex sgml-list-elements
+@item sgml-list-elements
+Will list all elements and the attributes declared for the element.
+@findex sgml-list-attributes
+@item sgml-list-attributes
+Will list all attributes declared and the elements that use them.
+@findex sgml-list-terminals
+@item sgml-list-terminals
+Will list all elements that can contain data.
+@findex sgml-list-occur-in-elements
+@item sgml-list-occur-in-elements
+Will list all element types and where it can occur.
+@findex sgml-list-content-elements
+@item sgml-list-content-elements
+Will list all element types and the element types that can occur
+in its content.
+@end table
 @c ---------------------------------------------------------------------------
 @node  Edit, Display, Managing the DTD, Top
 @comment  node-name,  next,  previous,  up
 @chapter Commands for editing
 * 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::
 @end menu
 @c ------------------------------------------------------------------
 @node Insert, Complete, Edit, Edit
 @comment  node-name,  next,  previous,  up
 @end enumerate
 @kindex C-c C-e
 @findex sgml-insert-element
+@vindex sgml-insert-end-tag-on-new-line
 @item C-c C-e
-Insert start and end-tags for an element (@code{sgml-insert-element}).
+Insert start and end-tags for an element
-The name of the element is read from the mini-buffer with completion on
+(@code{sgml-insert-element}).  The name of the element is read
-valid elements.
+from the mini-buffer with completion on valid elements.  If
+@code{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.
+@vindex sgml-omittag-transparent
 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.
+@vindex sgml-auto-insert-required-elements
+@vindex sgml-insert-missing-element-comment
 Required elements in the content will be automatically inserted if the
 option @code{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
+@code{sgml-insert-missing-element-comment} 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
 @example
 Value for @var{attribute} (@var{type} Default: @var{current value}):
 @end example
+@kindex C-c C-u C-m
+@findex sgml-custom-markup
+@item 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 @var{sgml-custom-markup} below.)
 @end table
 Menu bar:
 @table @samp
 @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
+(@kbd{S-@key{mouse-1}}).  In XEmacs 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
 ("New page"  "<?NewPage>"))
 @end example
 @end defopt
+@defopt sgml-insert-missing-element-comment
+If non-nil, and sgml-auto-insert-required-elements also true,
+@code{sgml-insert-element} will insert a comment if there is an
+element required but there is more than one to choose from.
+@end defopt
+@defopt sgml-insert-end-tag-on-new-line
+If non-nil, @code{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.
+@end defopt
 @c -------------------------------------------------------------------------
 @node Complete, Information, Insert, Edit
 @comment  node-name,  next,  previous,  up
 @section Markup completion
 make the attribute be implied.
 @end table
 @c --------------------------------------------------------------------------
-@node Change and delete,  , Attributes, Edit
+@node Change and delete, Translating characters and entities, Attributes, Edit
 @comment  node-name,  next,  previous,  up
 @section Changing and deleting markup
 @table @kbd
 @kindex C-c =
 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-expand-all-shortrefs
+@item 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, @var{to-entity}, is non-@code{nil}, or if
+called interactive with numeric prefix argument, all short references
+are replaced by generally entity references.
 @findex sgml-normalize
 @item M-x sgml-normalize
 Normalize the document in the buffer.  This will
 @enumerate
 @item
+expand short references,
+@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 argument, @var{to-entity}, with the same meaning as for
+@code{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.
 Default: @code{t}.
 @end defopt
+@c --------------------------------------------------------------------------
+@node Translating characters and entities,  , Change and delete, Edit
+@comment  node-name,  next,  previous,  up
+@section Translating between characters and entity references
+@c *** Need work..
+Set the variable @code{sgml-display-char-list-filename} to a file 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'.
+The use the functions (also in the Modify menu)
+@table @code
+@findex sgml-charent-to-display-char
+@item sgml-charent-to-display-char
+@findex sgml-display-char-to-charent
+@item sgml-display-char-to-charent
+@end table
+to translate between entities and characters.
 @c ---------------------------------------------------------------------------
-@node Display, Bugs, Edit, Top
+@node Display, Miscellaneous options, Edit, Top
 @comment  node-name,  next,  previous,  up
 @chapter Appearance of text in the buffer
 @menu
 * Fold::                        Folding editing
+* Hiding markup::
 * Highlight::                   Highlighting markup
 @end menu
 @c ---------------------------------------------------------------------------
-@node  Fold, Highlight, Display, Display
+@node  Fold, Hiding markup, 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.
 (@code{sgml-expand-element}).  If the current element is folded this
 expands what is visible.
 @end table
 @c ---------------------------------------------------------------------------
-@node  Highlight,  , Fold, Display
+@node  Hiding markup, Highlight, Fold, Display
+@comment  node-name,  next,  previous,  up
+@section Hiding markup
+*** Describe hide-tags
+@c ---------------------------------------------------------------------------
+@node  Highlight,  , Hiding markup, Display
 @comment  node-name,  next,  previous,  up
 @section Highlighting markup
-PSGML can highlight the markup as it parses it by giving the markup a
+PSGML can highlight the markup giving the markup a different @dfn{face}
-different @dfn{face} (@pxref{Faces, , Using Multiple Typefaces, emacs,
+(@pxref{Faces, , Using Multiple Typefaces, emacs, The Emacs Editor}).
-The Emacs Editor}).  The highlighting will only be done if the variable
+The highlighting will only be done if the variable @code{sgml-set-face}
-@code{sgml-set-face} is non-nil.  The default settings make tags bold
+is non-@code{nil}.  The default settings make tags bold and comments
-and comments italic, but this can be modified with the variable
+italic, but this can be modified with the variable
-@code{sgml-markup-faces}.
+@code{sgml-markup-faces}.  When highlighting is on PSGML will parse after
+every command until the whole buffer has been parsed or user event
+occurs.
 @findex sgml-clear-faces
 To remove the highlighting type @kbd{M-x sgml-clear-faces}.
 @defopt sgml-set-face
 @item shortref
 short reference
 @end table
 @end defopt
 @c ------------------------------------------------------------------
-@node Bugs, Index, Display, Top
+@node  Miscellaneous options, Bugs, Display, Top
+@comment  node-name,  next,  previous,  up
+@chapter Miscellaneous options
+*** describe sgml-save-options
+@defopt sgml-ignore-undefined-elements
+Start-tags for undefined elements will either be ignored, if
+@code{sgml-ignore-undefined-elements} is @code{t}, or assumed to be
+acceptable in the current element and defined with @code{O O ANY}
+@end defopt
+@defopt 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.
+@vindex sgml-max-menu-size
+This is used for long menus of elements, tags or entities that are split
+into @code{sgml-max-menu-size} big sub-menus.
+@end defopt
+@c ------------------------------------------------------------------
+@node Bugs, Index, Miscellaneous options, Top
 @comment  node-name,  next,  previous,  up
 @chapter Bugs
 If you encounter something that you think is a bug, please report
 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
+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}).
 @comment    node-name,         next,       previous, up
 @chapter Index
 @printindex cp
+@contents
 @bye

Mercurial > hg > xemacs-beta

comparison man/psgml.texi @ 2:ac2d302a0011 r19-15b2