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: