xemacs-beta: man/psgml.texi comparison

comparison man/psgml.texi @ 0:376386a54a3c r19-14

Import from CVS: tag r19-14

author	cvs
date	Mon, 13 Aug 2007 08:45:50 +0200
parents
children	ac2d302a0011

comparison

equal deleted inserted replaced

--1:000000000000
+:376386a54a3c
+\input texinfo   @c -*-texinfo-*-
+@c %**start of header
+@setfilename ../info/psgml.info
+@settitle psgml
+@c @setchapternewpage odd
+@syncodeindex fn cp
+@syncodeindex vr cp
+@synindex ky cp
+@c %**end of header
+@c $Id: psgml.texi,v 1.1.1.1 1996/12/18 03:36:10 steve Exp $
+@ifinfo
+Documentation for PSGML, a major mode for SGML.
+Copyright 1994 Lennart Staflin
+Permission is granted to make and distribute verbatim
+copies of this manual provided the copyright notice and
+this permission notice are preserved on all copies.
+@ignore
+Permission is granted to process this file through TeX
+and print the results, provided the printed document
+carries a copying permission notice identical to this
+one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+@end ignore
+Permission is granted to copy and distribute modified
+versions of this manual under the conditions for
+verbatim copying, and provided that the entire
+resulting derived work is distributed under the terms
+of a permission notice identical to this one.
+Permission is granted to copy and distribute
+translations of this manual into another language,
+under the above conditions for modified versions,
+except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+@end ifinfo
+@titlepage
+@title Editing SGML with Emacs and PSGML
+@author Lennart Staflin
+@c  The following two commands
+@c  start the copyright page.
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1994 Lennart Staflin
+@c Published by ...
+Permission is granted to make and distribute verbatim
+copies of this manual provided the copyright notice and
+this permission notice are preserved on all copies.
+@ignore
+Permission is granted to process this file through TeX
+and print the results, provided the printed document
+carries a copying permission notice identical to this
+one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+@end ignore
+Permission is granted to copy and distribute modified
+versions of this manual under the conditions for
+verbatim copying, and provided that the entire
+resulting derived work is distributed under the terms
+of a permission notice identical to this one.
+Permission is granted to copy and distribute
+translations of this manual into another language,
+under the above conditions for modified versions,
+except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+@end titlepage
+@node  Top, Introduction, (dir), (dir)
+@comment  node-name,  next,  previous,  up
+@ifinfo
+@top PSGML
+PSGML is a major mode for editing SGML documents, with special
+additions for HTML.  This is the DRAFT documentation for PSGML
+version 1.0.
+@end ifinfo
+@menu
+* Introduction::                Introduction
+* Install::                     How to install PSGML
+* Invoke::                      How to invoke PSGML
+* Entity manager::              The Entity Manager
+* Validate::                    Running an external SGML parser
+* SGML declaration::            Using an SGML declaration
+* Managing the DTD::            Specifying what DTD to use
+* Edit::                        Commands for editing
+* Display::                     Appearance of text in the buffer
+* Bugs::                        Reporting bugs
+* Index::
+@end menu
+@c ------------------------------------------------------------------
+@node  Introduction, Install, Top, Top
+@comment  node-name,  next,  previous,  up
+@chapter Introduction
+@cindex CONCUR
+@cindex DATATAG
+@cindex LINK
+@cindex RANK
+@cindex SGML Declaration
+PSGML is a major mode for editing SGML documents, and includes a number
+of features for working specifically with HTML.  It works with GNU Emacs
+19.19 and later or with Lucid Emacs 19.9 and later.  PSGML contains a
+simple SGML parser and can work with any DTD.  Functions provided
+includes menus and commands for inserting tags with only the
+contextually valid tags, identification of structural errors, editing of
+attribute values in a separate window with information about types and
+defaults, and structure based editing.
+SGML, a language for encoding the structure of a document, is an ISO
+standard: ISO 8879:1986 ``Information processing -- Text and office
+systems -- Standard Generalized Markup Language (SGML)''.
+A good introduction to SGML is @cite{A Gentle Introduction to SGML}
+produced by Text Encoding Initiative (this is really chapter 2 of TEI
+P3). This can be found on
+@file{ftp://ftp.ifi.uio.no/pub/SGML/TEI/P3SG.DOC}.
+A SGML document has three major parts, in order:
+@enumerate
+@item
+SGML Declaration (@samp{<!SGML "ISO 8879:1986" @dots{} >})
+@item
+Document Type Declaration (@samp{<!DOCTYPE @var{name} @dots{} >})
+@item
+Document Element (@samp{<@var{name}> @dots{} </@var{name}>})
+@end enumerate
+The SGML declaration contains general information about character sets,
+concrete syntax, and SGML features used. PSGML does not use the SGML
+Declaration, it can be left out, and if included is ignored. Many SGML
+systems allow the SGML declaration to be defaulted.  PSGML always use
+the Concrete Reference Syntax but without limitations on
+lengths. Features used has to be indicated with variables (@pxref{SGML
+declaration}).
+The document type declaration specifies the valid elements and entities
+and how they can be nested. A document type is usually needed, but can
+reside in another file (@pxref{Managing the DTD}).
+The system declaration for PSGML:
+@format
+SYSTEM "ISO 8879:1986"
+CHARSET
+BASESET  "ISO 646-1983//CHARSET
+International Reference Version (IRV)//ESC 2/5 4/0"
+DESCSET  0 128 0
+CAPACITY PUBLIC  "ISO 8879:1986//CAPACITY Reference//EN"
+FEATURES
+MINIMIZE DATATAG NO  OMITTAG  YES   RANK     NO  SHORTTAG YES
+LINK     SIMPLE  NO  IMPLICIT NO    EXPLICIT NO
+OTHER    CONCUR  NO  SUBDOC   YES 1 FORMAL   YES
+SCOPE    DOCUMENT
+SYNTAX   PUBLIC  "ISO 8879:1986//SYNTAX Reference//EN"
+@c     SYNTAX   PUBLIC  "ISO 8879:1986//SYNTAX Core//EN"
+VALIDATE
+GENERAL NO  MODEL    NO   EXCLUDE  NO  CAPACITY NO
+NONSGML NO  SGML     NO   FORMAL   NO
+SDIF     PACK    NO  UNPACK   NO
+@end format
+@c -------------------------------------------------------------------------
+@node Install, Invoke, Introduction, Top
+@comment  node-name,  next,  previous,  up
+@chapter Installing PSGML
+Place the @file{*.el} and the @file{*.elc} files in a directory where
+Emacs can find it (i.e. one of the directories in the @code{load-path}
+variable, you can add a directory to this variable in your
+@file{.emacs}.)  If you obtained PSGML without @file{*.elc} files, you
+can create them by letting Emacs byte compile the @file{*.el} files (use
+@kbd{M-x byte-compile-file}).  Parsing SGML in Emacs Lisp is slow and
+needs all the speed it can get.
+Put the following line in your .emacs:
+@lisp
+(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
+@end lisp
+You may also want to set up search paths for external entities,
+@xref{Entity manager}.
+The @file{psgml.info} is the documentation for PSGML in the info format.
+You can read this with the Emacs command @kbd{C-u C-h i}.  You can also
+install the file in your systems info directory and edit the
+@file{dir} file to include @file{psgml.info} in the menu.
+The info file @file{psgml.info} is created from the texinfo file
+@file{psgml.texi}.  The texinfo file can also be used to create a hard
+copy of the documentation.  To do this you need the @TeX{} program and a
+copy of @file{texinfo.tex}.
+@c --------------------------------------------------------------------------
+@node  Invoke, Entity manager, Install, Top
+@comment  node-name,  next,  previous,  up
+@chapter How to invoke PSGML
+@cindex invoke
+@cindex start up
+@cindex major mode
+@findex sgml-mode
+PSGML defines a major mode called @code{sgml-mode}.  Files with
+extensions @file{.sgml}, @file{.sgm} or @file{.dtd} will
+automatically be edited in SGML mode.  To edit some other file in
+sgml mode, type @kbd{M-x sgml-mode @key{RET}} after finding the
+file.
+If you can modify the file you can add a @dfn{Local Variables} list
+(@pxref{file variables, , Local Variables in Files, emacs, The Emacs
+Editor}) to the end of the file.  This can make Emacs
+automatically set sgml mode and user options when the file is loaded.
+The simplest Local Variables list would look like:
+@example
+<!--
+Local Variables:
+mode: sgml
+End:
+-->
+@end example
+You can also put a line at the top of the file to tell emacs to use sgml
+mode:
+@example
+<!-- -*- sgml -*- -->
+@end example
+But remember that you can't have a comment before the @emph{SGML
+declaration}.
+@c -------------------------------------------------------------------------
+@node  Entity manager, Validate, Invoke, Top
+@comment node-name,  next,  previous,  up
+@chapter The Entity Manager
+@cindex public identifier
+@cindex system identifier
+@cindex external identifier
+SGML can refer to an external file (really entity) with an
+@emph{external identifier}, this is a @emph{public identifier} or a
+@emph{system identifier}.
+A typical public identifier looks like
+@example
+PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN"
+@end example
+@noindent
+where ``ISO 8879:1986'' is the owner, ``ENTITIES'' is the text class and
+``Added Latin 1'' is the text description (and ``EN'' is language).
+A system identifier looks like
+@example
+SYSTEM "htmlplus.dtd"
+@end example
+@noindent where ``htmlplus.dtd'' is a system-specific identifier.
+To map external identifiers to file names, PSGML first searches entity
+catalog files and then search the list of file name templates in the
+variable @code{sgml-public-map}.
+*** Describe the catalog format
+The catalog format is according to SGML/Opens resoution on entity
+management. The catalog consists of a series of entries and comment. A
+comment is delimited by @samp{--} like in a markup declaration.
+The entry types recognized are described in the following table.
+@table @samp
+@item PUBLIC @var{pubid} @var{file}
+The @var{file} will be used for the entity text of an entity
+with the public identifier @var{pubid}.
+@item ENTITY @var{name} @var{file}
+The @var{file} will be used for the entity text of an entity
+with the name @var{name}. If the @var{name} starts with a @samp{%} the
+rest of the name will be matched against parameter entities.
+@item DOCTYPE @var{name} @var{file}
+The DOCTYPE keyword indicates that an entity manager should use the
+associated |storage object identifier| to locate the entity text
+(to be used as the external subset) for a doctype declaration whose
+document type name is specified by the |entity name spec|.
+@item SGMLDECL @var{file}
+The SGMLDECL keyword indicates that an entity manager should use
+the associated |storage object identifier| to locate the entity
+text to be used as the SGML declaration.
+@end table
+The @code{sgml-public-map} variable can contain a list of file name
+templates where @samp{%P} will be substituted with the whole public
+identifier, owner is substituted for @samp{%O}, public text class for
+@samp{%C}, and public text description for @samp{%D}.  The text class
+will be converted to lower case and the owner and description will be
+transliterated according to the variable
+@code{sgml-public-transliterations}.  The templates in the list is tried
+in order until an existing file is found.
+Given the public identifier above and the file name template
+@samp{/usr/local/lib/sgml/%o/%c/%d}, the resulting file name is
+@example
+/usr/local/lib/sgml/ISO_8879:1986/entities/Added_Latin_1
+@end example
+Note: blanks are transliterated to @samp{_} (and also @samp{/} to
+@samp{%}) and the text class is down cased.
+@defopt sgml-catalog-files
+This is a list of catalog entry files.
+The files are in the format defined in the SGML Open Draft Technical
+Resolution on Entity Management.  The Emacs variable is initialized from
+the environment variable @code{SGML_CATALOG_FILES} or if this variable
+is undefined the default is
+@lisp
+("CATALOG" "/usr/local/lib/sgml/CATALOG")
+@end lisp
+@end defopt
+@defopt sgml-local-catalogs
+A list of SGML entity catalogs to be searched first when parsing the
+buffer.  This is used in addition to @code{sgml-catalog-files}, and
+@code{sgml-public-map}.  This variable is automatically local to the
+buffer.
+@end defopt
+@defopt sgml-public-map
+This should be a list of file name templates. This variable is
+initialized from the environment variable @code{SGML_PATH}. This is
+the same environment variable that @file{sgmls} uses.  If the
+environment variable is undefined the default is
+@lisp
+("%S" "/usr/local/lib/sgml/%o/%c/%d")
+@end lisp
+@c Mapping from public identifiers to file names.
+@end defopt
+@c the colon separated list in @code{SGML_PATH} is converted to a lisp list
+@c -------------------------------------------------------------------------
+@node  Validate, SGML declaration, Entity manager, Top
+@comment node-name,  next,  previous,  up
+@chapter Running an external SGML parser
+@kindex C-c C-v
+@findex sgml-validate
+PSGML can not validate an SGML document (see below what it can and can't
+do).  If you have a validating SGML parser, like @file{sgmls}, you can
+run the parser on your file with the command @kbd{C-c C-v}
+(@code{sgml-validate}).
+Some variables control this function:
+@defopt sgml-validate-command
+The shell command to validate an SGML document.
+This is a @code{format} control string that by default should contain
+two `%s' conversion specifications: the first will be replaced by the
+value of @code{sgml-declaration} (or the empty string, if nil); the
+second will be replaced by the current buffer's file name (or the empty
+string, if nil).
+If @code{sgml-validate-files} is non-nil, the format string should
+contain one `%s' conversion specification for each element of its
+result.
+The default value is @code{sgml -s %s %s}.
+@end defopt
+@defopt sgml-validate-files
+If non-nil, a function of no arguments that returns a list of file
+names.  These file names will serve as the arguments to the
+@code{sgml-validate-command} format control string instead of the
+defaults.
+@end defopt
+@defopt sgml-declaration
+The name of the SGML declaration file.
+@end defopt
+@defopt sgml-offer-save
+If non-nil, @kbd{C-c C-v} (@code{sgml-validate}) will ask about saving
+modified buffers before running the validate command.  The default value
+is @code{t}.
+@end defopt
+@kindex C-c C-o
+@findex sgml-next-trouble-spot
+The built-in parser can find some markup errors.  The command @kbd{C-c
+C-o} (@code{sgml-next-trouble-spot}) is the best way to use the built-in
+parser for this.  To check the whole file go to the beginning of the
+buffer and use @kbd{C-c C-o}.
+Some of the markup errors not found are:
+@itemize @bullet
+@item
+Errors in the SGML declaration.
+@item
+Errors in attribute specifications.
+@item
+Markup errors in entity replacement text.
+@item
+Omitted start-tags for empty elements.
+@end itemize
+@node SGML declaration, Managing the DTD, Validate, Top
+@comment  node-name,  next,  previous,  up
+@chapter SGML Declaration
+@cindex SHORTTAG
+@cindex OMITTAG
+PSGML does not understand the SGML declaration, it accepts one in the
+file but it is ignored.  If you have the SGML declaration in another
+file you can make @file{sgmls} use it when you use the @kbd{C-c C-v}
+(@code{sgml-validate}) command (@pxref{Validate}).
+PSGML has some options in what features it uses and what markup it
+creates.  You have to set these options to make PSGML's behavior
+consistent with your SGML declaration and personal preferences.
+@defopt sgml-omittag
+Set this to @code{t} if the SGML declaration has @samp{OMITTAG YES} and
+to @code{nil} otherwise.
+@end defopt
+@defopt sgml-shorttag
+Set this to @code{t} if the SGML declaration has @samp{SHORTTAG YES} and
+to @code{nil} otherwise.
+@end defopt
+@defopt sgml-always-quote-attributes
+If non-nil, quote all attribute values inserted after finishing edit
+attributes.  If this variable is @code{nil} and @code{sgml-shorttag} is
+non-@code{nil}, attribute values that consists of only name characters
+will not be quoted.
+@end defopt
+@defopt sgml-minimize-attributes
+Determines minimization of attributes inserted by edit-attributes.  If
+non-nil, omit attribute name if the attribute value is from a token
+group.  If @code{max}, omit attributes with default value.  Minimization
+will only be done if they produce legal SGML (assuming
+@code{sgml-omittag} and @code{sgml-shorttag} are set correctly).
+@end defopt
+@c --------------------------------------------------------------------------
+@node Managing the DTD, Edit, SGML declaration, Top
+@comment  node-name,  next,  previous,  up
+@chapter Document Type Declaration
+@cindex DOCTYPE
+@findex sgml-parse-prolog
+PSGML needs to know about the DTD you are using for many of its commands.
+You can use PSGML without specifying a DTD, it will then accept any tags
+and assume a content model of @code{ANY} with no omissible tags.
+If you have a @samp{DOCTYPE} declaration in your file, PSGML will try to
+parse this.  Either the first time you do something that needs to parse
+the document or with the command @code{sgml-parse-prolog}.  Big DTDs
+take some time to parse.
+@vindex sgml-system-path
+@vindex sgml-default-dtd-file
+@vindex sgml-parent-document
+You can have the @samp{DOCTYPE} declaration in another file either by
+setting @code{sgml-parent-document} to the other file or by creating a
+saved DTD and setting @code{sgml-default-dtd-file} to that file.  If
+@code{sgml-default-dtd-file} contains a relative file name, the
+directories in @code{sgml-system-path} will be searched for the file.
+@findex sgml-save-dtd
+@findex sgml-load-dtd
+If parsing the DTD takes too long time you can save the parsed DTD in a
+file using the command @kbd{M-x sgml-save-dtd}.  Next time PSGML can
+load that file instead of parsing the DTD.  For PSGML to find the saved
+DTD you must either save the DTD using the default name or do a @kbd{M-x
+sgml-save-options} after saving the DTD.  To directly use an already
+parsed and saved DTD, load the file containing the saved DTD with the
+command @kbd{M-x sgml-load-dtd}.
+When the DTD has been parsed or loaded the name of the document element
+will be displayed in the mode line inside brackets.  If there was an
+error parsing the DTD or there is no DTD, the mode line will display
+@samp{[ANY]}.
+@defopt sgml-default-dtd-file
+This is the default file name for saved DTD.  This is set by
+@code{sgml-mode} to the buffer file name less extension plus the
+extension @code{.ced}, if that file exists.  Can be changed in the Local
+variables section of the file.
+@end defopt
+@defopt sgml-parent-document
+This can be set to the name (a string) of a file containing the
+@samp{DOCTYPE} declaration to use, or a list @code{(@var{filename}
+@var{doctypename})}, where @var{filename} is the name of a file
+containing the @samp{DOCTYPE} declaration to use, with the modification
+that the document type name is @var{doctypename}.
+@end defopt
+If you change the doctype you must execute @code{sgml-parse-prolog},
+changes in the doctype are not automatically recognized.
+@defopt sgml-custom-dtd
+Menu entries to be added to the DTD menu.  The value should be a list of
+entries to be added to the DTD menu.
+Every entry should be a list. The first element of the entry is a string
+used as the menu entry.  The second element is a string containing a
+doctype declaration (this can be nil if no doctype).  The rest of the
+list should be a list of variables and values.  For backward
+compatibility a single string instead of a variable is assigned to
+@code{sgml-default-dtd-file}.  All variables are made buffer local and
+are also added to the buffers local variables list.
+When an entry is selected from the DTD menu, the doctype declaration will
+be inserted, the variables will be set to the values in the entry and a
+local variables list will be created in the buffer.
+Example:
+@example
+(("HTML" nil
+sgml-default-dtd-file "~/sgml/html.ced"
+sgml-omittag nil sgml-shorttag nil)
+("HTML+" "<!doctype htmlplus system 'htmlplus.dtd'>"
+"~/sgml/htmlplus.ced"
+sgml-omittag t sgml-shorttag nil)
+("DOCBOOK" "<!doctype docbook system 'docbook.dtd'>"
+"~/sgml/docbook.ced"
+sgml-omittag nil sgml-shorttag t)))
+@end example
+@end defopt
+@c ---------------------------------------------------------------------------
+@node  Edit, Display, Managing the DTD, Top
+@comment  node-name,  next,  previous,  up
+@chapter Commands for editing
+@menu
+* Insert::                      Inserting Markup
+* Complete::                    Markup completion
+* Information::                 Showing information
+* Indent::                      Indentation according to structure
+* Move::                        Move in the element structure
+* Attributes::                  Editing attributes
+* Change and delete::           Changing and deleting markup
+@end menu
+@c ------------------------------------------------------------------
+@node Insert, Complete, Edit, Edit
+@comment  node-name,  next,  previous,  up
+@section Inserting Markup
+@c erik says "inserts" ??
+The commands that insert start-tags works only if the document has an
+associated DTD.
+Keyboard commands for inserting:
+@table @kbd
+@kindex C-c <
+@findex sgml-insert-tag
+@item C-c <
+Will ask, for the tag to insert, in the mini-buffer with completion on the
+tags that are valid at point (@code{sgml-insert-tag}).
+If the option @code{sgml-balanced-tag-edit} is non-nil, inserting a
+start-tag will also insert the corresponding end-tag.  If, in addition,
+@code{sgml-auto-insert-required-elements} is non-nil, tags for elements
+required between the inserted tags will also be inserted.
+The list of valid tags, computed for a position in the buffer, will
+contain:
+@enumerate
+@item
+The end-tag for the current element, if it can be ended at the position
+and @code{sgml-balanced-tag-edit} is nil.  Furthermore it will contain
+end-tags for enclosing elements if the necessary omissible end-tag
+declarations have been made in the DTD.
+@item
+The start-tags of all elements that could occur after point.  If
+@code{sgml-omittag-transparent} is nil, the above will be limited to the
+elements that can occur within the current element.
+@end enumerate
+@kindex C-c C-e
+@findex sgml-insert-element
+@item C-c C-e
+Insert start and end-tags for an element (@code{sgml-insert-element}).
+The name of the element is read from the mini-buffer with completion on
+valid elements.
+If @code{sgml-omittag-transparent} is nil, the list of valid elements
+will only contain the elements that can be in the content of the current
+element.
+Required elements in the content will be automatically inserted if the
+option @code{sgml-auto-insert-required-elements} is non-nil.
+@kindex C-c C-r
+@findex sgml-tag-region
+@item C-c C-r
+Makes the region into a new element (@code{sgml-tag-region}).  Reads
+element name from mini-buffer with completion as for @kbd{C-c C-e}.
+@kindex C-c /
+@findex sgml-insert-end-tag
+@item C-c /
+Inserts an end-tag for the current element (@code{sgml-insert-end-tag}).
+@kindex C-c RET
+@findex sgml-split-element
+@item C-c RET
+Split the current element at point.  If repeated, the containing element
+will be split before the beginning of then current element.
+Typical use is to start a new paragraph element when inside a paragraph.
+@kindex C-c +
+@findex sgml-insert-attribute
+@item C-c +
+Read attribute name and value from mini-buffer and insert attribute
+specification (@code{sgml-insert-attribute}).  If point is immediately
+after a start-tag, this command operates on that start-tag.  Otherwise
+the command will operate on the element after point.
+The attribute name will be read with completion.  If the attribute has a
+token list as declared value the attribute value will also be read with
+completion.  The prompt for attribute value will typically look like:
+@example
+Value for @var{attribute} (@var{type} Default: @var{current value}):
+@end example
+@end table
+Menu bar:
+@table @samp
+@item Markup
+Selecting from this menu will insert markup.  The menu contains
+sub menus with tags and with entities, some other markup and a user
+defined section.
+Sub menus:
+@item Insert element
+Pops up a menu of valid elements and insert start and end-tags for
+the selected element.  Selections from the menu works like the @kbd{C-c
+C-e} command.
+@item Insert start-tag
+Pops up a menu of valid start-tags and insert the selected tag.  The
+menu has the same start-tags as the completion list for @kbd{C-c <}.
+@item Insert end-tag
+Pops up a menu of valid end-tags and insert the selected tag.
+@item Tag region
+Pops up a menu of valid elements and tag the region with the
+selection.  Selections from the menu works like the @kbd{C-c C-r}
+command.
+@item Insert entity
+Menu of all general entities defined in the DTD.
+@item Insert attribute
+Pops up a menu with all the attributes of an element.  The element is
+either the one which start-tag is immediately before point or the
+element after point.  Selecting from this menu edits the attribute
+specification list for the element.
+The menu has a sub menu for every attribute which declared value is a
+token list.  The rest of the attributes are collected in one sub menu.
+For the token list attributes, selecting a value will insert that
+attribute-value pair.  Selecting some other attribute reads the
+attribute-value from the mini-buffer and inserts the attribute value
+pair.
+@end table
+@kindex S-@key{mouse-1}
+A menu is also available directly with a mouse button click in the
+buffer.  In GNU Emacs it is the first mouse button combined with shift
+(@kbd{S-@key{mouse-1}}).  In Lucid Emacs it is bound to the third mouse
+button.  The mouse button click will pop-up a menu of valid tags or a
+menu of attributes if the point is in a start-tag.  The attributes menu
+works as the ``Insert attribute'' menu from the menu-bar.  The tags list
+is the list of valid tags described above for command @kbd{C-c <}.
+Selection from the tags menu works like the @kbd{C-c <} command, with
+the following exception:
+You can tag a region, with start and end-tag.  There are two ways to
+indicate the region to mark:
+@enumerate
+@item
+Use the normal mouse commands to mark region.
+For this to work you must either use @dfn{transient mark mode}
+(@pxref{Transient Mark, , Transient Mark Mode, emacs, The Emacs
+Editor}) or set the option @code{sgml-tag-region-if-active} to non-nil
+(don't set this unless you are sure that you want it).
+@item
+Alternatively make a secondary selection, this is done by holding down
+the meta key and using the mouse buttons.
+@xref{Secondary selection, , , emacs, The Emacs Editor}.
+Some window managers intercept these events, which makes it hard use the
+secondary selection in Emacs.
+@end enumerate
+@defopt sgml-balanced-tag-edit
+If non-nil, inserting a start-tag will also insert the corresponding
+end-tag.
+@end defopt
+@defopt sgml-auto-insert-required-elements
+If non-nil, automatically inserts required elements in the content
+of an inserted element.
+@end defopt
+@defopt sgml-omittag-transparent
+If non-nil, will show legal tags inside elements with omissible start-tags
+and legal tags beyond omissible end-tags.
+@end defopt
+@defopt sgml-tag-region-if-active
+If non-nil, the @samp{Insert tags} menu will tag a region if the region
+is considered active by emacs.  If nil, region must be active and
+@code{transient-mark-mode} must be on for the region to be tagged.
+@end defopt
+@defopt sgml-custom-markup
+Menu entries to be added to the Markup menu.  The value should be a list
+of lists of two strings.  The first string is the menu line and the
+second string is the text inserted when the menu item is selected.  The
+second string can contain a @samp{\r} where the cursor should be left.
+Also, if a selection is made according to the same rules as for the
+@kbd{S-mouse-1} menu, the selection is replaced with the second string
+and @samp{\r} is replaced with the selection.
+Example:
+@example
+(("Version1" "<![%Version1[\r]]>")
+("New page"  "<?NewPage>"))
+@end example
+@end defopt
+@c -------------------------------------------------------------------------
+@node Complete, Information, Insert, Edit
+@comment  node-name,  next,  previous,  up
+@section Markup completion
+@kindex M-TAB
+@findex sgml-complete
+If you are typing in markup directly, @kbd{M-TAB} will help you by
+completing a tag name, an entity name or a markup declaration name.  If
+you type @kbd{M-TAB} after a plain word, @code{ispell-complete-word}
+will be invoked instead.
+If you have typed (@point{} marks the position of point)
+@example
+&At@point{}
+@end example
+@noindent and type @kbd{M-TAB} (assuming you use the @file{ISOLat1}
+entity set) you get:
+@example
+&Atilde@point{}
+@end example
+@c ---------------------------------------------------------------------------
+@node Information, Indent, Complete, Edit
+@comment  node-name,  next,  previous,  up
+@section Showing information
+Commands for showing information obtained by parsing the buffer.
+@table @kbd
+@kindex C-c C-c
+@findex sgml-show-context
+@item C-c C-c
+Shows in the message area: context at point, if in a tag or in mixed
+content and the open elements (@code{sgml-show-context}).
+@kindex C-c C-w
+@findex sgml-what-element
+@item C-c C-w
+Shows what element the character after point (under the cursor) belongs
+to; also shows context of element (@code{sgml-what-element}).
+@kindex C-c C-t
+@findex sgml-list-valid-tags
+@item C-c C-t
+List contextually valid tags (@code{sgml-list-valid-tags}).  Displays
+information about current element, all valid end-tags, valid start-tags
+in current element, and start-tags valid at this point but in other
+elements together with the tags omitted.
+@end table
+You can make the mode-line display the name of the current open element
+by setting the @code{sgml-live-element-indicator} variable.  Setting
+this will make all commands slower due to the work needed to keep the
+mode-line up to date.
+@defopt sgml-live-element-indicator
+If non-nil, indicate current element in mode line.
+NOTE: Setting this implies that every command can cause a parse.
+@end defopt
+@c --------------------------------------------------------------------------
+@node  Indent, Move, Information, Edit
+@comment  node-name,  next,  previous,  up
+@section Indentation according to structure
+@kindex @key{TAB}
+@kindex @key{LFD}
+@findex sgml-indent-or-tab
+@findex newline-and-indent
+You can indent a line according to the depth of element nesting at the
+beginning of the line.  To indent the current line use @kbd{@key{TAB}}.
+You can also use @kbd{@key{LFD}} (@code{newline-and-indent}) to start a
+new line with correct indentation.
+@defopt sgml-indent-step
+How much to increment indent for every element level.  If nil, no
+indentation.
+If this is nil, @kbd{@key{TAB}} will insert a tab instead of indenting.
+@end defopt
+@defopt sgml-indent-data
+If non-nil, indent in data/mixed context also.
+@end defopt
+@c ---------------------------------------------------------------------------
+@node  Move, Attributes, Indent, Edit
+@comment  node-name,  next,  previous,  up
+@section Move in the element structure
+These commands move in the element structure.  The commands uses
+knowledge of SGML syntax, and if available the specific DTD.
+@table @kbd
+@kindex C-M-a
+@findex sgml-beginning-of-element
+@item C-M-a
+Move to the (content) beginning of the current element
+(@code{sgml-beginning-of-element}).
+@kindex C-M-e
+@findex sgml-end-of-element
+@item C-M-e
+Move to the (content) end of the current element (@code{sgml-end-of-element}).
+@kindex C-M-f
+@findex sgml-forward-element
+@item C-M-f
+Move forward by element (@code{sgml-forward-element}).
+@kindex C-M-b
+@findex sgml-backward-element
+@item C-M-b
+Move backward by element (@code{sgml-backward-element}).
+@kindex C-M-u
+@findex sgml-backward-up-element
+@item C-M-u
+Move up to before current element (@code{sgml-backward-up-element}).
+@kindex C-c C-n
+@findex sgml-up-element
+@item C-c C-n
+Move up to after current element (@code{sgml-up-element}).
+@kindex C-M-d
+@findex sgml-down-element
+@item C-M-d
+Move down to the (content) beginning of the next element
+(@code{sgml-down-element}).
+@kindex C-c C-d
+@findex sgml-next-data-field
+@item C-c C-d
+Move to the next place where data is allowed (@code{sgml-next-data-field}).
+@end table
+You can also move to the next place where there is some structural error
+with @kbd{C-c C-o} (@pxref{Validate}).
+@c ---------------------------------------------------------------------------
+@node Attributes, Change and delete, Move, Edit
+@comment  node-name,  next,  previous,  up
+@section Editing attributes
+@findex sgml-edit-attributes
+@kindex C-c C-a
+If you want to change the attributes of a start-tag you can simply edit
+them directly in the buffer.  Or you can place the cursor at or after
+the start-tag and use the @code{sgml-edit-attributes} command, available
+from the @samp{SGML}-menu or on @kbd{C-c C-a}.  This will create a new
+Emacs window with all possible attributes listed in the form
+@example
+@var{attribute name} = @var{current value}.
+@end example
+The @var{current value} may be shown as @samp{#DEFAULT} if the attribute
+has not been given a value in the start-tag.  The list also contains the
+attributes declaration as a comment.  Note also that the @var{current
+value} is show without eventual quotes.
+@kindex C-c C-d
+@kindex @key{TAB}
+It is now possible to edit the attribute values.  You can move to the
+next attribute with @kbd{@key{TAB}}.  If you want to let an attribute
+have its default value use @kbd{C-c C-d}, this will insert a
+@samp{#DEFAULT} in the value field.
+If Emacs is running in an X window, the @samp{#DEFAULT} will be
+underlined to distinguish it from normal values.
+@kindex C-c C-c
+Finish the editing with @kbd{C-c C-c}; this will replace the attribute
+values in the main buffer with those edited.  Note that values will be
+quoted as needed.
+If you want to abort the editing, you can remove the window with
+@kbd{C-x 0} or if you want it neat, kill the buffer and remove the
+window.
+Some other keys are:
+@table @kbd
+@kindex C-a
+@findex sgml-edit-attrib-field-start
+@item C-a
+Go to the beginning of the value field
+(@code{sgml-edit-attrib-field-start}).
+@kindex C-e
+@findex sgml-edit-attrib-field-end
+@item C-e
+Go to the end of the value field
+(@code{sgml-edit-attrib-field-end}).
+@kindex C-c C-k
+@findex sgml-edit-attrib-clear
+@item C-c C-k
+Clear the value field
+(@code{sgml-edit-attrib-clear}).
+@kindex C-c C-d
+@findex sgml-edit-attrib-default
+@item C-c C-d
+Set the value field to @samp{#DEFAULT}
+(@code{sgml-edit-attrib-default}).  This is a special value that will
+make the attribute be implied.
+@end table
+@c --------------------------------------------------------------------------
+@node Change and delete,  , Attributes, Edit
+@comment  node-name,  next,  previous,  up
+@section Changing and deleting markup
+@table @kbd
+@kindex C-c =
+@findex sgml-change-element-name
+@item C-c =
+Change the name of the current element (@code{sgml-change-element-name}).
+Tries to translate attribute specifications.  An attribute will be
+translated to an attribute with the same name.  If the new element has
+no attribute with the same name, the attribute will be ignored.  If
+there is an attribute with the same name but different declared content,
+a warning is given.
+ID attributes are handled specially, an attribute with declared value ID
+will always be translated to the attribute with declared value ID.
+@kindex C-c C-k
+@findex sgml-kill-markup
+@item C-c C-k
+Kill next tag, markup declaration or process instruction
+(@code{sgml-kill-markup}).
+@kindex C-M-k
+@findex sgml-kill-element
+@item C-M-k
+Kill the element following the cursor (@code{sgml-kill-element}).
+@kindex C-c -
+@findex sgml-untag-element
+@item C-c -
+Remove tags from current element (@code{sgml-untag-element}).
+@kindex C-c #
+@findex sgml-make-character-reference
+@item C-c #
+Convert character after point to a character reference
+(@code{sgml-make-character-reference}).  If called with a numeric
+argument, convert a character reference back to a normal character.
+@kindex C-c C-q
+@findex sgml-fill-element
+@item C-c C-q
+Fills an element as a paragraph (@code{sgml-fill-element}).  This is a
+substitute for the normal @code{fill-paragraph}.  The command uses
+heuristics to decide what should be a paragraph.
+@enumerate
+@item
+If point is in an element content, recursively fill the sub-elements.
+@item
+Find the biggest element with mixed content containing point.
+@item
+If the above element is mixed but contains elements with pure element
+content then fill what is between the pure elements as paragraphs and
+fill the pure elements recursively.
+@end enumerate
+@findex sgml-normalize
+@item M-x sgml-normalize
+Normalize the document in the buffer.  This will
+@enumerate
+@item
+insert missing tags,
+@item
+replace minimized tags with full tags,
+@item
+fix attribute specification lists according to options set.
+@end enumerate
+There is one option for the normalize command.  With its default value,
+normalize may actually change the data content of some elements.  But
+only by removing some white-space from the end of elements with omitted
+end-tags.
+@end table
+@defopt sgml-normalize-trims
+If non-nil, @code{sgml-normalize} will trim off white space from end of
+element when adding end-tag.
+Default: @code{t}.
+@end defopt
+@c ---------------------------------------------------------------------------
+@node Display, Bugs, Edit, Top
+@comment  node-name,  next,  previous,  up
+@chapter Appearance of text in the buffer
+@menu
+* Fold::                        Folding editing
+* Highlight::                   Highlighting markup
+@end menu
+@c ---------------------------------------------------------------------------
+@node  Fold, Highlight, Display, Display
+@comment  node-name,  next,  previous,  up
+@section Folding editing
+With these commands you can make parts of the text temporarily invisible
+to make it easier to see the overall structure of your text.
+When folding a region all the lines but the first will be invisible.
+The first line of the region will still be visible with an ellipsis at
+the end.
+@xref{Outline Mode, , , emacs, The Emacs Editor}.
+@table @kbd
+@kindex C-c C-f C-r
+@findex sgml-fold-region
+@item C-c C-f C-r
+The region between point and mark will be folded (@code{sgml-fold-region}).
+@kindex C-c C-f C-e
+@findex sgml-fold-element
+@item C-c C-f C-e
+The region between the start and end of the current element will be
+folded (@code{sgml-fold-element}).
+This command can also fold the SGML declaration or the DOCTYPE
+declaration.
+@kindex C-c C-f C-s
+@findex sgml-fold-subelement
+@item C-c C-f C-s
+Fold all the sub elements of the current element
+(@code{sgml-fold-subelement}).
+@kindex C-c C-s
+@kindex C-c C-u C-l
+@findex sgml-unfold-line
+@item C-c C-s
+@itemx C-c C-u C-l
+Unfold the current line, assuming it is the first line of a folded
+region (@code{sgml-unfold-line}).
+@kindex C-c C-u C-e
+@findex sgml-unfold-element
+@item C-c C-u C-e
+Make all lines in current element visible (@code{sgml-unfold-element}).
+@kindex C-c C-u C-a
+@findex sgml-unfold-all
+@item C-c C-u C-a
+Make all lines in current buffer visible (@code{sgml-unfold-all}).
+@kindex C-c C-f C-x
+@findex sgml-expand-element
+@item C-c C-f C-x
+Unfold current element and then fold the subelements
+(@code{sgml-expand-element}).  If the current element is folded this
+expands what is visible.
+@end table
+@c ---------------------------------------------------------------------------
+@node  Highlight,  , Fold, Display
+@comment  node-name,  next,  previous,  up
+@section Highlighting markup
+PSGML can highlight the markup as it parses it by giving the markup a
+different @dfn{face} (@pxref{Faces, , Using Multiple Typefaces, emacs,
+The Emacs Editor}).  The highlighting will only be done if the variable
+@code{sgml-set-face} is non-nil.  The default settings make tags bold
+and comments italic, but this can be modified with the variable
+@code{sgml-markup-faces}.
+@findex sgml-clear-faces
+To remove the highlighting type @kbd{M-x sgml-clear-faces}.
+@defopt sgml-set-face
+If non-nil, psgml will set the face of parsed markup.
+@end defopt
+@defopt sgml-markup-faces
+A list of markup to face mappings.
+Each element looks like @code{(@var{markup-type} . @var{face})}.
+Possible values for @var{markup-type} is:
+@table @code
+@item comment
+comment declaration
+@item doctype
+doctype declaration
+@item end-tag
+end-tag
+@item ignored
+ignored marked section
+@item ms-start
+marked section end, if not ignored
+@item ms-end
+marked section start, if not ignored
+@item pi
+processing instruction
+@item sgml
+SGML declaration
+@item start-tag
+start-tag
+@item entity
+entity reference
+@item shortref
+short reference
+@end table
+@end defopt
+@c ------------------------------------------------------------------
+@node Bugs, Index, Display, Top
+@comment  node-name,  next,  previous,  up
+@chapter Bugs
+If you encounter something that you think is a bug, please report
+it.  Try to include a clear description of the undesired behaviour.
+A test case that exhibits the bug, would also be useful.
+You can report a bug with the command @kbd{M-x sgml-submit-bug-report}.
+When PSGML needs contextual information it parses the document up to
+the point. During the parsing, it builds a parse tree.  The parse
+tree is used to initialize the next parse, to avoid having to parse
+things already parsed.  Changes to the buffer is supposed to prune
+the tree of all outdated information.  But if you get strange
+complaints from the parser, try and back up a bit and use @kbd{C-c
+C-o} (@code{sgml-next-trouble-spot}).
+@c ------------------------------------------------------------------
+@node Index,  , Bugs, Top
+@comment    node-name,         next,       previous, up
+@chapter Index
+@printindex cp
+@bye

Mercurial > hg > xemacs-beta

comparison man/psgml.texi @ 0:376386a54a3c r19-14