1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317
|
This is the READ ME file for psgml.el version 1.0. -*- text -*-
PSGML is a major mode for editing SGML documents. It works with
GNU Emacs 19.19 and later or with XEmacs 19.13.
This distribution should contain the following source files:
psgml.el
psgml.texi
psgml-other.el
psgml-lucid.el
psgml-edit.el
psgml-parse.el
psgml-dtd.el
psgml-info.el
psgml-charent.el
psgml-api.texi -- internals documentation
psgml-api.el -- Extra functions for the API
iso88591.map
Makefile.in
In addition the distribution contains the formatted versions of the
documentation files (psgml.info, ...). But the compiled elisp code is
no longer supplied. You will have to byte compile the files before
PSGML will achieve usable speed.
PSGML now comes with autoconf support. See INSTALL for generic
instructions. Run
sh configure
make
and possibly
make install
If you are using xemacs, you can run give the argument `--with-xemacs'
to configure, or use `make xemacs'.
Instead of using configure you can load the psgml-main.el file and run
the command psgml-compile-files. Then you have to set load-path or
move the .elc files.
Send bug reports, comments and suggestions to lenst@lysator.liu.se.
New in version 1.0
* Main changes
** Support for general entities
** Support for short reference
** Support for catalog files
** New mechanism for caching parsed DTD
** Includes commands to list various aspects of the DTD
* Entity support
PSGML will recognize entity references (except in attribute values). If
the entity is a general text entity, PSGML will also parse the content
of the entity. To support this PSGML has a new entity manager with a
new mechanism for looking up entities (see belove).
Short references are also supported, for the short reference delimiters
from the concrete reference syntax.
There are some new and changed commands to complete the entity support:
** Command: `sgml-expand-entity-reference'
Insert the text of the entity referenced at point.
** Command: `sgml-expand-all-shortrefs'
Expand all short references in the buffer. Short references to text
entities are expanded to the replacement text of the entity, other
short references are expanded into general entity references. If
argument, `to-entity', is non-nil, or if called interactive with
numeric prefix argument, all short references are replaced by generally
entity references.
** Command: `sgml-normalize'
Changed to expand short references also. Normalize buffer by filling in
omitted tags and expanding empty tags. Argument `to-entity' controls
how short references are expanded as with `sgml-expand-all-shortrefs'.
* Fontification
If `sgml-set-face' is true and the DTD has been activated, PSGML will
automatically set the face of markup in the buffer.
First the current line is parsed and fontified. If this would mean
parsing more than 500 chars, wait 1 second first.
The rest of the buffer is fontified after 6 seconds idle time.
Fontification can be interrupted by any input event.
The buffer can be fontified initially if `sgml-auto-activate-dtd' is
true.
* New entity manager
The new entity manager will handle an entity reference thus:
** If the entity has a system identifier, the entity manager will first
try and call the functions on `sgml-sysid-resolve-functions' with the
system identifier as argument, and if any function returns non-nil
assume that the function has handled the entity.
** If the entity has a system identifier and
`sgml-system-identifiers-are-preferred' is non-nil, the system
identifier will be used as a file name relative to the file containing
the entity declaration.
** Next the entity manager will try the catalog, and
** if not found there use the `sgml-public-map'.
** Finally if the entity has not been found and it has a system
identifier, this will be used as a file name.
Note: `sgml-system-path' is no longer used for entity lookup.
The catalog files searched is given by the variable
`sgml-local-catalogs' and `sgml-catalog-files'. The
`sgml-catalog-files' variable is initialized from the environment
variable `SGML_CATALOG_FILES' (should be a colon separated list of
files). The `sgml-local-catalogs' variable is assumed to be set in a
files local variables.
File names for external entities (e.g system identifiers) are relative
to the directory containing the file declaring the entity.
The `sgml-public-map' is initialized from the environment variable
`SGML_PATH'.
`sgml-system-path' defaults to nil.
Supports most of sgmls substitutions for sgml-public-map. Supported:
%%, %N, %P, %S, %Y, %C, %L, %O, %T, %V. Unsupported: %D, %X, %A, %E,
%I, %R, %U. Note: that %D is and alias for %C in PSGML (historical
accident).
* New and changed options
** `sgml-recompile-out-of-date-cdtd'
** New options for insert-element:
`sgml-insert-missing-element-comment' and
`sgml-insert-end-tag-on-new-line'.
** `sgml-validate-files' and slight change of `sgml-validate-command'
The variable `sgml-validate-command' can now be a list of strings. The
strings can contain %-sequences that will be expanded: %b to buffer
file name, %s to SGML Declaration file, either the value of
sgml-declaration variable or SGML Declaration file for parent document
or DOCTYPE file or SGMLDECL from catalog. %d value of `sgml-doctype'.
** `sgml-set-face'
Now automatically sets faces for all visible text, with a delay of 1s.
** `sgml-exposed-tags'
The list of tag names that remain visible, despite `M-x
sgml-hide-tags'. Each name is a lowercase string, and start-tags and
end-tags must be listed individually.
** `sgml-auto-activate-dtd'
PSGML was behaving inconsistent when a new file was loaded. If the
variable `sgml-set-face' was true the DTD would automatically be
activated (loaded or parsed), but only if psgml-parse already loaded.
Rather than let `sgml-set-face' decide if the DTD is activated, there
is now a distinct option for this. This option works even the first
time.
If non-nil, loading a sgml-file will automatically try to activate its
DTD. Activation means either to parse the document type declaration or
to load a previously saved parsed DTD. The name of the activated DTD
will be shown in the mode line.
* Various
** Tracing catalog lookup
To help debug entity lookup there is a new option
`sgml-trace-entity-lookup'. If this option is t messages will be logged
in *SGML LOG* buffer when external entities are looked up. These
messages shows entity, catalogs searched, and entry type in catalog
where entity was found.
** Translating between characters and entity references
Set the variable `sgml-display-char-list-filename' to a file that
contains mappings between all characters present in the presentation
character set, and their "standard replacement text" names, e.g. "" ->
"[aring ]", e.t.c. The default value for this variable is
`iso88591.map'.
Use the functions (also in the Modify menu)
`sgml-charent-to-display-char' and `sgml-display-char-to-charent' to
translate between entities and characters.
** Handling of missing DOCTYPE
If the document prolog does not contain a document type declaration,
PSGML will try to supply one on the form `<!DOCTYPE DocTypeName
SYSTEM>' If the variable `sgml-default-doctype-name' is defined this
will be used for the document type name, otherwise the GI of the first
start tag will be used. I.e., if the document starts with `<book>', a
document type declaration `<!DOCTYPE book SYSTEM>' will be assumed.
** Handling of tags for undefined elements
*** Start-tags for undefined elements will either be ignored, if
`sgml-ignore-undefined-elements' is `t', or assumed to be acceptable in
the current element and defined with `O O ANY'.
*** An end-tag for an element that is not currently open will be
ignored.
** Cleaned up Markup menu
The removed entries can be added with sgml-custom-markup:
(setq sgml-custom-markup
'(("<!entity ... >" "<!entity \r>\n")
("<!attlist ... >" "<!attlist \r>\n")
("<!element ... >" "<!element \r>\n")
("<!doctype ...>" "<!doctype \r -- public or system --\n[\n]>\n")
("Local variables comment" "<!--\nLocal variables:\n\rEnd:\n-->\n")
("Comment" "<!-- \r -->\n") ))
** New commands
Thanks to David Megginson the custom menus are now reachable from the
keyboard:
`C-c C-u C-d' (`sgml-custom-dtd')
`C-c C-u C-m' (`sgml-custom-markup')
* Changes to API
** New hooks
*** `sgml-close-element-hook'
The hook run by `sgml-close-element'. These functions are invoked with
`sgml-current-tree' bound to the element just parsed.
*** `sgml-new-attribute-list-function'
This hook is run when a new element is inserted to construct the
attribute specification list. The default function prompts for the
required attributes.
*** `sgml-doctype-parsed-hook'
This hook is called after the doctype has been parsed. It can be used
to load any additional information into the DTD structure.
Example: add description to element types
(defun set-help-info ()
(let ((help '(("para" "A Paragraph")
("q" "A Quotation")
("date" "A Date")))
(dtd (sgml-pstate-dtd sgml-buffer-parse-state)))
(loop for h in help do
(setf (sgml-eltype-appdata (sgml-lookup-eltype (first h) dtd)
'help-string)
(second h)))))
(add-hook 'sgml-doctype-parsed-hook 'set-help-info)
(defun sgml-help-for-element ()
(interactive)
(let* ((el (sgml-find-element-of (point)))
(help (sgml-element-appdata el 'help-string)))
(and help
(message "%s" help))))
*** sgml-sysid-resolve-functions
This variable should contain a list of functions. Each function should
take one argument, the system identifier of an entity. If the function
can handle that identifier, it should insert the text of the entity
into the current buffer at point and return t. If the system identifier
is not handled the function should return nil.
Example use: Support URLs as system identifiers
(defun sgml-url-sysid (sysid)
(cond ((string-match "^\\([a-z]+\\):" sysid) ; looks like url
(require 'url)
(set-buffer (prog1 (current-buffer)
(url-retrieve sysid)))
(insert-buffer url-working-buffer)
t)))
(add-hook 'sgml-sysid-resolve-functions 'sgml-url-sysid)
** New file psgml-api.el
This file contain API-functions that are not used by other parts of
psgml. Use `(require 'psgml-api)' to use the API functions (psgml-api
includes the rest of the psgml files).
Local variables:
mode: text
mode: outline
end:
|