1 \input texinfo @c -*-texinfo-*-
3 @documentencoding ISO-8859-1
5 @setfilename ../info/psgml.info
6 @c @setfilename psgml.info
8 @c @setchapternewpage odd
13 @c $Id: psgml.texi,v 1.8 2005/03/02 19:44:20 lenst Exp $
18 * PSGML: (psgml). PSGML, a major mode for SGML documents.
24 Documentation for PSGML, a major mode for SGML.
26 Copyright 1994, 1996, 1998 Lennart Staflin
28 Permission is granted to make and distribute verbatim
29 copies of this manual provided the copyright notice and
30 this permission notice are preserved on all copies.
33 Permission is granted to process this file through TeX
34 and print the results, provided the printed document
35 carries a copying permission notice identical to this
36 one except for the removal of this paragraph (this
37 paragraph not being relevant to the printed manual).
40 Permission is granted to copy and distribute modified
41 versions of this manual under the conditions for
42 verbatim copying, and provided that the entire
43 resulting derived work is distributed under the terms
44 of a permission notice identical to this one.
46 Permission is granted to copy and distribute
47 translations of this manual into another language,
48 under the above conditions for modified versions,
49 except that this permission notice may be stated in a
50 translation approved by the Free Software Foundation.
56 @title Editing SGML with Emacs and PSGML
57 @author Lennart Staflin
59 @c The following two commands
60 @c start the copyright page.
62 @vskip 0pt plus 1filll
63 Copyright @copyright{} 1994, 1996, 1998 Lennart Staflin
67 Permission is granted to make and distribute verbatim
68 copies of this manual provided the copyright notice and
69 this permission notice are preserved on all copies.
72 Permission is granted to process this file through TeX
73 and print the results, provided the printed document
74 carries a copying permission notice identical to this
75 one except for the removal of this paragraph (this
76 paragraph not being relevant to the printed manual).
79 Permission is granted to copy and distribute modified
80 versions of this manual under the conditions for
81 verbatim copying, and provided that the entire
82 resulting derived work is distributed under the terms
83 of a permission notice identical to this one.
85 Permission is granted to copy and distribute
86 translations of this manual into another language,
87 under the above conditions for modified versions,
88 except that this permission notice may be stated in a
89 translation approved by the Free Software Foundation.
92 @node Top, Introduction, (dir), (dir)
93 @comment node-name, next, previous, up
97 PSGML is a major mode for editing SGML documents. This is the DRAFT
98 documentation for PSGML version 1.4.
102 * Introduction:: Introduction
103 * Install:: How to install PSGML
104 * Invoke:: How to invoke PSGML
105 * Entity manager:: The Entity Manager
106 * Validate:: Running an external SGML parser
107 * SGML declaration:: Using an SGML declaration
108 * Managing the DTD:: Specifying what DTD to use
109 * Edit:: Commands for editing
110 * Display:: Appearance of text in the buffer
111 * Miscellaneous options::
112 * Bugs:: Reporting bugs
117 @c *** section about error recovery ??
120 @c ------------------------------------------------------------------
122 @node Introduction, Install, Top, Top
123 @comment node-name, next, previous, up
124 @chapter Introduction
129 @cindex SGML Declaration
131 PSGML is a major mode for editing SGML and XML documents. It works with
132 GNU Emacs 19.34, 20.3 and later or with XEmacs 19.9 and later. PSGML
133 contains a simple SGML parser and can work with any DTD. Functions
134 provided includes menus and commands for inserting tags with only the
135 contextually valid tags, identification of structural errors, editing of
136 attribute values in a separate window with information about types and
137 defaults, and structure based editing.
139 SGML, a language for encoding the structure of a document, is an ISO
140 standard: ISO 8879:1986 ``Information processing -- Text and office
141 systems -- Standard Generalized Markup Language (SGML)''.
143 A good introduction to SGML is @cite{A Gentle Introduction to SGML}
144 produced by Text Encoding Initiative (this is really chapter 2 of TEI
145 P3). This can be found on
148 @file{ftp://ftp.ifi.uio.no/pub/SGML/TEI/P3SG.DOC}.
151 A SGML document has three major parts, in order:
155 SGML Declaration (@samp{<!SGML "ISO 8879:1986" @dots{} >})
157 Document Type Declaration (@samp{<!DOCTYPE @var{name} @dots{} >})
159 Document Element (@samp{<@var{name}> @dots{} </@var{name}>})
162 The SGML declaration contains general information about character sets,
163 concrete syntax, and SGML features used. PSGML does not use the SGML
164 Declaration, it can be left out, and if included is ignored. Many SGML
165 systems allow the SGML declaration to be defaulted. PSGML always use
166 the Concrete Reference Syntax but without limitations on
167 lengths. Features used has to be indicated with variables (@pxref{SGML
170 The document type declaration specifies the valid elements and entities
171 and how they can be nested. A document type is usually needed, but can
172 reside in another file (@pxref{Managing the DTD}).
174 The system declaration for PSGML:
176 SYSTEM "ISO 8879:1986"
178 BASESET "ISO 646-1983//CHARSET
179 International Reference Version (IRV)//ESC 2/5 4/0"
181 CAPACITY PUBLIC "ISO 8879:1986//CAPACITY Reference//EN"
183 MINIMIZE DATATAG NO OMITTAG YES RANK NO SHORTTAG YES
184 LINK SIMPLE NO IMPLICIT NO EXPLICIT NO
185 OTHER CONCUR NO SUBDOC YES 1 FORMAL YES
187 SYNTAX PUBLIC "ISO 8879:1986//SYNTAX Reference//EN"
188 @c SYNTAX PUBLIC "ISO 8879:1986//SYNTAX Core//EN"
190 GENERAL NO MODEL NO EXCLUDE NO CAPACITY NO
191 NONSGML NO SGML NO FORMAL NO
192 SDIF PACK NO UNPACK NO
196 @c -------------------------------------------------------------------------
197 @node Install, Invoke, Introduction, Top
198 @comment node-name, next, previous, up
199 @chapter Installing PSGML
201 As of @cite{XEmacs 21.0} (with @cite{EFS} installed) you can get the
202 latest @cite{psgml} package by evaluating the follwing two lines within
206 (require 'package-get)
207 (package-get 'psgml nil)
210 To install PSGML in XEmacs versions prior to 21.0 you first need to
211 uncompress and unpack the source archive. This is done with the
212 @code{gunzip} and @code{tar} commands.
215 gunzip psgml-1.3.1.tar.gz; tar xf psgml-1.3.1.tar
218 This should create a subdirectory to the current directory with the
219 source code. This directory contains a @code{configure} command (see the
220 file INSTALL for more information about configure). You can use the
221 @code{configure} command to configure the package or you can load the
222 file @file{psgml-maint} and execute the @code{psgml-compile-files}
225 Place the @file{*.el} and the @file{*.elc} files in a directory where
226 Emacs can find it (i.e. one of the directories in the @code{load-path}
227 variable, you can add a directory to this variable in your
230 If you use the @code{configure} approach, compile psgml with @code{make}
231 and the you can run @code{make install} to install it in the system
232 library @file{site-lisp}. The location of @file{site-lisp} is figured
233 out by @code{configure}, but you can change it in the @file{Makefile}.
235 Put the following line in your .emacs:
238 (autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t)
239 (autoload 'xml-mode "psgml" "Major mode to edit XML files." t)
242 You may also want to set up search paths for external entities,
243 @xref{Entity manager}.
245 The @file{psgml.info} is the documentation for PSGML in the info format.
246 You can read this with the Emacs command @kbd{C-u C-h i}. You can also
247 install the file in your systems info directory and edit the
248 @file{dir} file to include @file{psgml.info} in the menu.
250 The info file @file{psgml.info} is created from the texinfo file
251 @file{psgml.texi}. The texinfo file can also be used to create a hard
252 copy of the documentation. To do this you need the @TeX{} program and a
253 copy of @file{texinfo.tex}.
258 @c --------------------------------------------------------------------------
259 @node Invoke, Entity manager, Install, Top
260 @comment node-name, next, previous, up
261 @chapter How to invoke PSGML
267 PSGML defines major modes called @code{sgml-mode} and @code{xml-mode}.
268 Files with extensions @file{.sgml}, @file{.sgm} or @file{.dtd} will
269 automatically be edited in SGML mode. To edit some other file in SGML
270 mode, type @kbd{M-x sgml-mode @key{RET}} after finding the file.
271 To edit XML files, type @kbd{M-x xml-mode @key{RET}}.
273 If you can modify the file you can add a @dfn{Local Variables} list
274 (@pxref{file variables, , Local Variables in Files, emacs, The Emacs
275 Editor}) to the end of the file. This can make Emacs
276 automatically set sgml mode and user options when the file is loaded.
277 The simplest Local Variables list would look like:
287 You can also put a line at the top of the file to tell emacs to use sgml
291 <!-- -*- sgml -*- -->
294 For XML replace @samp{sgml} with @samp{xml} in the above examples.
295 But remember that you can't have a comment before the @emph{SGML
296 declaration} or the @emph{XML declaration}.
299 @c -------------------------------------------------------------------------
300 @node Entity manager, Validate, Invoke, Top
301 @comment node-name, next, previous, up
302 @chapter The Entity Manager
303 @cindex public identifier
304 @cindex system identifier
305 @cindex external identifier
306 @cindex entity catalog
308 @c *** sgml-sysid-resolve-functions
310 SGML can refer to an external file (really entity) with an
311 @emph{external identifier}, this is a @emph{public identifier} or a
312 @emph{system identifier}, or both.
314 A typical public identifier looks like
317 PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN"
321 where ``ISO 8879:1986'' is the owner, ``ENTITIES'' is the text class and
322 ``Added Latin 1'' is the text description (and ``EN'' is language).
324 A system identifier looks like
327 SYSTEM "htmlplus.dtd"
330 @noindent where ``htmlplus.dtd'' is a system-specific identifier.
332 To map external identifiers to file names, PSGML first searches entity
333 catalog files and then search the list of file name templates in the
334 variable @code{sgml-public-map}.
336 The catalog format is according to SGML/Opens resolution on entity
337 management. The catalog consists of a series of entries and comments. A
338 comment is delimited by @samp{--} like in a markup declaration.
339 The entry types recognized are described in the following table.
343 @item public @var{pubid} @var{file}
344 The @var{file} will be used for the entity text of an entity
345 with the public identifier @var{pubid}.
347 @item entity @var{name} @var{file}
348 The @var{file} will be used for the entity text of an entity
349 with the name @var{name}. If the @var{name} starts with a @samp{%} the
350 rest of the name will be matched against parameter entities.
352 @item doctype @var{name} @var{file}
353 The @var{file} will be used for the entity text of an entity
354 used as external subset of a document declaration with @var{name} as
357 @item sgmldecl @var{file}
358 Used to specify a default SGML declaration. Recognized but not used by
359 PSGML other than to pass to an external validation command
360 (@code{sgml-validate-command}).
364 When PSGML is looking for the file containing an external entity, the
365 following things will be tried in order:
369 @vindex sgml-system-identifiers-are-preferred
371 Try the system identifier, as a file name, if there is a system
372 identifier and the variable @code{sgml-system-identifiers-are-preferred}
373 is non-@code{nil} and there is no elements containing @samp{%s} in
374 @code{sgml-public-map}. If the system identifier is a relative file name
375 it will be relative to the directory containing the defining entity.
378 Look thru each catalog in @code{sgml-local-catalogs} and
379 @code{sgml-catalog-files} in order. For each catalog look first for
380 entries matching the public identifier, if any. Then look for other
381 matching entries in the order they appear in the catalog.
383 Currently an entry will be ignored if it is matching but its file is
384 non-existent or unreadable. (This is under reconsideration, perhaps it
385 should signal error instead).
388 Try the system identifier, if any, as a file name.
389 If @code{sgml-system-identifiers-are-preferred} is @code{nil}
390 and there is no elements containing @samp{%s} in @code{sgml-public-map}.
393 Try the entries in @code{sgml-public-map}. Using the catalogs are
394 preferred. The @code{sgml-public-map} may disappear in a future version
395 of PSGML (not soon though).
399 The @code{sgml-public-map} variable can contain a list of file name
400 templates where @samp{%P} will be substituted with the whole public
401 identifier, owner is substituted for @samp{%O}, public text class for
402 @samp{%C}, and public text description for @samp{%D}. The text class
403 will be converted to lower case and the owner and description will be
404 transliterated according to the variable
405 @code{sgml-public-transliterations}. The templates in the list is tried
406 in order until an existing file is found. The @code{sgml-public-map} is
407 modeled after @file{sgmls} environment variable @code{SGML_PATH} and
408 psgml understand the following substitution characters: %%, %N, %P, %S,
409 %Y, %C, %L, %O, %T, and %V. The default value of
410 @code{sgml-public-map} is taken from the environment variable
413 Given the public identifier above and the file name template
414 @samp{/usr/local/lib/sgml/%o/%c/%d}, the resulting file name is
417 /usr/local/lib/sgml/ISO_8879:1986/entities/Added_Latin_1
420 Note: blanks are transliterated to @samp{_} (and also @samp{/} to
421 @samp{%}) and the text class is down cased.
425 @defopt sgml-catalog-files
426 This is a list of catalog entry files.
427 The files are in the format defined in the SGML Open Draft Technical
428 Resolution on Entity Management. The Emacs variable is initialized from
429 the environment variable @code{SGML_CATALOG_FILES} or if this variable
430 is undefined the default is
433 ("CATALOG" "/usr/local/lib/sgml/CATALOG")
437 @defopt sgml-local-catalogs
438 A list of SGML entity catalogs to be searched first when parsing the
439 buffer. This is used in addition to @code{sgml-catalog-files}, and
440 @code{sgml-public-map}. This variable is automatically local to the
444 @defopt sgml-system-identifiers-are-preferred
445 If @code{nil}, PSGML will look up external entities by searching the
446 catalogs in @code{sgml-local-catalogs} and @code{sgml-catalog-files} and
447 only if the entity is not found in the catalogs will a given system
448 identifier be used. If the variable is non-nil and a system identifier is
449 given, the system identifier will be used for the entity. If no system
450 identifier is given the catalogs will searched.
454 @defopt sgml-public-map
455 This should be a list of file name templates. This variable is
456 initialized from the environment variable @code{SGML_PATH}. This is
457 the same environment variable that @file{sgmls} uses. If the
458 environment variable is undefined the default is
461 ("%S" "/usr/local/lib/sgml/%o/%c/%d")
463 @c Mapping from public identifiers to file names.
466 @c the colon separated list in @code{SGML_PATH} is converted to a lisp list
468 @c -------------------------------------------------------------------------
469 @node Validate, SGML declaration, Entity manager, Top
470 @comment node-name, next, previous, up
471 @chapter Running an external SGML parser
474 @findex sgml-validate
475 PSGML can not validate an SGML document (see below what it can
476 and can't do). If you have a validating SGML parser, like
477 @file{sgmls}, you can run the parser on your file with the
478 command @kbd{C-c C-v} (@code{sgml-validate}).
480 Some variables control this function:
482 @defopt sgml-validate-command
483 The shell command to validate an SGML document.
485 This is a @code{format} control string that by default should contain two
486 @code{%s} conversion specifications: the first will be replaced by the
487 value of @code{sgml-declaration} (or the empty string, if nil); the
488 second will be replaced by the current buffer's file name (or the
489 empty string, if nil).
491 If @code{sgml-validate-files} is non-nil, the format string should contain
492 one @code{%s} conversion specification for each element of its result.
494 If sgml-validate-command is a list, then every element should be a
495 string. The strings will be tried in order and @samp{%}-sequences in the
496 string will be replaced according to the list below, if the string contains
497 @samp{%}-sequences with no replacement value the next string will be tried.
501 means the visited file of the current buffer
504 means the SGML declaration specified in the sgml-declaration variable
507 means the file containing the DOCTYPE declaration, if not in the buffer
510 The default value is @code{nsgmls -s %s %s}.
513 @defopt sgml-validate-files
514 If non-nil, a function of no arguments that returns a list of
515 file names. These file names will serve as the arguments to the
516 @code{sgml-validate-command} format control string instead of
520 @defopt sgml-declaration
521 The name of the SGML declaration file.
524 @defopt sgml-offer-save
525 If non-nil, @kbd{C-c C-v} (@code{sgml-validate}) will ask about
526 saving modified buffers before running the validate command.
527 The default value is @code{t}.
532 @findex sgml-next-trouble-spot
533 The built-in parser can find some markup errors. The command @kbd{C-c
534 C-o} (@code{sgml-next-trouble-spot}) is the best way to use the built-in
535 parser for this. To check the whole file go to the beginning of the
536 buffer and use @kbd{C-c C-o}.
538 Some of the markup errors not found are:
542 Errors in the SGML declaration.
544 Errors in attribute specifications.
546 Omitted start-tags for empty elements.
550 @c --------------------------------------------------------------------------
551 @node SGML declaration, Managing the DTD, Validate, Top
552 @comment node-name, next, previous, up
553 @chapter SGML Declaration
556 @cindex NAMECASE GENERAL
557 @cindex case sensitivity
559 PSGML does not understand the SGML declaration, it accepts one in the
560 file but it is ignored. If you have the SGML declaration in another
561 file you can make @file{sgmls} use it when you use the @kbd{C-c C-v}
562 (@code{sgml-validate}) command (@pxref{Validate}).
564 PSGML has some options in what features it uses and what markup it
565 creates. You have to set these options to make PSGML's behavior
566 consistent with your SGML declaration and personal preferences.
569 Set this to @code{t} if the SGML declaration has @samp{OMITTAG YES} and
570 to @code{nil} otherwise.
573 @defopt sgml-shorttag
574 Set this to @code{t} if the SGML declaration has @samp{SHORTTAG YES} and
575 to @code{nil} otherwise.
578 @defopt sgml-namecase-general
579 Set this to @code{t} if the SGML declaration has @samp{NAMECASE
580 GENERAL YES} and to @code{nil} otherwise. I.e., this controls whether
581 names, except entity names, will be case insensitive (translated to
585 @defopt sgml-always-quote-attributes
586 If non-nil, quote all attribute values inserted after finishing edit
587 attributes. If this variable is @code{nil} and @code{sgml-shorttag} is
588 non-@code{nil}, attribute values that consists of only name characters
592 @defopt sgml-minimize-attributes
593 Determines minimization of attributes inserted by edit-attributes. If
594 non-nil, omit attribute name if the attribute value is from a token
595 group. If @code{max}, omit attributes with default value. Minimization
596 will only be done if they produce legal SGML (assuming
597 @code{sgml-omittag} and @code{sgml-shorttag} are set correctly).
601 @c --------------------------------------------------------------------------
602 @node Managing the DTD, Edit, SGML declaration, Top
603 @comment node-name, next, previous, up
604 @chapter Document Type Declaration
608 @vindex sgml-default-doctype-name
609 PSGML needs to know about the DTD you are using for many of its commands.
610 If you do not have a @samp{DOCTYPE} declaration in your file,
611 PSGML will try assume that there is one of the form
614 <!DOCTYPE @var{name} SYSTEM>
617 where @var{name} is the value of @code{sgml-default-doctype-name}, if
618 the value is non-@code{nil}, else the GI of the first tag will be used.
620 @findex sgml-parse-prolog
621 @vindex sgml-auto-activate-dtd
622 PSGML will try to parse the document type declaration the first time
623 you do something that needs to parse the document or immediately if the
624 variable @code{sgml-auto-activate-dtd} is @code{t}. You can also
625 initiate the parsing of the document type declaration with the command
626 @code{sgml-parse-prolog}. Big DTDs take some time to parse.
628 When the DTD has been parsed or loaded the name of the document element
629 will be displayed in the mode line inside brackets. If there was an
630 error parsing the DTD or there is no DTD, the mode line will display
631 @samp{[ANY]} (*** this is not really correct! a DTD will be established
632 even if there are missing entities, it may even be empty).
635 * Precompiled DTD Subsets::
636 * Using a Split Document::
637 * Inserting a DOCTYPE::
638 * Information from the DTD::
643 @c ------------------------------------------------------------
644 @node Precompiled DTD Subsets, Using a Split Document, Managing the DTD, Managing the DTD
645 @comment node-name, next, previous, up
646 @section Precompiled DTD Subsets
648 If parsing the DTD takes too long time you can arrange to have PSGML
649 cache an internal complied version of the DTD. Caching can be done of
650 DTD fragments in favourable situations. It is possible to have an
651 external DTD subset cached but still have an internal DTD subset as long
652 as the internal subset does not define parameter entities that affect
653 the parsing of the external subset (*** what is the exact conditions?,
654 probably you can't use the cached external subset if the internal subset
655 defines parameter entities that are also defined in the external subset
658 @vindex sgml-ecat-files
659 @vindex sgml-local-ecat-files
660 To enable caching you have to create special catalog files, hereafter
661 called ECAT files due to (temporary) lack of imagination. These catalogs
662 have similar syntax to the entity catalogs and there are two variables
663 containing lists of catalogs to search: @code{sgml-ecat-files} and
664 @code{sgml-local-ecat-files}. The ECAT files can contain the following
668 @item file @var{dtdfile} @var{entitydef} @var{cfile}
669 The @var{dtdfile} is the name of a file containing a DTD subset that
670 should be cached in @var{cfile}. The @var{entitydef} is optional and if
671 given have the following syntax:
673 [ @var{name1} @var{literal1} @var{name2} @var{literal2} @dots{} ]
675 Using @var{entitydef} will modify the DTD subset by defining the
676 parameter entity with name @var{name1} to be @var{literal1}, @dots{}. The
677 cached version of the subset will be created with those entity
678 definitions, and when PSGML search for a matching cached subset will check
679 that the parameter entities in @var{entitydef} has been defined with
680 those values before trying to use @file{cfile}.
682 @item public @var{pubid} @var{entitydef} @var{cfile}
683 Cache the DTD subset with public identifier @var{pubid} in file
688 @defopt sgml-recompile-out-of-date-cdtd
689 If non-@code{nil}, out of date compiled DTDs will be automatically
690 recompiled. If the value is @code{ask}, PSGML will ask before
691 recompiling. A @code{nil} value will cause PSGML to silently load an out
692 of date compiled DTD. A DTD that refers to undefined external entities
693 is always out of date, thus in such case it can be useful to set this
694 variable to @code{nil}.
698 Previous versions of PSGML have had another way of speeding up DTD
699 parsing. This code remains in this version of PSGML, but is not actively
700 maintained and may disappear in the future.
702 @findex sgml-save-dtd
703 @findex sgml-load-dtd
704 @vindex sgml-default-dtd-file
705 You can save the parsed DTD in a file using the command @kbd{M-x
706 sgml-save-dtd}. Next time PSGML can load that file instead of parsing
707 the DTD. For PSGML to find the saved DTD you must either save the DTD
708 using the default name or do a @kbd{M-x sgml-save-options} after saving
709 the DTD. To directly use an already parsed and saved DTD, load the file
710 containing the saved DTD with the command @kbd{M-x sgml-load-dtd}.
712 @defopt sgml-default-dtd-file
713 This is the default file name for saved DTD. This is set by
714 @code{sgml-mode} to the buffer file name less extension plus the
715 extension @code{.ced}, if that file exists. Can be changed in the Local
716 variables section of the file.
719 @c true with system-path
720 @c either or by creating a saved DTD and setting
721 @c @code{sgml-default-dtd-file} to that file. If
722 @c @code{sgml-default-dtd-file} contains a relative file name, the
723 @c directories in @code{sgml-system-path} will be searched for the file.
726 @c ------------------------------------------------------------
727 @node Using a Split Document, Inserting a DOCTYPE, Precompiled DTD Subsets, Managing the DTD
728 @comment node-name, next, previous, up
729 @section Using a Split Document
731 @c *** why not defopt??
733 You can have the @samp{DOCTYPE} declaration in another file by setting
734 @code{sgml-doctype} to the other file.
736 @defopt sgml-parent-document
737 Used when the current file is part of a bigger document.
739 The variable describes how the current file's content fit into the element
740 hierarchy. The variable should have the form
743 (@var{parent-file} @var{context-element}* @var{top-element} (@var{has-seen-element}*)?)
748 is a string, the name of the file containing the
751 @item context-element
752 is a string, that is the name of an element type.
753 It can occur 0 or more times and is used to set up
754 exceptions and short reference map. Good candidates
755 for these elements are the elements open when the
756 entity pointing to the current file is used.
759 is a string that is the name of the element type
760 of the top level element in the current file. The file
761 should contain one instance of this element, unless
762 the last (lisp) element of sgml-parent-document is a
763 list. If it is a list, the top level of the file
764 should follow the content model of top-element.
766 @item has-seen-element
767 is a string that is the name of an element type. This
768 element is satisfied in the content model of top-element.
773 @c ------------------------------------------------------------
774 @node Inserting a DOCTYPE, Information from the DTD, Using a Split Document, Managing the DTD
775 @comment node-name, next, previous, up
776 @section Inserting a DOCTYPE
779 @findex sgml-custom-dtd
780 *** Describe the DTD menu in general. Describe customized entries for
781 special DTDs. Mention @kbd{C-c C-u C-d} for inserting a DOCTYPE from
784 If you change the doctype you must execute @code{sgml-parse-prolog},
785 changes in the doctype are not automatically recognized.
787 @defopt sgml-custom-dtd
788 Menu entries to be added to the DTD menu. The value should be a list of
789 entries to be added to the DTD menu.
791 Every entry should be a list. The first element of the entry is a string
792 used as the menu entry. The second element is a string containing a
793 doctype declaration (this can be nil if no doctype). The rest of the
794 list should be a list of variables and values. For backward
795 compatibility a single string instead of a variable is assigned to
796 @code{sgml-default-dtd-file}. All variables are made buffer local and
797 are also added to the buffers local variables list.
799 When an entry is selected from the DTD menu, the doctype declaration will
800 be inserted, the variables will be set to the values in the entry and a
801 local variables list will be created in the buffer.
807 sgml-default-dtd-file "~/sgml/html.ced"
808 sgml-omittag nil sgml-shorttag nil)
809 ("HTML+" "<!doctype htmlplus system 'htmlplus.dtd'>"
810 "~/sgml/htmlplus.ced"
811 sgml-omittag t sgml-shorttag nil)
812 ("DOCBOOK" "<!doctype docbook system 'docbook.dtd'>"
814 sgml-omittag nil sgml-shorttag t)))
819 @c ------------------------------------------------------------
820 @node Information from the DTD, Customizing DTD, Inserting a DOCTYPE, Managing the DTD
821 @comment node-name, next, previous, up
822 @section Information from the DTD
826 PSGML can list various information about the current DTD.
827 The following commands can be used via @kbd{M-x} and
828 can also be found in the DTD menu.
831 @findex sgml-describe-dtd
832 @item sgml-describe-dtd
833 Display information about the current DTD.
835 @findex sgml-describe-element-type
836 @item sgml-describe-element-type
837 Describe the properties of an element type as declared in the current DTD.
840 @findex sgml-describe-entity
841 @item sgml-describe-entity
842 Describe the properties of an entity as declared in the current DTD.
844 @findex sgml-list-elements
845 @item sgml-list-elements
846 Will list all elements and the attributes declared for the element.
848 @findex sgml-list-attributes
849 @item sgml-list-attributes
850 Will list all attributes declared and the elements that use them.
852 @findex sgml-list-terminals
853 @item sgml-list-terminals
854 Will list all elements that can contain data.
856 @findex sgml-list-occur-in-elements
857 @item sgml-list-occur-in-elements
858 Will list all element types and where it can occur.
860 @findex sgml-list-content-elements
861 @item sgml-list-content-elements
862 Will list all element types and the element types that can occur
867 @c ---------------------------------------------------------------------------
868 @node Customizing DTD, , Information from the DTD, Managing the DTD
869 @comment node-name, next, previous, up
870 @section Customizing DTD
872 PSGML can be customized by process instructions starting with ``PSGML''
873 in the DTD. Generally this associates some information with element
874 types. E.g., if @code{sgml-fill-element} should skip the element type
875 or if the content should be displayed with a special font.
877 The general syntax is
879 @samp{<?PSGML ELEMENT} @var{gi} (@var{prop} = @var{value})* @samp{>}
882 Note: in XML the ending delimiter is @samp{?>}, in SGML mode a
883 trailing @samp{?} will be ignored if preceded by a space.
885 Where @var{gi} is the element type, @var{prop} is a propery
886 described below, and @var{value} is the value for the property. The
887 first part from @samp{PSGML} to @var{gi} is read with current setting
888 for @samp{NAMECASE GENERAL}, i.e., case insensitive for normal SGML
889 but case sensitive in XML mode. The @var{prop} and @var{value} is read
890 using Emacs Lisp conventions, i.e. case sensitive and @var{value} is a
891 lisp expression (not evaluated).
896 <?PSGML ELEMENT PRE nofill=t face=fixed-pitch>
903 Set to either @code{t} or @code{nil}. If @code{t} the elements of this
904 type will be ignored when filling with @code{sgml-fill-element}.
905 Note that Emacs normal filling functions will not honor this.
908 Set to the name of an Emacs face. Should be a face that exists in
909 Emacs. E.g. @code{bold}, @code{italic}, @code{fixed-pitch}. The
910 content of elements of this type will be displayed in that face.
913 Set to a list of attribute names. E.g., @code{attnames=("ID" "CLASS"
914 "ONCLICK")}. This controls the attributes included when using the
915 @code{sgml-edit-attributes} (@kbd{C-c C-a}) command. Only the
916 attributes in the list will be included and in that order. You can
917 also end the list with a @code{*} to include all attributes, but the
918 listed attributes will be on the top. E.g.,
919 @code{attnames=("ID" "CLASS" "ONCLICK" *)}.
920 Note: that the attribute names need to be written with the correct
921 case and in string quotes.
924 Control if element is included in @code{sgml-show-structure} (@kbd{C-c
925 C-s}). If set to @code{t}, the element is included and if set to
926 @code{ignore} it will not be included. @xref{Information, Showing information}.
929 Should be a string. The string will be displayed by
930 @code{sgml-show-current-element-type} (@kbd{C-c C-t}).
935 @c ---------------------------------------------------------------------------
936 @node Edit, Display, Managing the DTD, Top
937 @comment node-name, next, previous, up
938 @chapter Commands for editing
941 * Insert:: Inserting Markup
942 * Complete:: Markup completion
943 * Information:: Showing information
944 * Indent:: Indentation according to structure
945 * Move:: Move in the element structure
946 * Attributes:: Editing attributes
947 * Change and delete:: Changing and deleting markup
948 * Translating characters and entities::
951 @c ------------------------------------------------------------------
952 @node Insert, Complete, Edit, Edit
953 @comment node-name, next, previous, up
954 @section Inserting Markup
956 @c erik says "inserts" ??
957 The commands that insert start-tags works only if the document has an
960 Keyboard commands for inserting:
964 @findex sgml-insert-tag
966 Will ask, for the tag to insert, in the mini-buffer with completion on the
967 tags that are valid at point (@code{sgml-insert-tag}).
969 If the option @code{sgml-balanced-tag-edit} is non-nil, inserting a
970 start-tag will also insert the corresponding end-tag. If, in addition,
971 @code{sgml-auto-insert-required-elements} is non-nil, tags for elements
972 required between the inserted tags will also be inserted.
974 The list of valid tags, computed for a position in the buffer, will
979 The end-tag for the current element, if it can be ended at the position
980 and @code{sgml-balanced-tag-edit} is nil. Furthermore it will contain
981 end-tags for enclosing elements if the necessary omissible end-tag
982 declarations have been made in the DTD.
985 The start-tags of all elements that could occur after point. If
986 @code{sgml-omittag-transparent} is nil, the above will be limited to the
987 elements that can occur within the current element.
992 @findex sgml-insert-element
993 @vindex sgml-insert-end-tag-on-new-line
995 Insert start and end-tags for an element
996 (@code{sgml-insert-element}). The name of the element is read
997 from the mini-buffer with completion on valid elements. If
998 @code{sgml-insert-end-tag-on-new-line} is non-nil or the
999 element has element content, the end-tag will be inserted on a
1000 new line after the start-tag.
1002 @vindex sgml-omittag-transparent
1003 If @code{sgml-omittag-transparent} is nil, the list of valid elements
1004 will only contain the elements that can be in the content of the current
1007 @vindex sgml-auto-insert-required-elements
1008 @vindex sgml-insert-missing-element-comment
1009 Required elements in the content will be automatically inserted if the
1010 option @code{sgml-auto-insert-required-elements} is non-nil.
1011 When the content model demands an element but there is more
1012 than one to choose from, a comment can be inserted with the
1013 available choices if the option
1014 @code{sgml-insert-missing-element-comment} is non-nil.
1017 @findex sgml-add-element-to-element
1019 Inserts a new element in the current element where it is legal. Prompts
1020 for element name with completion. The completion list contains all
1021 elements that could be added to the current element somewhere, without
1022 making the content invalid. This assumes that the content is valid to
1023 begin with. Currently this list only has regular elements, not
1024 inclusions. The new element will be inserted as late as possible in the
1025 current element (unless prefix argument is given, then as early as
1029 @findex sgml-tag-region
1031 Makes the region into a new element (@code{sgml-tag-region}). Reads
1032 element name from mini-buffer with completion as for @kbd{C-c C-e}.
1035 @findex sgml-insert-end-tag
1037 Inserts an end-tag for the current element (@code{sgml-insert-end-tag}).
1039 @c note that this keybinding doesn't follow the conventions for
1040 @c major-modes. Perhaps warn that this binding may change in the next
1045 @findex sgml-split-element
1047 Split the current element at point. If repeated, the containing element
1048 will be split before the beginning of then current element.
1050 Typical use is to start a new paragraph element when inside a paragraph.
1053 @findex sgml-insert-attribute
1055 Read attribute name and value from mini-buffer and insert attribute
1056 specification (@code{sgml-insert-attribute}). If point is immediately
1057 after a start-tag, this command operates on that start-tag. Otherwise
1058 the command will operate on the element after point.
1060 The attribute name will be read with completion. If the attribute has a
1061 token list as declared value the attribute value will also be read with
1062 completion. The prompt for attribute value will typically look like:
1065 Value for @var{attribute} (@var{type} Default: @var{current value}):
1068 @c note that this keybinding doesn't follow the conventions for
1069 @c major-modes. Perhaps warn that this binding may change in the next
1073 @findex sgml-custom-markup
1075 Give keyboard access to the customized part of the Markup menu.
1076 Emacs will prompt for the markup to insert using the menu line as
1077 selector. (See @var{sgml-custom-markup} below.)
1085 Selecting from this menu will insert markup. The menu contains
1086 sub menus with tags and with entities, some other markup and a user
1091 @item Insert element
1092 Pops up a menu of valid elements and insert start and end-tags for
1093 the selected element. Selections from the menu works like the @kbd{C-c
1096 @item Insert start-tag
1097 Pops up a menu of valid start-tags and insert the selected tag. The
1098 menu has the same start-tags as the completion list for @kbd{C-c <}.
1100 @item Insert end-tag
1101 Pops up a menu of valid end-tags and insert the selected tag.
1104 Pops up a menu of valid elements and tag the region with the
1105 selection. Selections from the menu works like the @kbd{C-c C-r}
1109 Menu of all general entities defined in the DTD.
1111 @item Add Element to Element
1112 Pops up a menu of all elements valid somewhere in the current element.
1113 The menu contains all elements that could be added to the current
1114 element somewhere, without making the content invalid. The new element
1115 will be inserted as late as possible in the current element.
1117 @item Insert attribute
1118 Pops up a menu with all the attributes of an element. The element is
1119 either the one which start-tag is immediately before point or the
1120 element after point. Selecting from this menu edits the attribute
1121 specification list for the element.
1123 The menu has a sub menu for every attribute which declared value is a
1124 token list. The rest of the attributes are collected in one sub menu.
1125 For the token list attributes, selecting a value will insert that
1126 attribute-value pair. Selecting some other attribute reads the
1127 attribute-value from the mini-buffer and inserts the attribute value
1131 @kindex S-@key{mouse-3}
1132 A menu is also available directly with a mouse button click in the
1133 buffer. In GNU Emacs it is the first mouse button combined with shift
1134 (@kbd{S-@key{mouse-3}}). In XEmacs it is bound to the third mouse
1135 button. The mouse button click will pop-up a menu of valid tags or a
1136 menu of attributes if the point is in a start-tag. The attributes menu
1137 works as the ``Insert attribute'' menu from the menu-bar. The tags list
1138 is the list of valid tags described above for command @kbd{C-c <}.
1139 Selection from the tags menu works like the @kbd{C-c <} command, with
1140 the following exception:
1142 You can tag a region, with start and end-tag. There are two ways to
1143 indicate the region to mark:
1147 Use the normal mouse commands to mark region.
1149 For this to work you must either use @dfn{transient mark mode}
1150 (@pxref{Transient Mark, , Transient Mark Mode, emacs, The Emacs
1151 Editor}) or set the option @code{sgml-tag-region-if-active} to non-nil
1152 (don't set this unless you are sure that you want it).
1155 Alternatively make a secondary selection, this is done by holding down
1156 the meta key and using the mouse buttons.
1157 @xref{Secondary selection, , , emacs, The Emacs Editor}.
1158 Some window managers intercept these events, which makes it hard use the
1159 secondary selection in Emacs.
1162 @defopt sgml-balanced-tag-edit
1163 If non-nil, inserting a start-tag using the context menu will also
1164 insert the corresponding end-tag.
1167 @defopt sgml-auto-insert-required-elements
1168 If non-nil, automatically inserts required elements in the content
1169 of an inserted element.
1172 @defopt sgml-omittag-transparent
1173 If non-nil, will show legal tags inside elements with omissible start-tags
1174 and legal tags beyond omissible end-tags.
1177 @defopt sgml-tag-region-if-active
1178 If non-nil, the @samp{Insert tags} menu will tag a region if the region
1179 is considered active by emacs. If nil, region must be active and
1180 @code{transient-mark-mode} must be on for the region to be tagged.
1183 @defopt sgml-custom-markup
1184 Menu entries to be added to the Markup menu. The value should be a list
1185 of lists of two strings. The first string is the menu line and the
1186 second string is the text inserted when the menu item is selected. The
1187 second string can contain a @samp{\r} where the cursor should be left.
1188 Also, if a selection is made according to the same rules as for the
1189 @kbd{S-mouse-1} menu, the selection is replaced with the second string
1190 and @samp{\r} is replaced with the selection.
1195 (("Version1" "<![%Version1[\r]]>")
1196 ("New page" "<?NewPage>"))
1201 @defopt sgml-insert-missing-element-comment
1202 If non-nil, and sgml-auto-insert-required-elements also true,
1203 @code{sgml-insert-element} will insert a comment if there is an
1204 element required but there is more than one to choose from.
1207 @defopt sgml-insert-end-tag-on-new-line
1208 If non-nil, @code{sgml-insert-element} will put the end-tag on
1209 a new line after the start-tag. Useful on slow terminals if you
1210 find the end-tag after the cursor irritating.
1214 @c -------------------------------------------------------------------------
1215 @node Complete, Information, Insert, Edit
1216 @comment node-name, next, previous, up
1217 @section Markup completion
1220 @findex sgml-complete
1221 If you are typing in markup directly, @kbd{M-TAB} will help you by
1222 completing a tag name, an entity name or a markup declaration name. If
1223 you type @kbd{M-TAB} after a plain word, @code{ispell-complete-word}
1224 will be invoked instead.
1226 If you have typed (@point{} marks the position of point)
1232 @noindent and type @kbd{M-TAB} (assuming you use the @file{ISOLat1}
1233 entity set) you get:
1240 @c ---------------------------------------------------------------------------
1241 @node Information, Indent, Complete, Edit
1242 @comment node-name, next, previous, up
1243 @section Showing information
1245 Commands for showing information obtained by parsing the buffer.
1249 @findex sgml-show-context
1251 Shows in the message area: context at point, if in a tag or in mixed
1252 content and the open elements (@code{sgml-show-context}). The form of
1253 the string is controled by the user option
1254 @code{sgml-show-context-function}.
1257 @findex sgml-what-element
1259 Shows what element the character after point (under the cursor) belongs
1260 to; also shows context of element (@code{sgml-what-element}).
1263 @findex sgml-show-current-element-type
1265 Show information about the current element type and the valid element
1266 following the point.
1269 @findex sgml-show-structure
1271 Show the major element structure in a separate buffer (@samp{*Document
1272 structure*}). That buffer can be used to navigate the document, like
1273 an Occur buffer (@pxref{Other Repeating Search, , Other
1274 Search-and-Loop Commands, emacs, The Emacs Editor}). The structure
1275 shows container elements and the text of the first child element (if
1276 it is not a container). This works best for document types which uses
1277 containers and title structure (e.g. @samp{<div> <title>Heder</title>
1278 ..</div>}). PSGML uses a heuristic rule to identify container
1279 elements: it should have element content and be non empty. You can
1280 configure exceptions from this rule using a process instruction in the
1281 DTD (@pxref{Customizing DTD}).
1283 To include an element type @var{el1} that would otherwise be excluded:
1285 <?PSGML element @var{el1} structure=t?>
1288 To exclude an element type @var{el2} that would otherwise be included:
1290 <?PSGML element @var{el2} structure=ignore?>
1295 @findex sgml-list-valid-tags
1296 List contextually valid tags (@code{sgml-list-valid-tags}). Displays
1297 information about current element, all valid end-tags, valid start-tags
1298 in current element, and start-tags valid at this point but in other
1299 elements together with the tags omitted.
1302 *** This is no longer working
1304 You can make the mode-line display the name of the current open element
1305 by setting the @code{sgml-live-element-indicator} variable. Setting
1306 this will make all commands slower due to the work needed to keep the
1307 mode-line up to date.
1309 @defopt sgml-live-element-indicator
1310 If non-nil, indicate current element in mode line.
1312 NOTE: Setting this implies that every command can cause a parse.
1317 @defopt sgml-show-context-function
1318 The value shold be a function that generates a string from an element
1319 and the current markup type (if any). There are two ready made
1320 functions for this. The function @code{sgml-show-context-standard},
1321 the default, generates a string like @samp{#PCDATA in para in chapter
1322 in book}. The function @code{sgml-show-context-backslash} generates a
1323 string like @samp{book\chapter\para}.
1327 @c --------------------------------------------------------------------------
1328 @node Indent, Move, Information, Edit
1329 @comment node-name, next, previous, up
1330 @section Indentation according to structure
1334 @findex sgml-indent-or-tab
1335 @findex newline-and-indent
1336 You can indent a line according to the depth of element nesting at the
1337 beginning of the line. To indent the current line use @kbd{@key{TAB}}.
1338 You can also use @kbd{@key{LFD}} (@code{newline-and-indent}) to start a
1339 new line with correct indentation.
1341 @defopt sgml-indent-step
1342 How much to increment indent for every element level. If nil, no
1345 If this is nil, @kbd{@key{TAB}} will insert a tab instead of indenting.
1348 @defopt sgml-indent-data
1349 If non-nil, indent in data/mixed context also.
1354 @c ---------------------------------------------------------------------------
1355 @node Move, Attributes, Indent, Edit
1356 @comment node-name, next, previous, up
1357 @section Move in the element structure
1359 These commands move in the element structure. The commands uses
1360 knowledge of SGML syntax, and if available the specific DTD.
1364 @findex sgml-beginning-of-element
1366 Move to the (content) beginning of the current element
1367 (@code{sgml-beginning-of-element}).
1370 @findex sgml-end-of-element
1372 Move to the (content) end of the current element (@code{sgml-end-of-element}).
1375 @findex sgml-forward-element
1377 Move forward by element (@code{sgml-forward-element}).
1380 @findex sgml-backward-element
1382 Move backward by element (@code{sgml-backward-element}).
1385 @findex sgml-backward-up-element
1387 Move up to before current element (@code{sgml-backward-up-element}).
1390 @findex sgml-up-element
1392 Move up to after current element (@code{sgml-up-element}).
1395 @findex sgml-down-element
1397 Move down to the (content) beginning of the next element
1398 (@code{sgml-down-element}).
1401 @findex sgml-next-data-field
1403 Move to the next place where data is allowed (@code{sgml-next-data-field}).
1406 You can also move to the next place where there is some structural error
1407 with @kbd{C-c C-o} (@pxref{Validate}).
1410 @c ---------------------------------------------------------------------------
1411 @node Attributes, Change and delete, Move, Edit
1412 @comment node-name, next, previous, up
1413 @section Editing attributes
1415 @findex sgml-edit-attributes
1417 If you want to change the attributes of a start-tag you can simply edit
1418 them directly in the buffer. Or you can place the cursor at or after
1419 the start-tag and use the @code{sgml-edit-attributes} command, available
1420 from the @samp{SGML}-menu or on @kbd{C-c C-a}. This will create a new
1421 Emacs window with all possible attributes listed in the form
1424 @var{attribute name} = @var{current value}.
1427 The @var{current value} may be shown as @samp{#DEFAULT} if the attribute
1428 has not been given a value in the start-tag. The list also contains the
1429 attributes declaration as a comment. Note also that the @var{current
1430 value} is show without eventual quotes.
1434 It is now possible to edit the attribute values. You can move to the
1435 next attribute with @kbd{@key{TAB}}. If you want to let an attribute
1436 have its default value use @kbd{C-c C-d}, this will insert a
1437 @samp{#DEFAULT} in the value field.
1439 If Emacs is running in an X window, the @samp{#DEFAULT} will be
1440 underlined to distinguish it from normal values.
1443 Finish the editing with @kbd{C-c C-c}; this will replace the attribute
1444 values in the main buffer with those edited. Note that values will be
1447 If you want to abort the editing, you can remove the window with
1448 @kbd{C-x 0} or if you want it neat, kill the buffer and remove the
1451 Some other keys are:
1454 @findex sgml-edit-attrib-field-start
1456 Go to the beginning of the value field
1457 (@code{sgml-edit-attrib-field-start}).
1460 @findex sgml-edit-attrib-field-end
1462 Go to the end of the value field
1463 (@code{sgml-edit-attrib-field-end}).
1466 @findex sgml-edit-attrib-clear
1468 Clear the value field
1469 (@code{sgml-edit-attrib-clear}).
1472 @findex sgml-edit-attrib-default
1474 Set the value field to @samp{#DEFAULT}
1475 (@code{sgml-edit-attrib-default}). This is a special value that will
1476 make the attribute be implied.
1480 @c --------------------------------------------------------------------------
1481 @node Change and delete, Translating characters and entities, Attributes, Edit
1482 @comment node-name, next, previous, up
1483 @section Changing and deleting markup
1487 @findex sgml-change-element-name
1489 Change the name of the current element (@code{sgml-change-element-name}).
1490 Tries to translate attribute specifications. An attribute will be
1491 translated to an attribute with the same name. If the new element has
1492 no attribute with the same name, the attribute will be ignored. If
1493 there is an attribute with the same name but different declared content,
1496 ID attributes are handled specially, an attribute with declared value ID
1497 will always be translated to the attribute with declared value ID.
1500 @findex sgml-kill-markup
1502 Kill next tag, markup declaration or process instruction
1503 (@code{sgml-kill-markup}).
1506 @findex sgml-kill-element
1508 Kill the element following the cursor (@code{sgml-kill-element}).
1511 @findex sgml-untag-element
1513 Remove tags from current element (@code{sgml-untag-element}).
1516 @findex sgml-make-character-reference
1518 Convert character after point to a character reference
1519 (@code{sgml-make-character-reference}). If called with a numeric
1520 argument, convert a character reference back to a normal character.
1523 @findex sgml-fill-element
1525 Fills an element as a paragraph (@code{sgml-fill-element}). This is a
1526 substitute for the normal @code{fill-paragraph}. The command uses
1527 heuristics to decide what should be a paragraph.
1531 If point is in an element content, recursively fill the sub-elements.
1533 Find the biggest element with mixed content containing point.
1535 If the above element is mixed but contains elements with pure element
1536 content then fill what is between the pure elements as paragraphs and
1537 fill the pure elements recursively.
1540 @findex sgml-expand-all-shortrefs
1541 @item M-x sgml-expand-all-shortrefs
1542 Short references to text entities are expanded to the replacement text
1543 of the entity other short references are expanded into general entity
1544 references. If argument, @var{to-entity}, is non-@code{nil}, or if
1545 called interactive with numeric prefix argument, all short references
1546 are replaced by generally entity references.
1548 @findex sgml-normalize
1549 @item M-x sgml-normalize
1550 Normalize the document in the buffer. This will
1554 expand short references,
1556 insert missing tags,
1558 replace minimized tags with full tags,
1560 fix attribute specification lists according to options set.
1563 There is one argument, @var{to-entity}, with the same meaning as for
1564 @code{sgml-expand-all-shortrefs}.
1566 There is one option for the normalize command. With its default value,
1567 normalize may actually change the data content of some elements. But
1568 only by removing some white-space from the end of elements with omitted
1572 @defopt sgml-normalize-trims
1573 If non-nil, @code{sgml-normalize} will trim off white space from end of
1574 element when adding end-tag.
1580 @c --------------------------------------------------------------------------
1581 @node Translating characters and entities, , Change and delete, Edit
1582 @comment node-name, next, previous, up
1583 @section Translating between characters and entity references
1587 Set the variable @code{sgml-display-char-list-filename} to a file that
1588 contains mappings between all characters present in the presentation
1589 character set, and their "standard replacement text" names, e.g. "å"
1590 -> "[aring ]", e.t.c.
1592 The default value for this variable is `iso88591.map'.
1594 Then use the functions (also in the Modify menu)
1597 @findex sgml-charent-to-display-char
1598 @item sgml-charent-to-display-char
1599 @findex sgml-display-char-to-charent
1600 @item sgml-display-char-to-charent
1603 to translate between entities and characters.
1605 @c ---------------------------------------------------------------------------
1606 @node Display, Miscellaneous options, Edit, Top
1607 @comment node-name, next, previous, up
1608 @chapter Appearance of text in the buffer
1611 * Fold:: Folding editing
1613 * Highlight:: Highlighting markup
1616 @c ---------------------------------------------------------------------------
1617 @node Fold, Hiding markup, Display, Display
1618 @comment node-name, next, previous, up
1619 @section Folding editing
1621 With these commands you can make parts of the text temporarily invisible
1622 to make it easier to see the overall structure of your text.
1624 When folding a region all the lines but the first will be invisible.
1625 The first line of the region will still be visible with an ellipsis at
1628 @xref{Outline Mode, , , emacs, The Emacs Editor}.
1632 @findex sgml-fold-region
1634 The region between point and mark will be folded (@code{sgml-fold-region}).
1637 @findex sgml-fold-element
1639 The region between the start and end of the current element will be
1640 folded (@code{sgml-fold-element}).
1642 This command can also fold the SGML declaration or the DOCTYPE
1646 @findex sgml-fold-subelement
1648 Fold all the sub elements of the current element
1649 (@code{sgml-fold-subelement}).
1653 @findex sgml-unfold-line
1656 Unfold the current line, assuming it is the first line of a folded
1657 region (@code{sgml-unfold-line}).
1660 @findex sgml-unfold-element
1662 Make all lines in current element visible (@code{sgml-unfold-element}).
1665 @findex sgml-unfold-all
1667 Make all lines in current buffer visible (@code{sgml-unfold-all}).
1670 @findex sgml-expand-element
1672 Unfold current element and then fold the subelements
1673 (@code{sgml-expand-element}). If the current element is folded this
1674 expands what is visible.
1678 @c ---------------------------------------------------------------------------
1679 @node Hiding markup, Highlight, Fold, Display
1680 @comment node-name, next, previous, up
1681 @section Hiding markup
1683 *** Describe hide-tags
1686 @c ---------------------------------------------------------------------------
1687 @node Highlight, , Hiding markup, Display
1688 @comment node-name, next, previous, up
1689 @section Highlighting markup
1692 PSGML can highlight the markup giving the markup a different @dfn{face}
1693 (@pxref{Faces, , Using Multiple Typefaces, emacs, The Emacs Editor}).
1694 The highlighting will only be done if the variable @code{sgml-set-face}
1695 is non-@code{nil}. The default settings make tags bold and comments
1696 italic, but this can be modified with the variable
1697 @code{sgml-markup-faces}. When highlighting is on PSGML will parse after
1698 every command until the whole buffer has been parsed or user event
1701 @findex sgml-clear-faces
1702 To remove the highlighting type @kbd{M-x sgml-clear-faces}.
1704 @defopt sgml-set-face
1705 If non-nil, psgml will set the face of parsed markup.
1708 @defopt sgml-markup-faces
1709 A list of markup to face mappings.
1710 Each element looks like @code{(@var{markup-type} . @var{face})}.
1711 Possible values for @var{markup-type} is:
1721 ignored marked section
1723 marked section end, if not ignored
1725 marked section start, if not ignored
1727 processing instruction
1741 @c ------------------------------------------------------------------
1742 @node Miscellaneous options, Bugs, Display, Top
1743 @comment node-name, next, previous, up
1744 @chapter Miscellaneous options
1746 *** describe sgml-save-options
1748 @defopt sgml-ignore-undefined-elements
1749 Start-tags for undefined elements will either be ignored, if
1750 @code{sgml-ignore-undefined-elements} is @code{t}, or assumed to be
1751 acceptable in the current element and defined with @code{O O ANY}
1754 @defopt sgml-range-indicator-max-length
1755 Maximum number of characters used from the first and last entry
1756 of a sub-menu to indicate the range of that menu.
1758 @vindex sgml-max-menu-size
1759 This is used for long menus of elements, tags or entities that are split
1760 into @code{sgml-max-menu-size} big sub-menus.
1766 @c ------------------------------------------------------------------
1767 @node Bugs, Index, Miscellaneous options, Top
1768 @comment node-name, next, previous, up
1772 If you encounter something that you think is a bug, please report
1773 it. Try to include a clear description of the undesired behaviour.
1774 A test case that exhibits the bug, would also be useful.
1776 You can report a bug with the command @kbd{M-x sgml-submit-bug-report}.
1778 When PSGML needs contextual information it parses the document up to
1779 the point. During the parsing, it builds a parse tree. The parse
1780 tree is used to initialize the next parse, to avoid having to parse
1781 things already parsed. Changes to the buffer is supposed to prune
1782 the tree of all outdated information. But if you get strange
1783 complaints from the parser, try and back up a bit and use @kbd{C-c
1784 C-o} (@code{sgml-next-trouble-spot}).
1788 @c ------------------------------------------------------------------
1789 @node Index, , Bugs, Top
1790 @comment node-name, next, previous, up