|
78
|
1 This is the READ ME file for psgml.el version 1.0 -*- text -*-
|
|
0
|
2
|
|
|
3 PSGML is a major mode for editing SGML documents. It works with
|
|
2
|
4 GNU Emacs 19.19 and later or with XEmacs 19.13.
|
|
0
|
5
|
|
|
6 This distribution should contain the following source files:
|
|
|
7 psgml.el
|
|
|
8 psgml.texi
|
|
|
9 psgml-other.el
|
|
|
10 psgml-lucid.el
|
|
|
11 psgml-edit.el
|
|
|
12 psgml-parse.el
|
|
|
13 psgml-dtd.el
|
|
|
14 psgml-info.el
|
|
|
15 psgml-charent.el
|
|
|
16 psgml-api.texi -- internals documentation
|
|
|
17 psgml-api.el -- Extra functions for the API
|
|
|
18 iso88591.map
|
|
2
|
19 Makefile.in
|
|
0
|
20
|
|
|
21 In addition the distribution contains the formatted versions of the
|
|
|
22 documentation files (psgml.info, ...). But the compiled elisp code is
|
|
|
23 no longer supplied. You will have to byte compile the files before
|
|
2
|
24 PSGML will achieve usable speed.
|
|
0
|
25
|
|
2
|
26 PSGML now comes with autoconf support. See INSTALL for generic
|
|
|
27 instructions. Run
|
|
|
28
|
|
|
29 sh configure
|
|
|
30 make
|
|
0
|
31
|
|
2
|
32 and possibly
|
|
|
33
|
|
|
34 make install
|
|
0
|
35
|
|
2
|
36 If you are using xemacs, you can run give the argument `--with-xemacs'
|
|
|
37 to configure, or use `make xemacs'.
|
|
|
38
|
|
|
39 Instead of using configure you can load the psgml-main.el file and run
|
|
|
40 the command psgml-compile-files. Then you have to set load-path or
|
|
|
41 move the .elc files.
|
|
0
|
42
|
|
|
43 Send bug reports, comments and suggestions to lenst@lysator.liu.se.
|
|
|
44
|
|
78
|
45 New in version 1.0
|
|
|
46
|
|
|
47 * Main changes
|
|
|
48
|
|
|
49 ** Support for general entities
|
|
2
|
50
|
|
78
|
51 ** Support for short reference
|
|
|
52
|
|
|
53 ** Support for catalog files
|
|
|
54
|
|
|
55 ** New mechanism for caching parsed DTD
|
|
2
|
56
|
|
78
|
57 ** Includes commands to list various aspects of the DTD
|
|
|
58
|
|
|
59 * Entity support
|
|
2
|
60
|
|
78
|
61 PSGML will recognize entity references (except in attribute values). If
|
|
|
62 the entity is a general text entity, PSGML will also parse the content
|
|
|
63 of the entity. To support this PSGML has a new entity manager with a
|
|
|
64 new mechanism for looking up entities (see belove).
|
|
2
|
65
|
|
78
|
66 Short references are also supported, for the short reference delimiters
|
|
|
67 from the concrete reference syntax.
|
|
2
|
68
|
|
78
|
69 There are some new and changed commands to complete the entity support:
|
|
|
70
|
|
|
71 ** Command: `sgml-expand-entity-reference'
|
|
2
|
72
|
|
78
|
73 Insert the text of the entity referenced at point.
|
|
|
74
|
|
|
75 ** Command: `sgml-expand-all-shortrefs'
|
|
2
|
76
|
|
78
|
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'
|
|
2
|
85
|
|
78
|
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'.
|
|
2
|
89
|
|
78
|
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.
|
|
2
|
94
|
|
|
95 First the current line is parsed and fontified. If this would mean
|
|
|
96 parsing more than 500 chars, wait 1 second first.
|
|
|
97
|
|
78
|
98 The rest of the buffer is fontified after 6 seconds idle time.
|
|
|
99
|
|
|
100 Fontification can be interrupted by any input event.
|
|
|
101
|
|
|
102 The buffer can be fontified initially if `sgml-auto-activate-dtd' is
|
|
|
103 true.
|
|
|
104
|
|
|
105 * New entity manager
|
|
|
106
|
|
|
107 The new entity manager will handle an entity reference thus:
|
|
|
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.
|
|
70
|
118
|
|
78
|
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.
|
|
70
|
127
|
|
78
|
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.
|
|
70
|
142
|
|
78
|
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.
|
|
70
|
167
|
|
78
|
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.
|
|
70
|
179
|
|
78
|
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
|
|
70
|
192
|
|
|
193 To help debug entity lookup there is a new option
|
|
78
|
194 `sgml-trace-entity-lookup'. If this option is t messages will be logged
|
|
|
195 in *SGML LOG* buffer when external entities are looked up. These
|
|
|
196 messages shows entity, catalogs searched, and entry type in catalog
|
|
|
197 where entity was found.
|
|
70
|
198
|
|
78
|
199 ** Translating between characters and entity references
|
|
70
|
200
|
|
78
|
201 Set the variable `sgml-display-char-list-filename' to a file that
|
|
|
202 contains mappings between all characters present in the presentation
|
|
|
203 character set, and their "standard replacement text" names, e.g. "å" ->
|
|
|
204 "[aring ]", e.t.c. The default value for this variable is
|
|
|
205 `iso88591.map'.
|
|
12
|
206
|
|
78
|
207 Use the functions (also in the Modify menu)
|
|
|
208 `sgml-charent-to-display-char' and `sgml-display-char-to-charent' to
|
|
|
209 translate between entities and characters.
|
|
70
|
210
|
|
78
|
211 ** Handling of missing DOCTYPE
|
|
70
|
212
|
|
78
|
213 If the document prolog does not contain a document type declaration,
|
|
|
214 PSGML will try to supply one on the form `<!DOCTYPE DocTypeName
|
|
|
215 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
|
|
|
217 start tag will be used. I.e., if the document starts with `<book>', a
|
|
|
218 document type declaration `<!DOCTYPE book SYSTEM>' will be assumed.
|
|
12
|
219
|
|
78
|
220 ** Handling of tags for undefined elements
|
|
70
|
221
|
|
78
|
222 *** Start-tags for undefined elements will either be ignored, if
|
|
|
223 `sgml-ignore-undefined-elements' is `t', or assumed to be acceptable in
|
|
|
224 the current element and defined with `O O ANY'.
|
|
12
|
225
|
|
78
|
226 *** An end-tag for an element that is not currently open will be
|
|
|
227 ignored.
|
|
70
|
228
|
|
78
|
229 ** Cleaned up Markup menu
|
|
70
|
230
|
|
78
|
231 The removed entries can be added with sgml-custom-markup:
|
|
12
|
232
|
|
78
|
233 (setq sgml-custom-markup
|
|
|
234 '(("<!entity ... >" "<!entity \r>\n")
|
|
|
235 ("<!attlist ... >" "<!attlist \r>\n")
|
|
|
236 ("<!element ... >" "<!element \r>\n")
|
|
|
237 ("<!doctype ...>" "<!doctype \r -- public or system --\n[\n]>\n")
|
|
|
238 ("Local variables comment" "<!--\nLocal variables:\n\rEnd:\n-->\n")
|
|
|
239 ("Comment" "<!-- \r -->\n") ))
|
|
70
|
240
|
|
78
|
241 ** New commands
|
|
70
|
242
|
|
78
|
243 Thanks to David Megginson the custom menus are now reachable from the
|
|
|
244 keyboard:
|
|
70
|
245
|
|
78
|
246 `C-c C-u C-d' (`sgml-custom-dtd')
|
|
70
|
247
|
|
78
|
248 `C-c C-u C-m' (`sgml-custom-markup')
|
|
70
|
249
|
|
78
|
250 * Changes to API
|
|
12
|
251
|
|
78
|
252 ** New hooks
|
|
|
253
|
|
|
254 *** `sgml-close-element-hook'
|
|
70
|
255
|
|
78
|
256 The hook run by `sgml-close-element'. These functions are invoked with
|
|
|
257 `sgml-current-tree' bound to the element just parsed.
|
|
70
|
258
|
|
78
|
259 *** `sgml-new-attribute-list-function'
|
|
70
|
260
|
|
|
261 This hook is run when a new element is inserted to construct the
|
|
|
262 attribute specification list. The default function prompts for the
|
|
|
263 required attributes.
|
|
|
264
|
|
78
|
265 *** `sgml-doctype-parsed-hook'
|
|
70
|
266
|
|
78
|
267 This hook is called after the doctype has been parsed. It can be used
|
|
|
268 to load any additional information into the DTD structure.
|
|
0
|
269
|
|
|
270 Example: add description to element types
|
|
78
|
271
|
|
0
|
272 (defun set-help-info ()
|
|
|
273 (let ((help '(("para" "A Paragraph")
|
|
|
274 ("q" "A Quotation")
|
|
|
275 ("date" "A Date")))
|
|
|
276 (dtd (sgml-pstate-dtd sgml-buffer-parse-state)))
|
|
|
277 (loop for h in help do
|
|
78
|
278 (setf (sgml-eltype-appdata (sgml-lookup-eltype (first h) dtd)
|
|
0
|
279 'help-string)
|
|
|
280 (second h)))))
|
|
|
281 (add-hook 'sgml-doctype-parsed-hook 'set-help-info)
|
|
|
282 (defun sgml-help-for-element ()
|
|
|
283 (interactive)
|
|
|
284 (let* ((el (sgml-find-element-of (point)))
|
|
|
285 (help (sgml-element-appdata el 'help-string)))
|
|
|
286 (and help
|
|
|
287 (message "%s" help))))
|
|
|
288
|
|
78
|
289 *** sgml-sysid-resolve-functions
|
|
0
|
290
|
|
78
|
291 This variable should contain a list of functions. Each function should
|
|
|
292 take one argument, the system identifier of an entity. If the function
|
|
|
293 can handle that identifier, it should insert the text of the entity
|
|
|
294 into the current buffer at point and return t. If the system identifier
|
|
|
295 is not handled the function should return nil.
|
|
0
|
296
|
|
78
|
297 Example use: Support URLs as system identifiers
|
|
|
298
|
|
0
|
299 (defun sgml-url-sysid (sysid)
|
|
|
300 (cond ((string-match "^\\([a-z]+\\):" sysid) ; looks like url
|
|
|
301 (require 'url)
|
|
|
302 (set-buffer (prog1 (current-buffer)
|
|
|
303 (url-retrieve sysid)))
|
|
|
304 (insert-buffer url-working-buffer)
|
|
|
305 t)))
|
|
|
306 (add-hook 'sgml-sysid-resolve-functions 'sgml-url-sysid)
|
|
|
307
|
|
78
|
308 ** New file psgml-api.el
|
|
0
|
309
|
|
78
|
310 This file contain API-functions that are not used by other parts of
|
|
|
311 psgml. Use `(require 'psgml-api)' to use the API functions (psgml-api
|
|
|
312 includes the rest of the psgml files).
|
|
2
|
313
|
|
|
314 Local variables:
|
|
|
315 mode: text
|
|
|
316 mode: outline
|
|
|
317 end:
|
