Mercurial > hg > xemacs-beta

comparison lisp/psgml/README.psgml @ 12:bcdc7deadc19 r19-15b7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r19-15b7
author cvs
date Mon, 13 Aug 2007 08:48:16 +0200
parents ac2d302a0011
children 131b0175ea99
comparison
equal deleted inserted replaced
11:91ffe8bd52e4 12:bcdc7deadc19
1 This is the READ ME file for psgml.el version 1a12. -*- text -*- 1 This is the READ ME file for psgml.el version 1.0 -*- 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
17 psgml-api.texi -- internals documentation 16 psgml-api.texi -- internals documentation
18 psgml-api.el -- Extra functions for the API 17 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
22 iso88591.map 18 iso88591.map
23 Makefile.in 19 Makefile.in
24 20
25 In addition the distribution contains the formatted versions of the 21 In addition the distribution contains the formatted versions of the
26 documentation files (psgml.info, ...). But the compiled elisp code is 22 documentation files (psgml.info, ...). But the compiled elisp code is
44 the command psgml-compile-files. Then you have to set load-path or 40 the command psgml-compile-files. Then you have to set load-path or
45 move the .elc files. 41 move the .elc files.
46 42
47 Send bug reports, comments and suggestions to lenst@lysator.liu.se. 43 Send bug reports, comments and suggestions to lenst@lysator.liu.se.
48 44
49 New in version 1.0a12 45 New in version 1.0
50 46
51 See ChangeLog... 47 * Main changes
52 48
53 49 ** Support for general entities
54 New in version 1.0a11 50
55 51 ** Support for short reference
56 * Autoconf support 52
57 53 ** Support for catalog files
58 Tanks to Karl Eichwalder. 54
59 55 ** New mechanism for caching parsed DTD
60 * Bugs fixed 56
61 57 ** Includes commands to list various aspects of the DTD
62 ** after-change-function lost if text entity referenced 58
63 59 * Entity support
64 ** Mouse button 3, has wrong binding in XEmacs. 60
65 61 PSGML will recognize entity references (except in attribute values). If
66 62 the entity is a general text entity, PSGML will also parse the content
67 New in version 1.0a10 63 of the entity. To support this PSGML has a new entity manager with a
68 64 new mechanism for looking up entities (see belove).
69 * Changed how fontification is done 65
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.
70 94
71 First the current line is parsed and fontified. If this would mean 95 First the current line is parsed and fontified. If this would mean
72 parsing more than 500 chars, wait 1 second first. 96 parsing more than 500 chars, wait 1 second first.
73 97
74 Wait 6 seconds and then fontify rest of buffer. 98 The rest of the buffer is fontified after 6 seconds idle time.
75 99
76 These waits and the parsing can be interrupted by any input event. 100 Fontification can be interrupted by any input event.
77 101
78 This seems to work well with Emacs 19.29 and XEmacs 19.13 on Linux. 102 The buffer can be fontified initially if `sgml-auto-activate-dtd' is
79 103 true.
80 * XEmacs menus made with easy-menu 104
81 105 * New entity manager
82 Now there is only one set of menu for both Emacs and XEmacs. 106
83 107 The new entity manager will handle an entity reference thus:
84 * Tracing catalog lookup 108
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
85 192
86 To help debug entity lookup there is a new option 193 To help debug entity lookup there is a new option
87 `sgml-trace-entity-lookup'. If this option is t messages will be 194 `sgml-trace-entity-lookup'. If this option is t messages will be logged
88 logged in *SGML LOG* buffer when external entities are looked up. 195 in *SGML LOG* buffer when external entities are looked up. These
89 These messages shows entity, catalogs searched, and entry type in 196 messages shows entity, catalogs searched, and entry type in catalog
90 catalog where entity was found. 197 where entity was found.
91 198
92 199 ** Translating between characters and entity references
93 200
94 * Renamed default style sheet for fs.el 201 Set the variable `sgml-display-char-list-filename' to a file that
95 202 contains mappings between all characters present in the presentation
96 The default style sheet used by fs.el, style sheet formatter example 203 character set, and their "standard replacement text" names, e.g. "å" ->
97 is now "style.fs". 204 "[aring ]", e.t.c. The default value for this variable is
98 205 `iso88591.map'.
99 206
100 New in version 1.0a9 207 Use the functions (also in the Modify menu)
101 208 `sgml-charent-to-display-char' and `sgml-display-char-to-charent' to
102 * XEmacs may have problem if sgml-set-face is t 209 translate between entities and characters.
103 210
104 I tried with the latest version on a sun4 Solaris 2 machine and PSGML 211 ** Handling of missing DOCTYPE
105 would always parse to the end of the buffer even if I typed something. 212
106 There seem to be a problem with the input-pending-p function. I don't 213 If the document prolog does not contain a document type declaration,
107 know if this is specific for Solaris. Emacs on Solaris has problems 214 PSGML will try to supply one on the form `<!DOCTYPE DocTypeName
108 with signal handling. 215 SYSTEM>' If the variable `sgml-default-doctype-name' is defined this
109 216 will be used for the document type name, otherwise the GI of the first
110 217 start tag will be used. I.e., if the document starts with `<book>', a
111 * New options for insert-element 218 document type declaration `<!DOCTYPE book SYSTEM>' will be assumed.
112 ** sgml-insert-missing-element-comment 219
113 ** sgml-insert-end-tag-on-new-line 220 ** Handling of tags for undefined elements
114 221
115 * psgml-api: 222 *** Start-tags for undefined elements will either be ignored, if
116 ** sgml-map-content: new optional argument. If the argument ENTITY-FUN 223 `sgml-ignore-undefined-elements' is `t', or assumed to be acceptable in
117 is specified it should be a function with one argument. The function 224 the current element and defined with `O O ANY'.
118 will be called for data entity references instead of the entity text 225
119 being passed to the DATA-FUN. The argument is the entity referenced. 226 *** An end-tag for an element that is not currently open will be
120 Use `sgml-entity-name', `sgml-entity-type' etc. 227 ignored.
121 228
122 229 ** Cleaned up Markup menu
123 Version 1.0a8 has only bug-fixes. 230
124 231 The removed entries can be added with sgml-custom-markup:
125 232
126 New in version 1.0a7 233 (setq sgml-custom-markup
127 234 '(("<!entity ... >" "<!entity \r>\n")
128 * Better CATALOG parsing 235 ("<!attlist ... >" "<!attlist \r>\n")
129 236 ("<!element ... >" "<!element \r>\n")
130 ** Will handle SGMLDECL, etc.. 237 ("<!doctype ...>" "<!doctype \r -- public or system --\n[\n]>\n")
131 238 ("Local variables comment" "<!--\nLocal variables:\n\rEnd:\n-->\n")
132 ** New option: sgml-system-identifiers-are-preferred 239 ("Comment" "<!-- \r -->\n") ))
133 If nil PSGML will look up external entities by searching the catalogs 240
134 in `sgml-local-catalogs' and `sgml-catalog-files' and only if the entity 241 ** New commands
135 is not found in will a given system identifier be used. If the variable 242
136 is non-nil and a system identifier is given, the system identifier will 243 Thanks to David Megginson the custom menus are now reachable from the
137 be used for the entity. If no system identifier is given the catalogs 244 keyboard:
138 will searched. 245
139 246 `C-c C-u C-d' (`sgml-custom-dtd')
140 * File names for external entities (e.g system identifiers) are 247
141 relative to the directory containing the file declaring of the entity. 248 `C-c C-u C-m' (`sgml-custom-markup')
142 249
143 * Changes to how the DTD is found 250 * Changes to API
144 251
145 ** If the variable sgml-doctype is set, it should be the name of a file 252 ** New hooks
146 containing the DOCTYPE declaration to use. 253
147 254 *** `sgml-close-element-hook'
148 ** The variable sgml-parent-document is used when the current file 255
149 is part of a bigger document, and the variable describes how the 256 The hook run by `sgml-close-element'. These functions are invoked with
150 current files content fits into the element hierarchy. The variable 257 `sgml-current-tree' bound to the element just parsed.
151 should have the form 258
152 259 *** `sgml-new-attribute-list-function'
153 (parent-file context-element* top-element (has-seen-element*)?) 260
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 261 This hook is run when a new element is inserted to construct the
185 attribute specification list. The default function prompts for the 262 attribute specification list. The default function prompts for the
186 required attributes. 263 required attributes.
187 264
188 265 *** `sgml-doctype-parsed-hook'
189 * API 266
190 267 This hook is called after the doctype has been parsed. It can be used
191 ** New file psgml-api.el 268 to load any additional information into the DTD structure.
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
283
284 ** Translating between characters and entity references
285
286 Set the variable `sgml-display-char-list-filename' to a file file that
287 contains mappings between all characters present in the presentation
288 character set, and their "standard replacement text" names, e.g. "å"
289 -> "[aring ]", e.t.c.
290
291 The default value for this variable is `iso88591.map'.
292
293 The use the functions (also in the Modify menu)
294
295 sgml-charent-to-display-char
296 sgml-display-char-to-charent
297
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,
312 PSGML will try to supply one on the form `<!DOCTYPE DocTypeName
313 SYSTEM>' If the variable `sgml-default-doctype-name' is defined this
314 will be used for the document type name, otherwise the GI of the first
315 start tag will be used. I.e., if the document starts with `<book>', a
316 document type declaration `<!DOCTYPE book SYSTEM>' will be assumed.
317
318
319 * Compiled DTDs are now associated with external `Document Type
320 Declaration Subset' entities. You will have to create a catalog with
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
420 the current element and defined with `O O ANY'.
421
422 ** An end-tag for an element that is not currently open will be ignored.
423
424
425 * I have (as an experiment) turned off all warnings. Warnings are only
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
451 The removed entries can be added with sgml-custom-markup:
452
453 (setq sgml-custom-markup
454 '(
455 ("<!entity ... >" "<!entity \r>\n")
456 ("<!attlist ... >" "<!attlist \r>\n")
457 ("<!element ... >" "<!element \r>\n")
458 ("<!doctype ...>" "<!doctype \r -- public or system --\n[\n]>\n")
459 ("Local variables comment" "<!--\nLocal variables:\n\rEnd:\n-->\n")
460 ("Comment" "<!-- \r -->\n")
461 ))
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
519 Thanks to David Megginson the custom menus are now reachable from the
520 keyboard:
521 ** C-c C-u C-d (sgml-custom-dtd)
522 ** C-c C-u C-m (sgml-custom-markup)
523
524 * New command: sgml-expand-entity-reference
525 Insert the text of the entity referenced at point.
526
527 * sgml-validate-command is now a format string
528
529
530 News in version 1.0 a1
531
532 * A lot of internal changes
533
534 * Support for general entities
535
536 * New entity manager
537
538 The new entity manager will handle an entity thus:
539
540 1. If the entity has a system identifier, the entity manager will
541 first try and call the functions on sgml-sysid-resolve-functions
542 with the system identifier as argument, and if any function returns
543 non-nil assume that the function has handled the entity.
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.
574 269
575 Example: add description to element types 270 Example: add description to element types
271
576 (defun set-help-info () 272 (defun set-help-info ()
577 (let ((help '(("para" "A Paragraph") 273 (let ((help '(("para" "A Paragraph")
578 ("q" "A Quotation") 274 ("q" "A Quotation")
579 ("date" "A Date"))) 275 ("date" "A Date")))
580 (dtd (sgml-pstate-dtd sgml-buffer-parse-state))) 276 (dtd (sgml-pstate-dtd sgml-buffer-parse-state)))
581 (loop for h in help do 277 (loop for h in help do
582 (setf (sgml-eltype-appdata (sgml-lookup-eltype (first h) dtd) 278 (setf (sgml-eltype-appdata (sgml-lookup-eltype (first h) dtd)
583 'help-string) 279 'help-string)
584 (second h))))) 280 (second h)))))
585 (add-hook 'sgml-doctype-parsed-hook 'set-help-info) 281 (add-hook 'sgml-doctype-parsed-hook 'set-help-info)
586
587 (defun sgml-help-for-element () 282 (defun sgml-help-for-element ()
588 (interactive) 283 (interactive)
589 (let* ((el (sgml-find-element-of (point))) 284 (let* ((el (sgml-find-element-of (point)))
590 (help (sgml-element-appdata el 'help-string))) 285 (help (sgml-element-appdata el 'help-string)))
591 (and help 286 (and help
592 (message "%s" help)))) 287 (message "%s" help))))
593 288
594 289 *** sgml-sysid-resolve-functions
595 ** sgml-sysid-resolve-functions 290
596 This variable should contain a list of functions. 291 This variable should contain a list of functions. Each function should
597 Each function should take one argument, the system identifier of an entity. 292 take one argument, the system identifier of an entity. If the function
598 If the function can handle that identifier, it should insert the text 293 can handle that identifier, it should insert the text of the entity
599 of the entity into the current buffer at point and return t. If the 294 into the current buffer at point and return t. If the system identifier
600 system identifier is not handled the function should return nil. 295 is not handled the function should return nil.
601 296
602 Example use: Support URLs as system identifiers 297 Example use: Support URLs as system identifiers
298
603 (defun sgml-url-sysid (sysid) 299 (defun sgml-url-sysid (sysid)
604 (cond ((string-match "^\\([a-z]+\\):" sysid) ; looks like url 300 (cond ((string-match "^\\([a-z]+\\):" sysid) ; looks like url
605 (require 'url) 301 (require 'url)
606 (set-buffer (prog1 (current-buffer) 302 (set-buffer (prog1 (current-buffer)
607 (url-retrieve sysid))) 303 (url-retrieve sysid)))
608 (insert-buffer url-working-buffer) 304 (insert-buffer url-working-buffer)
609 t))) 305 t)))
610 (add-hook 'sgml-sysid-resolve-functions 'sgml-url-sysid) 306 (add-hook 'sgml-sysid-resolve-functions 'sgml-url-sysid)
611 307
612 308 ** New file psgml-api.el
613 * sgml-set-face Now automatically sets faces for all visible text, 309
614 with a delay of 1s. 310 This file contain API-functions that are not used by other parts of
615 311 psgml. Use `(require 'psgml-api)' to use the API functions (psgml-api
616 * sgml-exposed-tags 312 includes the rest of the psgml files).
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
624 313
625 Local variables: 314 Local variables:
626 mode: text 315 mode: text
627 mode: outline 316 mode: outline
628 end: 317 end: