Mercurial > hg > xemacs-beta

comparison lisp/psgml/README.psgml @ 70:131b0175ea99 r20-0b30

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r20-0b30
author cvs
date Mon, 13 Aug 2007 09:02:59 +0200
parents bcdc7deadc19
children c7528f8e288d
comparison
equal deleted inserted replaced
69:804d1389bcd6 70:131b0175ea99
1 This is the READ ME file for psgml.el version 1.0 -*- text -*- 1 This is the READ ME file for psgml.el version 1a12. -*- text -*-
2 2
3 PSGML is a major mode for editing SGML documents. It works with 3 PSGML is a major mode for editing SGML documents. It works with
4 GNU Emacs 19.19 and later or with XEmacs 19.13. 4 GNU Emacs 19.19 and later or with XEmacs 19.13.
5 5
6 This distribution should contain the following source files: 6 This distribution should contain the following source files:
11 psgml-edit.el 11 psgml-edit.el
12 psgml-parse.el 12 psgml-parse.el
13 psgml-dtd.el 13 psgml-dtd.el
14 psgml-info.el 14 psgml-info.el
15 psgml-charent.el 15 psgml-charent.el
16 psgml-debug.el -- some functions used in development
16 psgml-api.texi -- internals documentation 17 psgml-api.texi -- internals documentation
17 psgml-api.el -- Extra functions for the API 18 psgml-api.el -- Extra functions for the API
19 fs.el -- Example use of psgml to format a SGML file
20 style.fs -- example style file for fs.el
21 catalog.sgml -- example SGML-file for fs.el and style.el
18 iso88591.map 22 iso88591.map
19 Makefile.in 23 Makefile.in
20 24
21 In addition the distribution contains the formatted versions of the 25 In addition the distribution contains the formatted versions of the
22 documentation files (psgml.info, ...). But the compiled elisp code is 26 documentation files (psgml.info, ...). But the compiled elisp code is
40 the command psgml-compile-files. Then you have to set load-path or 44 the command psgml-compile-files. Then you have to set load-path or
41 move the .elc files. 45 move the .elc files.
42 46
43 Send bug reports, comments and suggestions to lenst@lysator.liu.se. 47 Send bug reports, comments and suggestions to lenst@lysator.liu.se.
44 48
45 New in version 1.0 49 New in version 1.0a12
46 50
47 * Main changes 51 See ChangeLog...
48 52
49 ** Support for general entities 53
50 54 New in version 1.0a11
51 ** Support for short reference 55
52 56 * Autoconf support
53 ** Support for catalog files 57
54 58 Tanks to Karl Eichwalder.
55 ** New mechanism for caching parsed DTD 59
56 60 * Bugs fixed
57 ** Includes commands to list various aspects of the DTD 61
58 62 ** after-change-function lost if text entity referenced
59 * Entity support 63
60 64 ** Mouse button 3, has wrong binding in XEmacs.
61 PSGML will recognize entity references (except in attribute values). If 65
62 the entity is a general text entity, PSGML will also parse the content 66
63 of the entity. To support this PSGML has a new entity manager with a 67 New in version 1.0a10
64 new mechanism for looking up entities (see belove). 68
65 69 * Changed how fontification is done
66 Short references are also supported, for the short reference delimiters
67 from the concrete reference syntax.
68
69 There are some new and changed commands to complete the entity support:
70
71 ** Command: `sgml-expand-entity-reference'
72
73 Insert the text of the entity referenced at point.
74
75 ** Command: `sgml-expand-all-shortrefs'
76
77 Expand all short references in the buffer. Short references to text
78 entities are expanded to the replacement text of the entity, other
79 short references are expanded into general entity references. If
80 argument, `to-entity', is non-nil, or if called interactive with
81 numeric prefix argument, all short references are replaced by generally
82 entity references.
83
84 ** Command: `sgml-normalize'
85
86 Changed to expand short references also. Normalize buffer by filling in
87 omitted tags and expanding empty tags. Argument `to-entity' controls
88 how short references are expanded as with `sgml-expand-all-shortrefs'.
89
90 * Fontification
91
92 If `sgml-set-face' is true and the DTD has been activated, PSGML will
93 automatically set the face of markup in the buffer.
94 70
95 First the current line is parsed and fontified. If this would mean 71 First the current line is parsed and fontified. If this would mean
96 parsing more than 500 chars, wait 1 second first. 72 parsing more than 500 chars, wait 1 second first.
97 73
98 The rest of the buffer is fontified after 6 seconds idle time. 74 Wait 6 seconds and then fontify rest of buffer.
99 75
100 Fontification can be interrupted by any input event. 76 These waits and the parsing can be interrupted by any input event.
101 77
102 The buffer can be fontified initially if `sgml-auto-activate-dtd' is 78 This seems to work well with Emacs 19.29 and XEmacs 19.13 on Linux.
103 true. 79
104 80 * XEmacs menus made with easy-menu
105 * New entity manager 81
106 82 Now there is only one set of menu for both Emacs and XEmacs.
107 The new entity manager will handle an entity reference thus: 83
108 84 * Tracing catalog lookup
109 ** If the entity has a system identifier, the entity manager will first
110 try and call the functions on `sgml-sysid-resolve-functions' with the
111 system identifier as argument, and if any function returns non-nil
112 assume that the function has handled the entity.
113
114 ** If the entity has a system identifier and
115 `sgml-system-identifiers-are-preferred' is non-nil, the system
116 identifier will be used as a file name relative to the file containing
117 the entity declaration.
118
119 ** Next the entity manager will try the catalog, and
120
121 ** if not found there use the `sgml-public-map'.
122
123 ** Finally if the entity has not been found and it has a system
124 identifier, this will be used as a file name.
125
126 Note: `sgml-system-path' is no longer used for entity lookup.
127
128 The catalog files searched is given by the variable
129 `sgml-local-catalogs' and `sgml-catalog-files'. The
130 `sgml-catalog-files' variable is initialized from the environment
131 variable `SGML_CATALOG_FILES' (should be a colon separated list of
132 files). The `sgml-local-catalogs' variable is assumed to be set in a
133 files local variables.
134
135 File names for external entities (e.g system identifiers) are relative
136 to the directory containing the file declaring the entity.
137
138 The `sgml-public-map' is initialized from the environment variable
139 `SGML_PATH'.
140
141 `sgml-system-path' defaults to nil.
142
143 Supports most of sgmls substitutions for sgml-public-map. Supported:
144 %%, %N, %P, %S, %Y, %C, %L, %O, %T, %V. Unsupported: %D, %X, %A, %E,
145 %I, %R, %U. Note: that %D is and alias for %C in PSGML (historical
146 accident).
147
148 * New and changed options
149
150 ** `sgml-recompile-out-of-date-cdtd'
151
152 ** New options for insert-element:
153 `sgml-insert-missing-element-comment' and
154 `sgml-insert-end-tag-on-new-line'.
155
156 ** `sgml-validate-files' and slight change of `sgml-validate-command'
157
158 The variable `sgml-validate-command' can now be a list of strings. The
159 strings can contain %-sequences that will be expanded: %b to buffer
160 file name, %s to SGML Declaration file, either the value of
161 sgml-declaration variable or SGML Declaration file for parent document
162 or DOCTYPE file or SGMLDECL from catalog. %d value of `sgml-doctype'.
163
164 ** `sgml-set-face'
165
166 Now automatically sets faces for all visible text, with a delay of 1s.
167
168 ** `sgml-exposed-tags'
169
170 The list of tag names that remain visible, despite `M-x
171 sgml-hide-tags'. Each name is a lowercase string, and start-tags and
172 end-tags must be listed individually.
173
174 ** `sgml-auto-activate-dtd'
175
176 PSGML was behaving inconsistent when a new file was loaded. If the
177 variable `sgml-set-face' was true the DTD would automatically be
178 activated (loaded or parsed), but only if psgml-parse already loaded.
179
180 Rather than let `sgml-set-face' decide if the DTD is activated, there
181 is now a distinct option for this. This option works even the first
182 time.
183
184 If non-nil, loading a sgml-file will automatically try to activate its
185 DTD. Activation means either to parse the document type declaration or
186 to load a previously saved parsed DTD. The name of the activated DTD
187 will be shown in the mode line.
188
189 * Various
190
191 ** Tracing catalog lookup
192 85
193 To help debug entity lookup there is a new option 86 To help debug entity lookup there is a new option
194 `sgml-trace-entity-lookup'. If this option is t messages will be logged 87 `sgml-trace-entity-lookup'. If this option is t messages will be
195 in *SGML LOG* buffer when external entities are looked up. These 88 logged in *SGML LOG* buffer when external entities are looked up.
196 messages shows entity, catalogs searched, and entry type in catalog 89 These messages shows entity, catalogs searched, and entry type in
197 where entity was found. 90 catalog where entity was found.
91
92
93
94 * Renamed default style sheet for fs.el
95
96 The default style sheet used by fs.el, style sheet formatter example
97 is now "style.fs".
98
99
100 New in version 1.0a9
101
102 * XEmacs may have problem if sgml-set-face is t
103
104 I tried with the latest version on a sun4 Solaris 2 machine and PSGML
105 would always parse to the end of the buffer even if I typed something.
106 There seem to be a problem with the input-pending-p function. I don't
107 know if this is specific for Solaris. Emacs on Solaris has problems
108 with signal handling.
109
110
111 * New options for insert-element
112 ** sgml-insert-missing-element-comment
113 ** sgml-insert-end-tag-on-new-line
114
115 * psgml-api:
116 ** sgml-map-content: new optional argument. If the argument ENTITY-FUN
117 is specified it should be a function with one argument. The function
118 will be called for data entity references instead of the entity text
119 being passed to the DATA-FUN. The argument is the entity referenced.
120 Use `sgml-entity-name', `sgml-entity-type' etc.
121
122
123 Version 1.0a8 has only bug-fixes.
124
125
126 New in version 1.0a7
127
128 * Better CATALOG parsing
129
130 ** Will handle SGMLDECL, etc..
131
132 ** New option: sgml-system-identifiers-are-preferred
133 If nil PSGML will look up external entities by searching the catalogs
134 in `sgml-local-catalogs' and `sgml-catalog-files' and only if the entity
135 is not found in will a given system identifier be used. If the variable
136 is non-nil and a system identifier is given, the system identifier will
137 be used for the entity. If no system identifier is given the catalogs
138 will searched.
139
140 * File names for external entities (e.g system identifiers) are
141 relative to the directory containing the file declaring of the entity.
142
143 * Changes to how the DTD is found
144
145 ** If the variable sgml-doctype is set, it should be the name of a file
146 containing the DOCTYPE declaration to use.
147
148 ** The variable sgml-parent-document is used when the current file
149 is part of a bigger document, and the variable describes how the
150 current files content fits into the element hierarchy. The variable
151 should have the form
152
153 (parent-file context-element* top-element (has-seen-element*)?)
154
155 *** parent-file (string) is the name of the file containing the
156 document entity.
157
158 *** context-element (string) is used to set up exceptions and short
159 reference map. Good candidates for these elements are the elements
160 open when the entity pointing to the current file is used.
161
162 *** top-element (string) is the top level element in the current file.
163 The file should contain one instance of this element, unless the last
164 (lisp) element of sgml-parent-document is a list. If it is a list, the
165 top level of the file should follow the content model of top-element.
166
167 *** has-seen-element (string) element satisfied in the content model
168 of top-element.
169
170
171 * sgml-validate
172 The variable sgml-validate-command can now be a list of strings. The
173 strings can contain %-sequences that will be expanded:
174 %b to buffer file name,
175 %s to SGML Declaration file, either the value of sgml-declaration
176 variable or SGML Declaration file for parent document or DOCTYPE file or
177 SGMLDECL from catalog.
178 %d value of sgml-doctype.
179
180
181 * Hooks
182
183 ** sgml-new-attribute-list-function
184 This hook is run when a new element is inserted to construct the
185 attribute specification list. The default function prompts for the
186 required attributes.
187
188
189 * API
190
191 ** New file psgml-api.el
192
193 This file contain API-functions that are not used by other parts of
194 psgml. Use (require 'psgml-api) to use the API functions (psgml-api
195 includes the rest of the psgml files).
196
197 The new functions in psgml-api is two functions to traverse the element
198 structure.
199
200 *** (sgml-map-content element element-function data-function pi-function)
201
202 Call element-function with every child of element.
203 Call data-function with all the data in element.
204 Don't modify the buffer in these functions.
205
206 *** (sgml-map-element-modify function element)
207
208 Call function on every sub element of element, allows the function to
209 modify the buffer (e.g. add/modify attributes of the elements).
210
211 ** Example of API use: fs.el -- a simple style sheet driven formatter.
212
213 Try fs.el with the catalog.sgml file. The style.el is the style sheet
214 for catalog.sgml. The command to format current buffer is
215 `M-x style-format'.
216
217
218 New in version 1.0 a6
219
220 * Entity manager
221
222 ** Use system id as file name, if there is no %S in sgml-public-map.
223
224 ** Finds PUBLIC entries before DOCTYPE and ENTITY in catalog files.
225
226 * Better error recovery for out of context data and tags
227
228 * New command: sgml-general-dtd-info
229
230 * Disables auto-fill in the prolog
231
232 * Insert element leaves point at the end of the element,
233 it used to leave point at the beginning of the element.
234
235 * sgml-hide-tags/attributes is better at handling minimized tags
236
237 * New options
238 ** sgml-validate-files and slight change of sgml-validate-command.
239 ** sgml-recompile-out-of-date-cdtd
240
241 * Now saving attribute specification list in parse tree
242 Faster sgml-element-attval, but more memory used.
243
244 * Long menus that are split into sub-menus now show the range of
245 choices in the different sub-menus.
246
247 The option `sgml-range-indicator-max-length' determines how many
248 characters from the first and the last choice to show.
249
250 * Private abbrev table
251
252
253 New in version 1.0 a5
254
255 * New menu structure
256 Perhaps there is to many top-level menus now. Any suggestions how to
257 organize the menus?
258
259 * Some new functions
260
261 ** Information from the DTD (used to be nefarious.el)
262
263 *** sgml-describe-element-type
264
265 *** sgml-describe-entity
266
267 *** sgml-list-elements
268 Will list all elements and the attributes declared for the element.
269
270 *** sgml-list-attributes
271 Will list all attributes declared and the elements that use them.
272
273 *** sgml-list-terminals
274 Will list all elements that can contain data.
275
276 *** sgml-list-occur-in-elements
277 Will list all element types and where it can occur.
278
279 *** sgml-list-content-elements
280 Will list all element types and the element types that can occur
281 in its content.
282
198 283
199 ** Translating between characters and entity references 284 ** Translating between characters and entity references
200 285
201 Set the variable `sgml-display-char-list-filename' to a file that 286 Set the variable `sgml-display-char-list-filename' to a file file that
202 contains mappings between all characters present in the presentation 287 contains mappings between all characters present in the presentation
203 character set, and their "standard replacement text" names, e.g. "å" -> 288 character set, and their "standard replacement text" names, e.g. "å"
204 "[aring ]", e.t.c. The default value for this variable is 289 -> "[aring ]", e.t.c.
205 `iso88591.map'. 290
206 291 The default value for this variable is `iso88591.map'.
207 Use the functions (also in the Modify menu) 292
208 `sgml-charent-to-display-char' and `sgml-display-char-to-charent' to 293 The use the functions (also in the Modify menu)
209 translate between entities and characters. 294
210 295 sgml-charent-to-display-char
211 ** Handling of missing DOCTYPE 296 sgml-display-char-to-charent
212 297
213 If the document prolog does not contain a document type declaration, 298 to translate between entities and characters.
299
300
301
302 * Two major bugs fixed
303 ** DTD using undeclared elements was improperly saved
304 ** Bug in using a precompiled DTD and local element, attlist or usemap
305 declaration.
306
307
308
309 New in version 1.0 a4
310
311 * If the document prolog does not contain a document type declaration,
214 PSGML will try to supply one on the form `<!DOCTYPE DocTypeName 312 PSGML will try to supply one on the form `<!DOCTYPE DocTypeName
215 SYSTEM>' If the variable `sgml-default-doctype-name' is defined this 313 SYSTEM>' If the variable `sgml-default-doctype-name' is defined this
216 will be used for the document type name, otherwise the GI of the first 314 will be used for the document type name, otherwise the GI of the first
217 start tag will be used. I.e., if the document starts with `<book>', a 315 start tag will be used. I.e., if the document starts with `<book>', a
218 document type declaration `<!DOCTYPE book SYSTEM>' will be assumed. 316 document type declaration `<!DOCTYPE book SYSTEM>' will be assumed.
219 317
220 ** Handling of tags for undefined elements 318
221 319 * Compiled DTDs are now associated with external `Document Type
222 *** Start-tags for undefined elements will either be ignored, if 320 Declaration Subset' entities. You will have to create a catalog with
223 `sgml-ignore-undefined-elements' is `t', or assumed to be acceptable in 321 entries for all the DTDs that should be compiled. This should make
322 it, in most cases, unnecessary to make saved dtds or to set the
323 `sgml-default-dtd-file', at the expense of having to maintain the
324 catalog file.
325
326 ** Options
327
328 `sgml-ecat-files' List of compiled dtd catalog files.
329 Default: ("ECAT" "~/sgml/ECAT" "/usr/local/lib/sgml/ECAT")
330
331 `sgml-local-ecat-files' This can be set as a buffer local variable to
332 a list of catalogs to be searched before `sgml-ecat-files'.
333
334 ** Catalog format
335
336 The catalog is similar to the catalog used to resolve public
337 identifiers. There are two types of entries:
338
339 PUBLIC pubid pents? cfile
340 and
341 FILE file pents? cfile
342
343 where pubid is a public identifier (as a minimum literal), pents is a
344 optional list of parameter entities and values, file is the file name
345 of a DTD file and cfile is the name of the complied DTD. The syntax
346 for pents is
347
348 `[' (name literal)* `]'
349
350 Example:
351
352 PUBLIC "-//lenst//dtd My DTD//en" cdtd/bar
353 FILE "bar.dtd" cdtd/bar
354
355 To better handle DTDs with options, like TEI and HTML 2.0/+ it is
356 possible to have several entries for the same DTD with different
357 parameter entity settings. The parameters are listed between `[' and
358 `]' before the file name of the compiled dtd.
359
360 FILE "~/sgml/htmlplus.dtd"
361 [ HTML.emph "INCLUDE" ] "~/sgml/htmlplus.ced"
362
363 PUBLIC "-//Text Encoding Initiative//DTD
364 P3 3.6.1: Main TEI document type declaration//EN"
365 [ TEI.prose 'INCLUDE' TEI.analysis 'INCLUDE' ] "tei2an.cdtd"
366
367 PUBLIC "-//Text Encoding Initiative//DTD
368 P3 3.6.1: Main TEI document type declaration//EN"
369 [ TEI.prose 'INCLUDE' TEI.verse 'INCLUDE' ] "tei2verse.cdtd"
370
371 The entries will be searched in order and the first matching will be
372 used. Put more specific entries before less specific. Matching is
373 done by matching pubid or file and checking that all the listed
374 parameters are defined with the listed values.
375
376
377
378 ** Example: setting up for editing HTML
379
380 If you have the files for the html.dtd in ~/sgml.
381 Put in ~/sgml/CATALOG:
382 PUBLIC "-//IETF//DTD HTML//EN" html.dtd
383 PUBLIC "-//IETF//DTD HTML//EN//2.0" html.dtd
384 PUBLIC "-//IETF//DTD HTML Level 1//EN//2.0" html-1.dtd
385 PUBLIC "-//IETF//ENTITIES Added Latin 1 for HTML//EN" ISOlat1.sgml
386 DOCTYPE HTML html.dtd
387
388 Put in ~/sgml/ECAT:
389 FILE html.dtd [ HTML.Recommended "INCLUDE" ] cdtd/html-r
390 FILE html.dtd cdtd/html
391
392 Put ~/sgml/CATALOG in sgml-catalog-files and ~/sgml/ECAT in
393 sgml-ecat-files.
394
395 Now it should be possible to edit html files if you put them in
396 sgml-mode. The file must either start with a proper DOCTYPE or with a
397 <html> tag. To be able to start with empty files and to edit files
398 not starting with <html> you can create a html-mode that sets the
399 default document type name:
400
401 (defun html-mode ()
402 (interactive)
403 (sgml-mode)
404 (make-local-variable 'sgml-declaration)
405 (make-local-variable 'sgml-default-doctype-name)
406 (setq sgml-declaration "~/sgml/html.decl"
407 sgml-default-doctype-name "html"
408 sgml-always-quote-attributes t
409 sgml-indent-step 2
410 sgml-indent-data t
411 sgml-minimize-attributes nil
412 sgml-omittag t
413 sgml-shortag t ))
414
415
416 * Handling of tags for undefined elements
417
418 ** Start-tags for undefined elements will either be ignored, if
419 `sgml-ignore-undefined-elements' is t, or assumed to be acceptable in
224 the current element and defined with `O O ANY'. 420 the current element and defined with `O O ANY'.
225 421
226 *** An end-tag for an element that is not currently open will be 422 ** An end-tag for an element that is not currently open will be ignored.
227 ignored. 423
228 424
229 ** Cleaned up Markup menu 425 * I have (as an experiment) turned off all warnings. Warnings are only
230 426 given if the sgml-next-trouble-spot is used or while parsing the DTD.
427
428
429 * Entity manager
430
431 ** sgml-system-path is no longer used for entity lookup
432
433 ** PSGML will recognize that a catalog file has been changed
434
435
436 News in version 1.0 a3
437
438 * Change in user options
439
440 ** sgml-live-element-indicator no longer buffer local
441
442 ** sgml-save-options only saves:
443 (sgml-parent-document sgml-omittag sgml-shorttag
444 sgml-minimize-attributes sgml-always-quote-attributes sgml-indent-step
445 sgml-indent-data sgml-default-dtd-file sgml-exposed-tags)
446 and saves all of them, even if they have no buffer local value
447
448 ** Options menu split in to two menus
449
450 * Cleaned up Markup menu
231 The removed entries can be added with sgml-custom-markup: 451 The removed entries can be added with sgml-custom-markup:
232 452
233 (setq sgml-custom-markup 453 (setq sgml-custom-markup
234 '(("<!entity ... >" "<!entity \r>\n") 454 '(
235 ("<!attlist ... >" "<!attlist \r>\n") 455 ("<!entity ... >" "<!entity \r>\n")
236 ("<!element ... >" "<!element \r>\n") 456 ("<!attlist ... >" "<!attlist \r>\n")
237 ("<!doctype ...>" "<!doctype \r -- public or system --\n[\n]>\n") 457 ("<!element ... >" "<!element \r>\n")
238 ("Local variables comment" "<!--\nLocal variables:\n\rEnd:\n-->\n") 458 ("<!doctype ...>" "<!doctype \r -- public or system --\n[\n]>\n")
239 ("Comment" "<!-- \r -->\n") )) 459 ("Local variables comment" "<!--\nLocal variables:\n\rEnd:\n-->\n")
240 460 ("Comment" "<!-- \r -->\n")
241 ** New commands 461 ))
242 462
463
464 * Some bug fixes
465 Including new default for sgml-catalog-files is
466 "CATALOG" and "/usr/local/lib/sgml/CATALOG".
467
468 * Some tuning
469
470
471 News in version 1.0 a2
472
473 * Support for short references
474
475 ** Command: sgml-expand-all-shortrefs
476 Expand all short references in the buffer. Short references to text
477 entities are expanded to the replacement text of the entity, other
478 short references are expanded into general entity references. If
479 argument, TO-ENTITY, is non-nil, or if called interactive with numeric
480 prefix argument, all short references are replaced by generally entity
481 references.
482
483 ** sgml-normalize: expand short references also
484 Normalize buffer by filling in omitted tags and expanding empty tags.
485 Argument TO-ENTITY controls how short references are expanded as with
486 `sgml-expand-all-shortrefs'.
487
488
489 * Variable: sgml-auto-activate-dtd
490
491 PSGML was behaving inconsistent when a new file was loaded. If the
492 variable `sgml-set-face' was true the DTD would automatically be
493 activated (loaded or parsed), but only if psgml-parse already loaded.
494
495 Rather than let `sgml-set-face' decide if the DTD is activated, there
496 is now a distinct option for this. This option works even the first
497 time.
498
499 If non-nil, loading a sgml-file will automatically try to activate its DTD.
500 Activation means either to parse the document type declaration or to
501 load a previously saved parsed DTD. The name of the activated DTD
502 will be shown in the mode line.
503
504
505 * face setting
506 If `sgml-set-face' is true and the DTD has been activated, PSGML will
507 automatically set the face of markup in the buffer. This is done by
508 parsing, with error messages turned off, as much as possible after
509 every command. The parsing is interrupted by input and is almost
510 transparent.
511
512 * Local catalog files
513 Variable `sgml-local-catalogs'
514 A list of SGML entity catalogs to be searched first when parsing the buffer.
515 This is used in addition to `sgml-catalog-files', and `sgml-public-map'.
516 This variable is automatically local to the buffer.
517
518 * New commands
243 Thanks to David Megginson the custom menus are now reachable from the 519 Thanks to David Megginson the custom menus are now reachable from the
244 keyboard: 520 keyboard:
245 521 ** C-c C-u C-d (sgml-custom-dtd)
246 `C-c C-u C-d' (`sgml-custom-dtd') 522 ** C-c C-u C-m (sgml-custom-markup)
247 523
248 `C-c C-u C-m' (`sgml-custom-markup') 524 * New command: sgml-expand-entity-reference
249 525 Insert the text of the entity referenced at point.
250 * Changes to API 526
251 527 * sgml-validate-command is now a format string
252 ** New hooks 528
253 529
254 *** `sgml-close-element-hook' 530 News in version 1.0 a1
255 531
256 The hook run by `sgml-close-element'. These functions are invoked with 532 * A lot of internal changes
257 `sgml-current-tree' bound to the element just parsed. 533
258 534 * Support for general entities
259 *** `sgml-new-attribute-list-function' 535
260 536 * New entity manager
261 This hook is run when a new element is inserted to construct the 537
262 attribute specification list. The default function prompts for the 538 The new entity manager will handle an entity thus:
263 required attributes. 539
264 540 1. If the entity has a system identifier, the entity manager will
265 *** `sgml-doctype-parsed-hook' 541 first try and call the functions on sgml-sysid-resolve-functions
266 542 with the system identifier as argument, and if any function returns
267 This hook is called after the doctype has been parsed. It can be used 543 non-nil assume that the function has handled the entity.
268 to load any additional information into the DTD structure. 544 2. Next the entity manager will try the catalogue, and
545 3. if not found there use the sgml-public-map.
546
547 The catalogue files searched is given by the variable
548 sgml-catalog-files (I suppose it would be confusing to call it
549 sgml-catalogue-files.) This variable is initialised from the
550 environment variable SGML_CATALOG_FILES (should be a colon separated
551 list of files).
552
553 The sgml-public-map is initialised from the environment variable
554 SGML_PATH.
555
556 sgml-system-path defaults to nil.
557
558 Supports most of sgmls substitutions for sgml-public-map.
559 Supported: %%, %N, %P, %S, %Y, %C, %L, %O, %T, %V
560 Unsupported: %D, %X, %A, %E, %I, %R, %U
561 Note: that %D is and alias for %C in PSGML (historical accident).
562
563
564 * Hooks
565
566 ** sgml-close-element-hook
567 The hook run by `sgml-close-element'.
568 These functions are invoked with `sgml-current-tree' bound to the
569 element just parsed.
570
571 ** sgml-doctype-parsed-hook
572 This hook is called after the doctype has been parsed.
573 It can be used to load any additional information into the DTD structure.
269 574
270 Example: add description to element types 575 Example: add description to element types
271
272 (defun set-help-info () 576 (defun set-help-info ()
273 (let ((help '(("para" "A Paragraph") 577 (let ((help '(("para" "A Paragraph")
274 ("q" "A Quotation") 578 ("q" "A Quotation")
275 ("date" "A Date"))) 579 ("date" "A Date")))
276 (dtd (sgml-pstate-dtd sgml-buffer-parse-state))) 580 (dtd (sgml-pstate-dtd sgml-buffer-parse-state)))
277 (loop for h in help do 581 (loop for h in help do
278 (setf (sgml-eltype-appdata (sgml-lookup-eltype (first h) dtd) 582 (setf (sgml-eltype-appdata (sgml-lookup-eltype (first h) dtd)
279 'help-string) 583 'help-string)
280 (second h))))) 584 (second h)))))
281 (add-hook 'sgml-doctype-parsed-hook 'set-help-info) 585 (add-hook 'sgml-doctype-parsed-hook 'set-help-info)
586
282 (defun sgml-help-for-element () 587 (defun sgml-help-for-element ()
283 (interactive) 588 (interactive)
284 (let* ((el (sgml-find-element-of (point))) 589 (let* ((el (sgml-find-element-of (point)))
285 (help (sgml-element-appdata el 'help-string))) 590 (help (sgml-element-appdata el 'help-string)))
286 (and help 591 (and help
287 (message "%s" help)))) 592 (message "%s" help))))
288 593
289 *** sgml-sysid-resolve-functions 594
290 595 ** sgml-sysid-resolve-functions
291 This variable should contain a list of functions. Each function should 596 This variable should contain a list of functions.
292 take one argument, the system identifier of an entity. If the function 597 Each function should take one argument, the system identifier of an entity.
293 can handle that identifier, it should insert the text of the entity 598 If the function can handle that identifier, it should insert the text
294 into the current buffer at point and return t. If the system identifier 599 of the entity into the current buffer at point and return t. If the
295 is not handled the function should return nil. 600 system identifier is not handled the function should return nil.
296 601
297 Example use: Support URLs as system identifiers 602 Example use: Support URLs as system identifiers
298
299 (defun sgml-url-sysid (sysid) 603 (defun sgml-url-sysid (sysid)
300 (cond ((string-match "^\\([a-z]+\\):" sysid) ; looks like url 604 (cond ((string-match "^\\([a-z]+\\):" sysid) ; looks like url
301 (require 'url) 605 (require 'url)
302 (set-buffer (prog1 (current-buffer) 606 (set-buffer (prog1 (current-buffer)
303 (url-retrieve sysid))) 607 (url-retrieve sysid)))
304 (insert-buffer url-working-buffer) 608 (insert-buffer url-working-buffer)
305 t))) 609 t)))
306 (add-hook 'sgml-sysid-resolve-functions 'sgml-url-sysid) 610 (add-hook 'sgml-sysid-resolve-functions 'sgml-url-sysid)
307 611
308 ** New file psgml-api.el 612
309 613 * sgml-set-face Now automatically sets faces for all visible text,
310 This file contain API-functions that are not used by other parts of 614 with a delay of 1s.
311 psgml. Use `(require 'psgml-api)' to use the API functions (psgml-api 615
312 includes the rest of the psgml files). 616 * sgml-exposed-tags
617 The list of tag names that remain visible, despite M-x sgml-hide-tags.
618 Each name is a lowercase string, and start-tags and end-tags must be
619 listed individually.
620
621 `sgml-exposed-tags' is local to each buffer in which it has been set;
622 use `setq-default' to set it to a value that is shared among buffers.
623
313 624
314 Local variables: 625 Local variables:
315 mode: text 626 mode: text
316 mode: outline 627 mode: outline
317 end: 628 end: