1 \input texinfo @c -*-texinfo-*-
4 @setfilename ../info/psgml.info
5 @c @setfilename psgml.info
7 @c @setchapternewpage odd
12 @c $Id: psgml.texi,v 1.8 2005/03/02 19:44:20 lenst Exp $
17 * PSGML: (psgml). PSGML, a major mode for SGML documents.
23 Documentation for PSGML, a major mode for SGML.
25 Copyright 1994, 1996, 1998 Lennart Staflin
27 Permission is granted to make and distribute verbatim
28 copies of this manual provided the copyright notice and
29 this permission notice are preserved on all copies.
32 Permission is granted to process this file through TeX
33 and print the results, provided the printed document
34 carries a copying permission notice identical to this
35 one except for the removal of this paragraph (this
36 paragraph not being relevant to the printed manual).
39 Permission is granted to copy and distribute modified
40 versions of this manual under the conditions for
41 verbatim copying, and provided that the entire
42 resulting derived work is distributed under the terms
43 of a permission notice identical to this one.
45 Permission is granted to copy and distribute
46 translations of this manual into another language,
47 under the above conditions for modified versions,
48 except that this permission notice may be stated in a
49 translation approved by the Free Software Foundation.
55 @title Editing SGML with Emacs and PSGML
56 @author Lennart Staflin
58 @c The following two commands
59 @c start the copyright page.
61 @vskip 0pt plus 1filll
62 Copyright @copyright{} 1994, 1996, 1998 Lennart Staflin
66 Permission is granted to make and distribute verbatim
67 copies of this manual provided the copyright notice and
68 this permission notice are preserved on all copies.
71 Permission is granted to process this file through TeX
72 and print the results, provided the printed document
73 carries a copying permission notice identical to this
74 one except for the removal of this paragraph (this
75 paragraph not being relevant to the printed manual).
78 Permission is granted to copy and distribute modified
79 versions of this manual under the conditions for
80 verbatim copying, and provided that the entire
81 resulting derived work is distributed under the terms
82 of a permission notice identical to this one.
84 Permission is granted to copy and distribute
85 translations of this manual into another language,
86 under the above conditions for modified versions,
87 except that this permission notice may be stated in a
88 translation approved by the Free Software Foundation.
91 @node Top, Introduction, (dir), (dir)
92 @comment node-name, next, previous, up
96 PSGML is a major mode for editing SGML documents. This is the DRAFT
97 documentation for PSGML version 1.4.
101 * Introduction:: Introduction
102 * Install:: How to install PSGML
103 * Invoke:: How to invoke PSGML
104 * Entity manager:: The Entity Manager
105 * Validate:: Running an external SGML parser
106 * SGML declaration:: Using an SGML declaration
107 * Managing the DTD:: Specifying what DTD to use
108 * Edit:: Commands for editing
109 * Display:: Appearance of text in the buffer
110 * Miscellaneous options::
111 * Bugs:: Reporting bugs
116 @c *** section about error recovery ??
119 @c ------------------------------------------------------------------
121 @node Introduction, Install, Top, Top
122 @comment node-name, next, previous, up
123 @chapter Introduction
128 @cindex SGML Declaration
130 PSGML is a major mode for editing SGML and XML documents. It works with
131 GNU Emacs 19.34, 20.3 and later or with XEmacs 19.9 and later. PSGML
132 contains a simple SGML parser and can work with any DTD. Functions
133 provided includes menus and commands for inserting tags with only the
134 contextually valid tags, identification of structural errors, editing of
135 attribute values in a separate window with information about types and
136 defaults, and structure based editing.
138 SGML, a language for encoding the structure of a document, is an ISO
139 standard: ISO 8879:1986 ``Information processing -- Text and office
140 systems -- Standard Generalized Markup Language (SGML)''.
142 A good introduction to SGML is @cite{A Gentle Introduction to SGML}
143 produced by Text Encoding Initiative (this is really chapter 2 of TEI
144 P3). This can be found on
147 @file{ftp://ftp.ifi.uio.no/pub/SGML/TEI/P3SG.DOC}.
150 A SGML document has three major parts, in order:
154 SGML Declaration (@samp{<!SGML "ISO 8879:1986" @dots{} >})
156 Document Type Declaration (@samp{<!DOCTYPE @var{name} @dots{} >})
158 Document Element (@samp{<@var{name}> @dots{} </@var{name}>})
161 The SGML declaration contains general information about character sets,
162 concrete syntax, and SGML features used. PSGML does not use the SGML
163 Declaration, it can be left out, and if included is ignored. Many SGML
164 systems allow the SGML declaration to be defaulted. PSGML always use
165 the Concrete Reference Syntax but without limitations on
166 lengths. Features used has to be indicated with variables (@pxref{SGML
169 The document type declaration specifies the valid elements and entities
170 and how they can be nested. A document type is usually needed, but can
171 reside in another file (@pxref{Managing the DTD}).
173 The system declaration for PSGML:
175 SYSTEM "ISO 8879:1986"
177 BASESET "ISO 646-1983//CHARSET
178 International Reference Version (IRV)//ESC 2/5 4/0"
180 CAPACITY PUBLIC "ISO 8879:1986//CAPACITY Reference//EN"
182 MINIMIZE DATATAG NO OMITTAG YES RANK NO SHORTTAG YES
183 LINK SIMPLE NO IMPLICIT NO EXPLICIT NO
184 OTHER CONCUR NO SUBDOC YES 1 FORMAL YES
186 SYNTAX PUBLIC "ISO 8879:1986//SYNTAX Reference//EN"
187 @c SYNTAX PUBLIC "ISO 8879:1986//SYNTAX Core//EN"
189 GENERAL NO MODEL NO EXCLUDE NO CAPACITY NO
190 NONSGML NO SGML NO FORMAL NO
191 SDIF PACK NO UNPACK NO
195 @c -------------------------------------------------------------------------
196 @node Install, Invoke, Introduction, Top
197 @comment node-name, next, previous, up
198 @chapter Installing PSGML
200 As of @cite{XEmacs 21.0} (with @cite{EFS} installed) you can get the
201 latest @cite{psgml} package by evaluating the follwing two lines within
205 (require 'package-get)
206 (package-get 'psgml nil)
209 To install PSGML in XEmacs versions prior to 21.0 you first need to
210 uncompress and unpack the source archive. This is done with the
211 @code{gunzip} and @code{tar} commands.
214 gunzip psgml-1.3.1.tar.gz; tar xf psgml-1.3.1.tar
217 This should create a subdirectory to the current directory with the
218 source code. This directory contains a @code{configure} command (see the
219 file INSTALL for more information about configure). You can use the
220 @code{configure} command to configure the package or you can load the
221 file @file{psgml-maint} and execute the @code{psgml-compile-files}
224 Place the @file{*.el} and the @file{*.elc} files in a directory where
225 Emacs can find it (i.e. one of the directories in the @code{load-path}
226 variable, you can add a directory to this variable in your
229 If you use the @code{configure} approach, compile psgml with @code{make}
230 and the you can run @code{make install} to install it in the system
231 library @file{site-lisp}. The location of @file{site-lisp} is figured
232 out by @code{configure}, but you can change it in the @file{Makefile}.
234 Put the following line in your .emacs:
237 (autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t)
238 (autoload 'xml-mode "psgml" "Major mode to edit XML files." t)
241 You may also want to set up search paths for external entities,
242 @xref{Entity manager}.
244 The @file{psgml.info} is the documentation for PSGML in the info format.
245 You can read this with the Emacs command @kbd{C-u C-h i}. You can also
246 install the file in your systems info directory and edit the
247 @file{dir} file to include @file{psgml.info} in the menu.
249 The info file @file{psgml.info} is created from the texinfo file
250 @file{psgml.texi}. The texinfo file can also be used to create a hard
251 copy of the documentation. To do this you need the @TeX{} program and a
252 copy of @file{texinfo.tex}.
257 @c --------------------------------------------------------------------------
258 @node Invoke, Entity manager, Install, Top
259 @comment node-name, next, previous, up
260 @chapter How to invoke PSGML
266 PSGML defines major modes called @code{sgml-mode} and @code{xml-mode}.
267 Files with extensions @file{.sgml}, @file{.sgm} or @file{.dtd} will
268 automatically be edited in SGML mode. To edit some other file in SGML
269 mode, type @kbd{M-x sgml-mode @key{RET}} after finding the file.
270 To edit XML files, type @kbd{M-x xml-mode @key{RET}}.
272 If you can modify the file you can add a @dfn{Local Variables} list
273 (@pxref{file variables, , Local Variables in Files, emacs, The Emacs
274 Editor}) to the end of the file. This can make Emacs
275 automatically set sgml mode and user options when the file is loaded.
276 The simplest Local Variables list would look like:
286 You can also put a line at the top of the file to tell emacs to use sgml
290 <!-- -*- sgml -*- -->
293 For XML replace @samp{sgml} with @samp{xml} in the above examples.
294 But remember that you can't have a comment before the @emph{SGML
295 declaration} or the @emph{XML declaration}.
298 @c -------------------------------------------------------------------------
299 @node Entity manager, Validate, Invoke, Top
300 @comment node-name, next, previous, up
301 @chapter The Entity Manager
302 @cindex public identifier
303 @cindex system identifier
304 @cindex external identifier
305 @cindex entity catalog
307 @c *** sgml-sysid-resolve-functions
309 SGML can refer to an external file (really entity) with an
310 @emph{external identifier}, this is a @emph{public identifier} or a
311 @emph{system identifier}, or both.
313 A typical public identifier looks like
316 PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN"
320 where ``ISO 8879:1986'' is the owner, ``ENTITIES'' is the text class and
321 ``Added Latin 1'' is the text description (and ``EN'' is language).
323 A system identifier looks like
326 SYSTEM "htmlplus.dtd"
329 @noindent where ``htmlplus.dtd'' is a system-specific identifier.
331 To map external identifiers to file names, PSGML first searches entity
332 catalog files and then search the list of file name templates in the
333 variable @code{sgml-public-map}.
335 The catalog format is according to SGML/Opens resolution on entity
336 management. The catalog consists of a series of entries and comments. A
337 comment is delimited by @samp{--} like in a markup declaration.
338 The entry types recognized are described in the following table.
342 @item public @var{pubid} @var{file}
343 The @var{file} will be used for the entity text of an entity
344 with the public identifier @var{pubid}.
346 @item entity @var{name} @var{file}
347 The @var{file} will be used for the entity text of an entity
348 with the name @var{name}. If the @var{name} starts with a @samp{%} the
349 rest of the name will be matched against parameter entities.
351 @item doctype @var{name} @var{file}
352 The @var{file} will be used for the entity text of an entity
353 used as external subset of a document declaration with @var{name} as
356 @item sgmldecl @var{file}
357 Used to specify a default SGML declaration. Recognized but not used by
358 PSGML other than to pass to an external validation command
359 (@code{sgml-validate-command}).
363 When PSGML is looking for the file containing an external entity, the
364 following things will be tried in order:
368 @vindex sgml-system-identifiers-are-preferred
370 Try the system identifier, as a file name, if there is a system
371 identifier and the variable @code{sgml-system-identifiers-are-preferred}
372 is non-@code{nil} and there is no elements containing @samp{%s} in
373 @code{sgml-public-map}. If the system identifier is a relative file name
374 it will be relative to the directory containing the defining entity.
377 Look thru each catalog in @code{sgml-local-catalogs} and
378 @code{sgml-catalog-files} in order. For each catalog look first for
379 entries matching the public identifier, if any. Then look for other
380 matching entries in the order they appear in the catalog.
382 Currently an entry will be ignored if it is matching but its file is
383 non-existent or unreadable. (This is under reconsideration, perhaps it
384 should signal error instead).
387 Try the system identifier, if any, as a file name.
388 If @code{sgml-system-identifiers-are-preferred} is @code{nil}
389 and there is no elements containing @samp{%s} in @code{sgml-public-map}.
392 Try the entries in @code{sgml-public-map}. Using the catalogs are
393 preferred. The @code{sgml-public-map} may disappear in a future version
394 of PSGML (not soon though).
398 The @code{sgml-public-map} variable can contain a list of file name
399 templates where @samp{%P} will be substituted with the whole public
400 identifier, owner is substituted for @samp{%O}, public text class for
401 @samp{%C}, and public text description for @samp{%D}. The text class
402 will be converted to lower case and the owner and description will be
403 transliterated according to the variable
404 @code{sgml-public-transliterations}. The templates in the list is tried
405 in order until an existing file is found. The @code{sgml-public-map} is
406 modeled after @file{sgmls} environment variable @code{SGML_PATH} and
407 psgml understand the following substitution characters: %%, %N, %P, %S,
408 %Y, %C, %L, %O, %T, and %V. The default value of
409 @code{sgml-public-map} is taken from the environment variable
412 Given the public identifier above and the file name template
413 @samp{/usr/local/lib/sgml/%o/%c/%d}, the resulting file name is
416 /usr/local/lib/sgml/ISO_8879:1986/entities/Added_Latin_1
419 Note: blanks are transliterated to @samp{_} (and also @samp{/} to
420 @samp{%}) and the text class is down cased.
424 @defopt sgml-catalog-files
425 This is a list of catalog entry files.
426 The files are in the format defined in the SGML Open Draft Technical
427 Resolution on Entity Management. The Emacs variable is initialized from
428 the environment variable @code{SGML_CATALOG_FILES} or if this variable
429 is undefined the default is
432 ("CATALOG" "/usr/local/lib/sgml/CATALOG")
436 @defopt sgml-local-catalogs
437 A list of SGML entity catalogs to be searched first when parsing the
438 buffer. This is used in addition to @code{sgml-catalog-files}, and
439 @code{sgml-public-map}. This variable is automatically local to the
443 @defopt sgml-system-identifiers-are-preferred
444 If @code{nil}, PSGML will look up external entities by searching the
445 catalogs in @code{sgml-local-catalogs} and @code{sgml-catalog-files} and
446 only if the entity is not found in the catalogs will a given system
447 identifier be used. If the variable is non-nil and a system identifier is
448 given, the system identifier will be used for the entity. If no system
449 identifier is given the catalogs will searched.
453 @defopt sgml-public-map
454 This should be a list of file name templates. This variable is
455 initialized from the environment variable @code{SGML_PATH}. This is
456 the same environment variable that @file{sgmls} uses. If the
457 environment variable is undefined the default is
460 ("%S" "/usr/local/lib/sgml/%o/%c/%d")
462 @c Mapping from public identifiers to file names.
465 @c the colon separated list in @code{SGML_PATH} is converted to a lisp list
467 @c -------------------------------------------------------------------------
468 @node Validate, SGML declaration, Entity manager, Top
469 @comment node-name, next, previous, up
470 @chapter Running an external SGML parser
473 @findex sgml-validate
474 PSGML can not validate an SGML document (see below what it can
475 and can't do). If you have a validating SGML parser, like
476 @file{sgmls}, you can run the parser on your file with the
477 command @kbd{C-c C-v} (@code{sgml-validate}).
479 Some variables control this function:
481 @defopt sgml-validate-command
482 The shell command to validate an SGML document.
484 This is a @code{format} control string that by default should contain two
485 @code{%s} conversion specifications: the first will be replaced by the
486 value of @code{sgml-declaration} (or the empty string, if nil); the
487 second will be replaced by the current buffer's file name (or the
488 empty string, if nil).
490 If @code{sgml-validate-files} is non-nil, the format string should contain
491 one @code{%s} conversion specification for each element of its result.
493 If sgml-validate-command is a list, then every element should be a
494 string. The strings will be tried in order and @samp{%}-sequences in the
495 string will be replaced according to the list below, if the string contains
496 @samp{%}-sequences with no replacement value the next string will be tried.
500 means the visited file of the current buffer
503 means the SGML declaration specified in the sgml-declaration variable
506 means the file containing the DOCTYPE declaration, if not in the buffer
509 The default value is @code{nsgmls -s %s %s}.
512 @defopt sgml-validate-files
513 If non-nil, a function of no arguments that returns a list of
514 file names. These file names will serve as the arguments to the
515 @code{sgml-validate-command} format control string instead of
519 @defopt sgml-declaration
520 The name of the SGML declaration file.
523 @defopt sgml-offer-save
524 If non-nil, @kbd{C-c C-v} (@code{sgml-validate}) will ask about
525 saving modified buffers before running the validate command.
526 The default value is @code{t}.
531 @findex sgml-next-trouble-spot
532 The built-in parser can find some markup errors. The command @kbd{C-c
533 C-o} (@code{sgml-next-trouble-spot}) is the best way to use the built-in
534 parser for this. To check the whole file go to the beginning of the
535 buffer and use @kbd{C-c C-o}.
537 Some of the markup errors not found are:
541 Errors in the SGML declaration.
543 Errors in attribute specifications.
545 Omitted start-tags for empty elements.
549 @c --------------------------------------------------------------------------
550 @node SGML declaration, Managing the DTD, Validate, Top
551 @comment node-name, next, previous, up
552 @chapter SGML Declaration
555 @cindex NAMECASE GENERAL
556 @cindex case sensitivity
558 PSGML does not understand the SGML declaration, it accepts one in the
559 file but it is ignored. If you have the SGML declaration in another
560 file you can make @file{sgmls} use it when you use the @kbd{C-c C-v}
561 (@code{sgml-validate}) command (@pxref{Validate}).
563 PSGML has some options in what features it uses and what markup it
564 creates. You have to set these options to make PSGML's behavior
565 consistent with your SGML declaration and personal preferences.
568 Set this to @code{t} if the SGML declaration has @samp{OMITTAG YES} and
569 to @code{nil} otherwise.
572 @defopt sgml-shorttag
573 Set this to @code{t} if the SGML declaration has @samp{SHORTTAG YES} and
574 to @code{nil} otherwise.
577 @defopt sgml-namecase-general
578 Set this to @code{t} if the SGML declaration has @samp{NAMECASE
579 GENERAL YES} and to @code{nil} otherwise. I.e., this controls whether
580 names, except entity names, will be case insensitive (translated to
584 @defopt sgml-always-quote-attributes
585 If non-nil, quote all attribute values inserted after finishing edit
586 attributes. If this variable is @code{nil} and @code{sgml-shorttag} is
587 non-@code{nil}, attribute values that consists of only name characters
591 @defopt sgml-minimize-attributes
592 Determines minimization of attributes inserted by edit-attributes. If
593 non-nil, omit attribute name if the attribute value is from a token
594 group. If @code{max}, omit attributes with default value. Minimization
595 will only be done if they produce legal SGML (assuming
596 @code{sgml-omittag} and @code{sgml-shorttag} are set correctly).
600 @c --------------------------------------------------------------------------
601 @node Managing the DTD, Edit, SGML declaration, Top
602 @comment node-name, next, previous, up
603 @chapter Document Type Declaration
607 @vindex sgml-default-doctype-name
608 PSGML needs to know about the DTD you are using for many of its commands.
609 If you do not have a @samp{DOCTYPE} declaration in your file,
610 PSGML will try assume that there is one of the form
613 <!DOCTYPE @var{name} SYSTEM>
616 where @var{name} is the value of @code{sgml-default-doctype-name}, if
617 the value is non-@code{nil}, else the GI of the first tag will be used.
619 @findex sgml-parse-prolog
620 @vindex sgml-auto-activate-dtd
621 PSGML will try to parse the document type declaration the first time
622 you do something that needs to parse the document or immediately if the
623 variable @code{sgml-auto-activate-dtd} is @code{t}. You can also
624 initiate the parsing of the document type declaration with the command
625 @code{sgml-parse-prolog}. Big DTDs take some time to parse.
627 When the DTD has been parsed or loaded the name of the document element
628 will be displayed in the mode line inside brackets. If there was an
629 error parsing the DTD or there is no DTD, the mode line will display
630 @samp{[ANY]} (*** this is not really correct! a DTD will be established
631 even if there are missing entities, it may even be empty).
634 * Precompiled DTD Subsets::
635 * Using a Split Document::
636 * Inserting a DOCTYPE::
637 * Information from the DTD::
642 @c ------------------------------------------------------------
643 @node Precompiled DTD Subsets, Using a Split Document, Managing the DTD, Managing the DTD
644 @comment node-name, next, previous, up
645 @section Precompiled DTD Subsets
647 If parsing the DTD takes too long time you can arrange to have PSGML
648 cache an internal complied version of the DTD. Caching can be done of
649 DTD fragments in favourable situations. It is possible to have an
650 external DTD subset cached but still have an internal DTD subset as long
651 as the internal subset does not define parameter entities that affect
652 the parsing of the external subset (*** what is the exact conditions?,
653 probably you can't use the cached external subset if the internal subset
654 defines parameter entities that are also defined in the external subset
657 @vindex sgml-ecat-files
658 @vindex sgml-local-ecat-files
659 To enable caching you have to create special catalog files, hereafter
660 called ECAT files due to (temporary) lack of imagination. These catalogs
661 have similar syntax to the entity catalogs and there are two variables
662 containing lists of catalogs to search: @code{sgml-ecat-files} and
663 @code{sgml-local-ecat-files}. The ECAT files can contain the following
667 @item file @var{dtdfile} @var{entitydef} @var{cfile}
668 The @var{dtdfile} is the name of a file containing a DTD subset that
669 should be cached in @var{cfile}. The @var{entitydef} is optional and if
670 given have the following syntax:
672 [ @var{name1} @var{literal1} @var{name2} @var{literal2} @dots{} ]
674 Using @var{entitydef} will modify the DTD subset by defining the
675 parameter entity with name @var{name1} to be @var{literal1}, @dots{}. The
676 cached version of the subset will be created with those entity
677 definitions, and when PSGML search for a matching cached subset will check
678 that the parameter entities in @var{entitydef} has been defined with
679 those values before trying to use @file{cfile}.
681 @item public @var{pubid} @var{entitydef} @var{cfile}
682 Cache the DTD subset with public identifier @var{pubid} in file
687 @defopt sgml-recompile-out-of-date-cdtd
688 If non-@code{nil}, out of date compiled DTDs will be automatically
689 recompiled. If the value is @code{ask}, PSGML will ask before
690 recompiling. A @code{nil} value will cause PSGML to silently load an out
691 of date compiled DTD. A DTD that refers to undefined external entities
692 is always out of date, thus in such case it can be useful to set this
693 variable to @code{nil}.
697 Previous versions of PSGML have had another way of speeding up DTD
698 parsing. This code remains in this version of PSGML, but is not actively
699 maintained and may disappear in the future.
701 @findex sgml-save-dtd
702 @findex sgml-load-dtd
703 @vindex sgml-default-dtd-file
704 You can save the parsed DTD in a file using the command @kbd{M-x
705 sgml-save-dtd}. Next time PSGML can load that file instead of parsing
706 the DTD. For PSGML to find the saved DTD you must either save the DTD
707 using the default name or do a @kbd{M-x sgml-save-options} after saving
708 the DTD. To directly use an already parsed and saved DTD, load the file
709 containing the saved DTD with the command @kbd{M-x sgml-load-dtd}.
711 @defopt sgml-default-dtd-file
712 This is the default file name for saved DTD. This is set by
713 @code{sgml-mode} to the buffer file name less extension plus the
714 extension @code{.ced}, if that file exists. Can be changed in the Local
715 variables section of the file.
718 @c true with system-path
719 @c either or by creating a saved DTD and setting
720 @c @code{sgml-default-dtd-file} to that file. If
721 @c @code{sgml-default-dtd-file} contains a relative file name, the
722 @c directories in @code{sgml-system-path} will be searched for the file.
725 @c ------------------------------------------------------------
726 @node Using a Split Document, Inserting a DOCTYPE, Precompiled DTD Subsets, Managing the DTD
727 @comment node-name, next, previous, up
728 @section Using a Split Document
730 @c *** why not defopt??
732 You can have the @samp{DOCTYPE} declaration in another file by setting
733 @code{sgml-doctype} to the other file.
735 @defopt sgml-parent-document
736 Used when the current file is part of a bigger document.
738 The variable describes how the current file's content fit into the element
739 hierarchy. The variable should have the form
742 (@var{parent-file} @var{context-element}* @var{top-element} (@var{has-seen-element}*)?)
747 is a string, the name of the file containing the
750 @item context-element
751 is a string, that is the name of an element type.
752 It can occur 0 or more times and is used to set up
753 exceptions and short reference map. Good candidates
754 for these elements are the elements open when the
755 entity pointing to the current file is used.
758 is a string that is the name of the element type
759 of the top level element in the current file. The file
760 should contain one instance of this element, unless
761 the last (lisp) element of sgml-parent-document is a
762 list. If it is a list, the top level of the file
763 should follow the content model of top-element.
765 @item has-seen-element
766 is a string that is the name of an element type. This
767 element is satisfied in the content model of top-element.
772 @c ------------------------------------------------------------
773 @node Inserting a DOCTYPE, Information from the DTD, Using a Split Document, Managing the DTD
774 @comment node-name, next, previous, up
775 @section Inserting a DOCTYPE
778 @findex sgml-custom-dtd
779 *** Describe the DTD menu in general. Describe customized entries for
780 special DTDs. Mention @kbd{C-c C-u C-d} for inserting a DOCTYPE from
783 If you change the doctype you must execute @code{sgml-parse-prolog},
784 changes in the doctype are not automatically recognized.
786 @defopt sgml-custom-dtd
787 Menu entries to be added to the DTD menu. The value should be a list of
788 entries to be added to the DTD menu.
790 Every entry should be a list. The first element of the entry is a string
791 used as the menu entry. The second element is a string containing a
792 doctype declaration (this can be nil if no doctype). The rest of the
793 list should be a list of variables and values. For backward
794 compatibility a single string instead of a variable is assigned to
795 @code{sgml-default-dtd-file}. All variables are made buffer local and
796 are also added to the buffers local variables list.
798 When an entry is selected from the DTD menu, the doctype declaration will
799 be inserted, the variables will be set to the values in the entry and a
800 local variables list will be created in the buffer.
806 sgml-default-dtd-file "~/sgml/html.ced"
807 sgml-omittag nil sgml-shorttag nil)
808 ("HTML+" "<!doctype htmlplus system 'htmlplus.dtd'>"
809 "~/sgml/htmlplus.ced"
810 sgml-omittag t sgml-shorttag nil)
811 ("DOCBOOK" "<!doctype docbook system 'docbook.dtd'>"
813 sgml-omittag nil sgml-shorttag t)))
818 @c ------------------------------------------------------------
819 @node Information from the DTD, Customizing DTD, Inserting a DOCTYPE, Managing the DTD
820 @comment node-name, next, previous, up
821 @section Information from the DTD
825 PSGML can list various information about the current DTD.
826 The following commands can be used via @kbd{M-x} and
827 can also be found in the DTD menu.
830 @findex sgml-describe-dtd
831 @item sgml-describe-dtd
832 Display information about the current DTD.
834 @findex sgml-describe-element-type
835 @item sgml-describe-element-type
836 Describe the properties of an element type as declared in the current DTD.
839 @findex sgml-describe-entity
840 @item sgml-describe-entity
841 Describe the properties of an entity as declared in the current DTD.
843 @findex sgml-list-elements
844 @item sgml-list-elements
845 Will list all elements and the attributes declared for the element.
847 @findex sgml-list-attributes
848 @item sgml-list-attributes
849 Will list all attributes declared and the elements that use them.
851 @findex sgml-list-terminals
852 @item sgml-list-terminals
853 Will list all elements that can contain data.
855 @findex sgml-list-occur-in-elements
856 @item sgml-list-occur-in-elements
857 Will list all element types and where it can occur.
859 @findex sgml-list-content-elements
860 @item sgml-list-content-elements
861 Will list all element types and the element types that can occur
866 @c ---------------------------------------------------------------------------
867 @node Customizing DTD, , Information from the DTD, Managing the DTD
868 @comment node-name, next, previous, up
869 @section Customizing DTD
871 PSGML can be customized by process instructions starting with ``PSGML''
872 in the DTD. Generally this associates some information with element
873 types. E.g., if @code{sgml-fill-element} should skip the element type
874 or if the content should be displayed with a special font.
876 The general syntax is
878 @samp{<?PSGML ELEMENT} @var{gi} (@var{prop} = @var{value})* @samp{>}
881 Note: in XML the ending delimiter is @samp{?>}, in SGML mode a
882 trailing @samp{?} will be ignored if preceded by a space.
884 Where @var{gi} is the element type, @var{prop} is a propery
885 described below, and @var{value} is the value for the property. The
886 first part from @samp{PSGML} to @var{gi} is read with current setting
887 for @samp{NAMECASE GENERAL}, i.e., case insensitive for normal SGML
888 but case sensitive in XML mode. The @var{prop} and @var{value} is read
889 using Emacs Lisp conventions, i.e. case sensitive and @var{value} is a
890 lisp expression (not evaluated).
895 <?PSGML ELEMENT PRE nofill=t face=fixed-pitch>
902 Set to either @code{t} or @code{nil}. If @code{t} the elements of this
903 type will be ignored when filling with @code{sgml-fill-element}.
904 Note that Emacs normal filling functions will not honor this.
907 Set to the name of an Emacs face. Should be a face that exists in
908 Emacs. E.g. @code{bold}, @code{italic}, @code{fixed-pitch}. The
909 content of elements of this type will be displayed in that face.
912 Set to a list of attribute names. E.g., @code{attnames=("ID" "CLASS"
913 "ONCLICK")}. This controls the attributes included when using the
914 @code{sgml-edit-attributes} (@kbd{C-c C-a}) command. Only the
915 attributes in the list will be included and in that order. You can
916 also end the list with a @code{*} to include all attributes, but the
917 listed attributes will be on the top. E.g.,
918 @code{attnames=("ID" "CLASS" "ONCLICK" *)}.
919 Note: that the attribute names need to be written with the correct
920 case and in string quotes.
923 Control if element is included in @code{sgml-show-structure} (@kbd{C-c
924 C-s}). If set to @code{t}, the element is included and if set to
925 @code{ignore} it will not be included. @xref{Information, Showing information}.
928 Should be a string. The string will be displayed by
929 @code{sgml-show-current-element-type} (@kbd{C-c C-t}).
934 @c ---------------------------------------------------------------------------
935 @node Edit, Display, Managing the DTD, Top
936 @comment node-name, next, previous, up
937 @chapter Commands for editing
940 * Insert:: Inserting Markup
941 * Complete:: Markup completion
942 * Information:: Showing information
943 * Indent:: Indentation according to structure
944 * Move:: Move in the element structure
945 * Attributes:: Editing attributes
946 * Change and delete:: Changing and deleting markup
947 * Translating characters and entities::
950 @c ------------------------------------------------------------------
951 @node Insert, Complete, Edit, Edit
952 @comment node-name, next, previous, up
953 @section Inserting Markup
955 @c erik says "inserts" ??
956 The commands that insert start-tags works only if the document has an
959 Keyboard commands for inserting:
963 @findex sgml-insert-tag
965 Will ask, for the tag to insert, in the mini-buffer with completion on the
966 tags that are valid at point (@code{sgml-insert-tag}).
968 If the option @code{sgml-balanced-tag-edit} is non-nil, inserting a
969 start-tag will also insert the corresponding end-tag. If, in addition,
970 @code{sgml-auto-insert-required-elements} is non-nil, tags for elements
971 required between the inserted tags will also be inserted.
973 The list of valid tags, computed for a position in the buffer, will
978 The end-tag for the current element, if it can be ended at the position
979 and @code{sgml-balanced-tag-edit} is nil. Furthermore it will contain
980 end-tags for enclosing elements if the necessary omissible end-tag
981 declarations have been made in the DTD.
984 The start-tags of all elements that could occur after point. If
985 @code{sgml-omittag-transparent} is nil, the above will be limited to the
986 elements that can occur within the current element.
991 @findex sgml-insert-element
992 @vindex sgml-insert-end-tag-on-new-line
994 Insert start and end-tags for an element
995 (@code{sgml-insert-element}). The name of the element is read
996 from the mini-buffer with completion on valid elements. If
997 @code{sgml-insert-end-tag-on-new-line} is non-nil or the
998 element has element content, the end-tag will be inserted on a
999 new line after the start-tag.
1001 @vindex sgml-omittag-transparent
1002 If @code{sgml-omittag-transparent} is nil, the list of valid elements
1003 will only contain the elements that can be in the content of the current
1006 @vindex sgml-auto-insert-required-elements
1007 @vindex sgml-insert-missing-element-comment
1008 Required elements in the content will be automatically inserted if the
1009 option @code{sgml-auto-insert-required-elements} is non-nil.
1010 When the content model demands an element but there is more
1011 than one to choose from, a comment can be inserted with the
1012 available choices if the option
1013 @code{sgml-insert-missing-element-comment} is non-nil.
1016 @findex sgml-add-element-to-element
1018 Inserts a new element in the current element where it is legal. Prompts
1019 for element name with completion. The completion list contains all
1020 elements that could be added to the current element somewhere, without
1021 making the content invalid. This assumes that the content is valid to
1022 begin with. Currently this list only has regular elements, not
1023 inclusions. The new element will be inserted as late as possible in the
1024 current element (unless prefix argument is given, then as early as
1028 @findex sgml-tag-region
1030 Makes the region into a new element (@code{sgml-tag-region}). Reads
1031 element name from mini-buffer with completion as for @kbd{C-c C-e}.
1034 @findex sgml-insert-end-tag
1036 Inserts an end-tag for the current element (@code{sgml-insert-end-tag}).
1038 @c note that this keybinding doesn't follow the conventions for
1039 @c major-modes. Perhaps warn that this binding may change in the next
1044 @findex sgml-split-element
1046 Split the current element at point. If repeated, the containing element
1047 will be split before the beginning of then current element.
1049 Typical use is to start a new paragraph element when inside a paragraph.
1052 @findex sgml-insert-attribute
1054 Read attribute name and value from mini-buffer and insert attribute
1055 specification (@code{sgml-insert-attribute}). If point is immediately
1056 after a start-tag, this command operates on that start-tag. Otherwise
1057 the command will operate on the element after point.
1059 The attribute name will be read with completion. If the attribute has a
1060 token list as declared value the attribute value will also be read with
1061 completion. The prompt for attribute value will typically look like:
1064 Value for @var{attribute} (@var{type} Default: @var{current value}):
1067 @c note that this keybinding doesn't follow the conventions for
1068 @c major-modes. Perhaps warn that this binding may change in the next
1072 @findex sgml-custom-markup
1074 Give keyboard access to the customized part of the Markup menu.
1075 Emacs will prompt for the markup to insert using the menu line as
1076 selector. (See @var{sgml-custom-markup} below.)
1084 Selecting from this menu will insert markup. The menu contains
1085 sub menus with tags and with entities, some other markup and a user
1090 @item Insert element
1091 Pops up a menu of valid elements and insert start and end-tags for
1092 the selected element. Selections from the menu works like the @kbd{C-c
1095 @item Insert start-tag
1096 Pops up a menu of valid start-tags and insert the selected tag. The
1097 menu has the same start-tags as the completion list for @kbd{C-c <}.
1099 @item Insert end-tag
1100 Pops up a menu of valid end-tags and insert the selected tag.
1103 Pops up a menu of valid elements and tag the region with the
1104 selection. Selections from the menu works like the @kbd{C-c C-r}
1108 Menu of all general entities defined in the DTD.
1110 @item Add Element to Element
1111 Pops up a menu of all elements valid somewhere in the current element.
1112 The menu contains all elements that could be added to the current
1113 element somewhere, without making the content invalid. The new element
1114 will be inserted as late as possible in the current element.
1116 @item Insert attribute
1117 Pops up a menu with all the attributes of an element. The element is
1118 either the one which start-tag is immediately before point or the
1119 element after point. Selecting from this menu edits the attribute
1120 specification list for the element.
1122 The menu has a sub menu for every attribute which declared value is a
1123 token list. The rest of the attributes are collected in one sub menu.
1124 For the token list attributes, selecting a value will insert that
1125 attribute-value pair. Selecting some other attribute reads the
1126 attribute-value from the mini-buffer and inserts the attribute value
1130 @kindex S-@key{mouse-3}
1131 A menu is also available directly with a mouse button click in the
1132 buffer. In GNU Emacs it is the first mouse button combined with shift
1133 (@kbd{S-@key{mouse-3}}). In XEmacs it is bound to the third mouse
1134 button. The mouse button click will pop-up a menu of valid tags or a
1135 menu of attributes if the point is in a start-tag. The attributes menu
1136 works as the ``Insert attribute'' menu from the menu-bar. The tags list
1137 is the list of valid tags described above for command @kbd{C-c <}.
1138 Selection from the tags menu works like the @kbd{C-c <} command, with
1139 the following exception:
1141 You can tag a region, with start and end-tag. There are two ways to
1142 indicate the region to mark:
1146 Use the normal mouse commands to mark region.
1148 For this to work you must either use @dfn{transient mark mode}
1149 (@pxref{Transient Mark, , Transient Mark Mode, emacs, The Emacs
1150 Editor}) or set the option @code{sgml-tag-region-if-active} to non-nil
1151 (don't set this unless you are sure that you want it).
1154 Alternatively make a secondary selection, this is done by holding down
1155 the meta key and using the mouse buttons.
1156 @xref{Secondary selection, , , emacs, The Emacs Editor}.
1157 Some window managers intercept these events, which makes it hard use the
1158 secondary selection in Emacs.
1161 @defopt sgml-balanced-tag-edit
1162 If non-nil, inserting a start-tag using the context menu will also
1163 insert the corresponding end-tag.
1166 @defopt sgml-auto-insert-required-elements
1167 If non-nil, automatically inserts required elements in the content
1168 of an inserted element.
1171 @defopt sgml-omittag-transparent
1172 If non-nil, will show legal tags inside elements with omissible start-tags
1173 and legal tags beyond omissible end-tags.
1176 @defopt sgml-tag-region-if-active
1177 If non-nil, the @samp{Insert tags} menu will tag a region if the region
1178 is considered active by emacs. If nil, region must be active and
1179 @code{transient-mark-mode} must be on for the region to be tagged.
1182 @defopt sgml-custom-markup
1183 Menu entries to be added to the Markup menu. The value should be a list
1184 of lists of two strings. The first string is the menu line and the
1185 second string is the text inserted when the menu item is selected. The
1186 second string can contain a @samp{\r} where the cursor should be left.
1187 Also, if a selection is made according to the same rules as for the
1188 @kbd{S-mouse-1} menu, the selection is replaced with the second string
1189 and @samp{\r} is replaced with the selection.
1194 (("Version1" "<![%Version1[\r]]>")
1195 ("New page" "<?NewPage>"))
1200 @defopt sgml-insert-missing-element-comment
1201 If non-nil, and sgml-auto-insert-required-elements also true,
1202 @code{sgml-insert-element} will insert a comment if there is an
1203 element required but there is more than one to choose from.
1206 @defopt sgml-insert-end-tag-on-new-line
1207 If non-nil, @code{sgml-insert-element} will put the end-tag on
1208 a new line after the start-tag. Useful on slow terminals if you
1209 find the end-tag after the cursor irritating.
1213 @c -------------------------------------------------------------------------
1214 @node Complete, Information, Insert, Edit
1215 @comment node-name, next, previous, up
1216 @section Markup completion
1219 @findex sgml-complete
1220 If you are typing in markup directly, @kbd{M-TAB} will help you by
1221 completing a tag name, an entity name or a markup declaration name. If
1222 you type @kbd{M-TAB} after a plain word, @code{ispell-complete-word}
1223 will be invoked instead.
1225 If you have typed (@point{} marks the position of point)
1231 @noindent and type @kbd{M-TAB} (assuming you use the @file{ISOLat1}
1232 entity set) you get:
1239 @c ---------------------------------------------------------------------------
1240 @node Information, Indent, Complete, Edit
1241 @comment node-name, next, previous, up
1242 @section Showing information
1244 Commands for showing information obtained by parsing the buffer.
1248 @findex sgml-show-context
1250 Shows in the message area: context at point, if in a tag or in mixed
1251 content and the open elements (@code{sgml-show-context}). The form of
1252 the string is controled by the user option
1253 @code{sgml-show-context-function}.
1256 @findex sgml-what-element
1258 Shows what element the character after point (under the cursor) belongs
1259 to; also shows context of element (@code{sgml-what-element}).
1262 @findex sgml-show-current-element-type
1264 Show information about the current element type and the valid element
1265 following the point.
1268 @findex sgml-show-structure
1270 Show the major element structure in a separate buffer (@samp{*Document
1271 structure*}). That buffer can be used to navigate the document, like
1272 an Occur buffer (@pxref{Other Repeating Search, , Other
1273 Search-and-Loop Commands, emacs, The Emacs Editor}). The structure
1274 shows container elements and the text of the first child element (if
1275 it is not a container). This works best for document types which uses
1276 containers and title structure (e.g. @samp{<div> <title>Heder</title>
1277 ..</div>}). PSGML uses a heuristic rule to identify container
1278 elements: it should have element content and be non empty. You can
1279 configure exceptions from this rule using a process instruction in the
1280 DTD (@pxref{Customizing DTD}).
1282 To include an element type @var{el1} that would otherwise be excluded:
1284 <?PSGML element @var{el1} structure=t?>
1287 To exclude an element type @var{el2} that would otherwise be included:
1289 <?PSGML element @var{el2} structure=ignore?>
1294 @findex sgml-list-valid-tags
1295 List contextually valid tags (@code{sgml-list-valid-tags}). Displays
1296 information about current element, all valid end-tags, valid start-tags
1297 in current element, and start-tags valid at this point but in other
1298 elements together with the tags omitted.
1301 *** This is no longer working
1303 You can make the mode-line display the name of the current open element
1304 by setting the @code{sgml-live-element-indicator} variable. Setting
1305 this will make all commands slower due to the work needed to keep the
1306 mode-line up to date.
1308 @defopt sgml-live-element-indicator
1309 If non-nil, indicate current element in mode line.
1311 NOTE: Setting this implies that every command can cause a parse.
1316 @defopt sgml-show-context-function
1317 The value shold be a function that generates a string from an element
1318 and the current markup type (if any). There are two ready made
1319 functions for this. The function @code{sgml-show-context-standard},
1320 the default, generates a string like @samp{#PCDATA in para in chapter
1321 in book}. The function @code{sgml-show-context-backslash} generates a
1322 string like @samp{book\chapter\para}.
1326 @c --------------------------------------------------------------------------
1327 @node Indent, Move, Information, Edit
1328 @comment node-name, next, previous, up
1329 @section Indentation according to structure
1333 @findex sgml-indent-or-tab
1334 @findex newline-and-indent
1335 You can indent a line according to the depth of element nesting at the
1336 beginning of the line. To indent the current line use @kbd{@key{TAB}}.
1337 You can also use @kbd{@key{LFD}} (@code{newline-and-indent}) to start a
1338 new line with correct indentation.
1340 @defopt sgml-indent-step
1341 How much to increment indent for every element level. If nil, no
1344 If this is nil, @kbd{@key{TAB}} will insert a tab instead of indenting.
1347 @defopt sgml-indent-data
1348 If non-nil, indent in data/mixed context also.
1353 @c ---------------------------------------------------------------------------
1354 @node Move, Attributes, Indent, Edit
1355 @comment node-name, next, previous, up
1356 @section Move in the element structure
1358 These commands move in the element structure. The commands uses
1359 knowledge of SGML syntax, and if available the specific DTD.
1363 @findex sgml-beginning-of-element
1365 Move to the (content) beginning of the current element
1366 (@code{sgml-beginning-of-element}).
1369 @findex sgml-end-of-element
1371 Move to the (content) end of the current element (@code{sgml-end-of-element}).
1374 @findex sgml-forward-element
1376 Move forward by element (@code{sgml-forward-element}).
1379 @findex sgml-backward-element
1381 Move backward by element (@code{sgml-backward-element}).
1384 @findex sgml-backward-up-element
1386 Move up to before current element (@code{sgml-backward-up-element}).
1389 @findex sgml-up-element
1391 Move up to after current element (@code{sgml-up-element}).
1394 @findex sgml-down-element
1396 Move down to the (content) beginning of the next element
1397 (@code{sgml-down-element}).
1400 @findex sgml-next-data-field
1402 Move to the next place where data is allowed (@code{sgml-next-data-field}).
1405 You can also move to the next place where there is some structural error
1406 with @kbd{C-c C-o} (@pxref{Validate}).
1409 @c ---------------------------------------------------------------------------
1410 @node Attributes, Change and delete, Move, Edit
1411 @comment node-name, next, previous, up
1412 @section Editing attributes
1414 @findex sgml-edit-attributes
1416 If you want to change the attributes of a start-tag you can simply edit
1417 them directly in the buffer. Or you can place the cursor at or after
1418 the start-tag and use the @code{sgml-edit-attributes} command, available
1419 from the @samp{SGML}-menu or on @kbd{C-c C-a}. This will create a new
1420 Emacs window with all possible attributes listed in the form
1423 @var{attribute name} = @var{current value}.
1426 The @var{current value} may be shown as @samp{#DEFAULT} if the attribute
1427 has not been given a value in the start-tag. The list also contains the
1428 attributes declaration as a comment. Note also that the @var{current
1429 value} is show without eventual quotes.
1433 It is now possible to edit the attribute values. You can move to the
1434 next attribute with @kbd{@key{TAB}}. If you want to let an attribute
1435 have its default value use @kbd{C-c C-d}, this will insert a
1436 @samp{#DEFAULT} in the value field.
1438 If Emacs is running in an X window, the @samp{#DEFAULT} will be
1439 underlined to distinguish it from normal values.
1442 Finish the editing with @kbd{C-c C-c}; this will replace the attribute
1443 values in the main buffer with those edited. Note that values will be
1446 If you want to abort the editing, you can remove the window with
1447 @kbd{C-x 0} or if you want it neat, kill the buffer and remove the
1450 Some other keys are:
1453 @findex sgml-edit-attrib-field-start
1455 Go to the beginning of the value field
1456 (@code{sgml-edit-attrib-field-start}).
1459 @findex sgml-edit-attrib-field-end
1461 Go to the end of the value field
1462 (@code{sgml-edit-attrib-field-end}).
1465 @findex sgml-edit-attrib-clear
1467 Clear the value field
1468 (@code{sgml-edit-attrib-clear}).
1471 @findex sgml-edit-attrib-default
1473 Set the value field to @samp{#DEFAULT}
1474 (@code{sgml-edit-attrib-default}). This is a special value that will
1475 make the attribute be implied.
1479 @c --------------------------------------------------------------------------
1480 @node Change and delete, Translating characters and entities, Attributes, Edit
1481 @comment node-name, next, previous, up
1482 @section Changing and deleting markup
1486 @findex sgml-change-element-name
1488 Change the name of the current element (@code{sgml-change-element-name}).
1489 Tries to translate attribute specifications. An attribute will be
1490 translated to an attribute with the same name. If the new element has
1491 no attribute with the same name, the attribute will be ignored. If
1492 there is an attribute with the same name but different declared content,
1495 ID attributes are handled specially, an attribute with declared value ID
1496 will always be translated to the attribute with declared value ID.
1499 @findex sgml-kill-markup
1501 Kill next tag, markup declaration or process instruction
1502 (@code{sgml-kill-markup}).
1505 @findex sgml-kill-element
1507 Kill the element following the cursor (@code{sgml-kill-element}).
1510 @findex sgml-untag-element
1512 Remove tags from current element (@code{sgml-untag-element}).
1515 @findex sgml-make-character-reference
1517 Convert character after point to a character reference
1518 (@code{sgml-make-character-reference}). If called with a numeric
1519 argument, convert a character reference back to a normal character.
1522 @findex sgml-fill-element
1524 Fills an element as a paragraph (@code{sgml-fill-element}). This is a
1525 substitute for the normal @code{fill-paragraph}. The command uses
1526 heuristics to decide what should be a paragraph.
1530 If point is in an element content, recursively fill the sub-elements.
1532 Find the biggest element with mixed content containing point.
1534 If the above element is mixed but contains elements with pure element
1535 content then fill what is between the pure elements as paragraphs and
1536 fill the pure elements recursively.
1539 @findex sgml-expand-all-shortrefs
1540 @item M-x sgml-expand-all-shortrefs
1541 Short references to text entities are expanded to the replacement text
1542 of the entity other short references are expanded into general entity
1543 references. If argument, @var{to-entity}, is non-@code{nil}, or if
1544 called interactive with numeric prefix argument, all short references
1545 are replaced by generally entity references.
1547 @findex sgml-normalize
1548 @item M-x sgml-normalize
1549 Normalize the document in the buffer. This will
1553 expand short references,
1555 insert missing tags,
1557 replace minimized tags with full tags,
1559 fix attribute specification lists according to options set.
1562 There is one argument, @var{to-entity}, with the same meaning as for
1563 @code{sgml-expand-all-shortrefs}.
1565 There is one option for the normalize command. With its default value,
1566 normalize may actually change the data content of some elements. But
1567 only by removing some white-space from the end of elements with omitted
1571 @defopt sgml-normalize-trims
1572 If non-nil, @code{sgml-normalize} will trim off white space from end of
1573 element when adding end-tag.
1579 @c --------------------------------------------------------------------------
1580 @node Translating characters and entities, , Change and delete, Edit
1581 @comment node-name, next, previous, up
1582 @section Translating between characters and entity references
1586 Set the variable @code{sgml-display-char-list-filename} to a file that
1587 contains mappings between all characters present in the presentation
1588 character set, and their "standard replacement text" names, e.g. "å"
1589 -> "[aring ]", e.t.c.
1591 The default value for this variable is `iso88591.map'.
1593 Then use the functions (also in the Modify menu)
1596 @findex sgml-charent-to-display-char
1597 @item sgml-charent-to-display-char
1598 @findex sgml-display-char-to-charent
1599 @item sgml-display-char-to-charent
1602 to translate between entities and characters.
1604 @c ---------------------------------------------------------------------------
1605 @node Display, Miscellaneous options, Edit, Top
1606 @comment node-name, next, previous, up
1607 @chapter Appearance of text in the buffer
1610 * Fold:: Folding editing
1612 * Highlight:: Highlighting markup
1615 @c ---------------------------------------------------------------------------
1616 @node Fold, Hiding markup, Display, Display
1617 @comment node-name, next, previous, up
1618 @section Folding editing
1620 With these commands you can make parts of the text temporarily invisible
1621 to make it easier to see the overall structure of your text.
1623 When folding a region all the lines but the first will be invisible.
1624 The first line of the region will still be visible with an ellipsis at
1627 @xref{Outline Mode, , , emacs, The Emacs Editor}.
1631 @findex sgml-fold-region
1633 The region between point and mark will be folded (@code{sgml-fold-region}).
1636 @findex sgml-fold-element
1638 The region between the start and end of the current element will be
1639 folded (@code{sgml-fold-element}).
1641 This command can also fold the SGML declaration or the DOCTYPE
1645 @findex sgml-fold-subelement
1647 Fold all the sub elements of the current element
1648 (@code{sgml-fold-subelement}).
1652 @findex sgml-unfold-line
1655 Unfold the current line, assuming it is the first line of a folded
1656 region (@code{sgml-unfold-line}).
1659 @findex sgml-unfold-element
1661 Make all lines in current element visible (@code{sgml-unfold-element}).
1664 @findex sgml-unfold-all
1666 Make all lines in current buffer visible (@code{sgml-unfold-all}).
1669 @findex sgml-expand-element
1671 Unfold current element and then fold the subelements
1672 (@code{sgml-expand-element}). If the current element is folded this
1673 expands what is visible.
1677 @c ---------------------------------------------------------------------------
1678 @node Hiding markup, Highlight, Fold, Display
1679 @comment node-name, next, previous, up
1680 @section Hiding markup
1682 *** Describe hide-tags
1685 @c ---------------------------------------------------------------------------
1686 @node Highlight, , Hiding markup, Display
1687 @comment node-name, next, previous, up
1688 @section Highlighting markup
1691 PSGML can highlight the markup giving the markup a different @dfn{face}
1692 (@pxref{Faces, , Using Multiple Typefaces, emacs, The Emacs Editor}).
1693 The highlighting will only be done if the variable @code{sgml-set-face}
1694 is non-@code{nil}. The default settings make tags bold and comments
1695 italic, but this can be modified with the variable
1696 @code{sgml-markup-faces}. When highlighting is on PSGML will parse after
1697 every command until the whole buffer has been parsed or user event
1700 @findex sgml-clear-faces
1701 To remove the highlighting type @kbd{M-x sgml-clear-faces}.
1703 @defopt sgml-set-face
1704 If non-nil, psgml will set the face of parsed markup.
1707 @defopt sgml-markup-faces
1708 A list of markup to face mappings.
1709 Each element looks like @code{(@var{markup-type} . @var{face})}.
1710 Possible values for @var{markup-type} is:
1720 ignored marked section
1722 marked section end, if not ignored
1724 marked section start, if not ignored
1726 processing instruction
1740 @c ------------------------------------------------------------------
1741 @node Miscellaneous options, Bugs, Display, Top
1742 @comment node-name, next, previous, up
1743 @chapter Miscellaneous options
1745 *** describe sgml-save-options
1747 @defopt sgml-ignore-undefined-elements
1748 Start-tags for undefined elements will either be ignored, if
1749 @code{sgml-ignore-undefined-elements} is @code{t}, or assumed to be
1750 acceptable in the current element and defined with @code{O O ANY}
1753 @defopt sgml-range-indicator-max-length
1754 Maximum number of characters used from the first and last entry
1755 of a sub-menu to indicate the range of that menu.
1757 @vindex sgml-max-menu-size
1758 This is used for long menus of elements, tags or entities that are split
1759 into @code{sgml-max-menu-size} big sub-menus.
1765 @c ------------------------------------------------------------------
1766 @node Bugs, Index, Miscellaneous options, Top
1767 @comment node-name, next, previous, up
1771 If you encounter something that you think is a bug, please report
1772 it. Try to include a clear description of the undesired behaviour.
1773 A test case that exhibits the bug, would also be useful.
1775 You can report a bug with the command @kbd{M-x sgml-submit-bug-report}.
1777 When PSGML needs contextual information it parses the document up to
1778 the point. During the parsing, it builds a parse tree. The parse
1779 tree is used to initialize the next parse, to avoid having to parse
1780 things already parsed. Changes to the buffer is supposed to prune
1781 the tree of all outdated information. But if you get strange
1782 complaints from the parser, try and back up a bit and use @kbd{C-c
1783 C-o} (@code{sgml-next-trouble-spot}).
1787 @c ------------------------------------------------------------------
1788 @node Index, , Bugs, Top
1789 @comment node-name, next, previous, up