This is the READ ME file for psgml.el version 1a9.       -*- text -*-

   PSGML is a major mode for editing SGML documents.  It works with
GNU Emacs 19.19 and later or with Lucid Emacs 19.9.

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-debug.el	-- some functions used in development
	psgml-api.texi	-- internals documentation
	psgml-api.el	-- Extra functions for the API
	fs.el		-- Example use of psgml to format a SGML file
	style.el	-- example style file for fs.el
	catalog.sgml	-- example SGML-file for fs.el and style.el
	iso88591.map

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 achive usable speed.

If you are not using Lucid Emacs or XEmacs you should compile:
	psgml.el
	psgml-other.el
	psgml-edit.el
	psgml-parse.el
	psgml-dtd.el
	psgml-info.el
        psgml-charent.el

If you on the other hand are using Lucid Emacs or XEmacs you should
compile
	psgml.el
	psgml-lucid.el
	psgml-edit.el
	psgml-parse.el
	psgml-dtd.el
	psgml-info.el
        psgml-charent.el

Additionally the following can be compiled, they are not normaly used
by PSGML:
	psgml-api.el	-- Extra functions for the API
	fs.el		-- Example use of psgml to format a SGML file
	psgml-debug.el	-- some functions used in development

Send bug reports, comments and suggestions to lenst@lysator.liu.se.

New in version 1.0a9

* XEmacs may have problem if sgml-set-face is t

I tried with the latest version on a sun4 Solaris 2 machine and PSGML
would always parse to the end of the buffer even if I typed something.
There seem to be a problem with the input-pending-p function. I don't
know if this is specific fo Solaris. Emacs on Solaris has problems
with signal handling.


* New options for insert-element
** sgml-insert-missing-element-comment
** sgml-insert-end-tag-on-new-line

* psgml-api:
** sgml-map-content: new optional argument. If the argument ENTITY-FUN
is specified it should be a function with one argument. The function
will be called for data entity references instead of the entity text
beeing passed to the DATA-FUN. The argument is the entity referenced.
Use `sgml-entity-name', `sgml-entity-type' etc.


Version 1.0a8 has only bugfixes.


New in version 1.0a7

* Better CATALOG parsing

** Will handle SGMLDECL, etc..

** New option: sgml-system-identifiers-are-preferred
If nil PSGML will look up external entities by searching the catalogs
in `sgml-local-catalogs' and `sgml-catalog-files'  and only if the entity
is not found in will a given system identifer be used.  If the variable
is non-nil and a system identifer is given, the system identifier will
be used for the entity. If no system identifier is given the catalogs
will searched.

* File names for external entities (e.g system identifiers) are
relative to the directory containing the file declaring of the entity.

* Changes to how the DTD is found

** If the variable sgml-doctype is set, it should be the name of a file
containing the DOCTYPE declaration to use.

** The variable sgml-parent-document is used when the current file
is part of a bigger document, and the variable describes how the
current files content fits into the element hierarchy. The variable
should have the form

  (parent-file context-element* top-element (has-seen-element*)?)

*** parent-file (string) is the name of the file contatining the
document entity.

*** context-element (string) is used to set up exceptions and short
reference map. Good candidates for these elements are the elements
open when the entity pointing to the current file is used.

*** top-element (string) is the top level element in the current file.
The file should contain one instance of this element, unless the last
(lisp) element of sgml-parent-document is a list. If it is a list, the
top level of the file should follow the content model of top-element.

*** has-seen-element (string) element satisfied in the content model
of top-element.


* sgml-validate
  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.


* Hooks

** 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.


* API

** 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).

The new functions in psgml-api is two functions to travers the element
structure.

*** (sgml-map-content element element-function data-function pi-function)

Call element-function with every child of element.
Call data-function with all the data in element.
Don't modify the buffer in these functions.
	
*** (sgml-map-element-modify function element)

Call function on every sub element of element, allows the function to
modify the buffer (e.g. add/modify attributes of the elements).

** Example of API use: fs.el -- a simple style sheet driven formatter.

Try fs.el with the catalog.sgml file.  The style.el is the style sheet
for catalog.sgml.  The command to format current buffer is
`M-x style-format'.


New in version 1.0 a6

* Entity manager

** Use system id as file name, if there is no %S in sgml-public-map.

** Finds PUBLIC entries before DOCTYPE and ENTITY in catalog files.

* Better error recovery for out of context data and tags

* New command: sgml-general-dtd-info

* Disables auto-fill in the prolog

* Insert element leaves point at the end of the element,
it used to leave point at the beginning of the element.

* sgml-hide-tags/attributes is better at handling minimized tags

* New options
** sgml-validate-files and slight change of sgml-validate-command.
** sgml-recompile-out-of-date-cdtd

* Now saving attribute specification list in parse tree
Faster sgml-element-attval, but more memory used.

* Long menus that are split into submenus now show the range of
choices in the different submenus.

The option `sgml-range-indicator-max-length' determines how many
characters from the first and the last choice to show.

* Private abbrev table


New in version 1.0 a5

* New menu structure
Perhaps there is to many top-level menus now. Any suggestions how to
organize the menus?

* Some new functions

** Information from the DTD (used to be nefarious.el)

*** sgml-describe-element-type

*** sgml-describe-entity

*** sgml-list-elements
 Will list all elements and the attributes declared for the element.

*** sgml-list-attributes
  Will list all attributes declared and the elements that use them.

*** sgml-list-terminals
  Will list all elements that can contain data.

*** sgml-list-occur-in-elements
  Will list all element types and where it can occur.

*** sgml-list-content-elements
  Will list all element types and the element types that can occur
  in its content.


** Translating between characters and entity references

Set the variable `sgml-display-char-list-filename' to a file 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'. 

The use the functions (also in the Modify menu)

  sgml-charent-to-display-char
  sgml-display-char-to-charent

to translate between entities and characters.



* Two major bugs fixed
** DTD using undeclared elements was improperly saved
** Bug in using a precompiled DTD and local element, attlist or usemap
declaration.



New in version 1.0 a4

* 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.


* Compiled DTDs are now associated with external `Document Type
Declaration Subset' entitys.  You will have to create a catalog with
entries for all the DTDs that should be compiled.  This should make
it, in most cases, unnecessary to make saved dtds or to set the
`sgml-default-dtd-file', at the expense of having to maintain the
catalog file.

** Options

`sgml-ecat-files'  List of compiled dtd catalog files.
	Default: ("ECAT" "~/sgml/ECAT" "/usr/local/lib/sgml/ECAT")

`sgml-local-ecat-files'  This can be set as a buffer local variable to
a list of catalogs to be searched before `sgml-ecat-files'.

** Catalog format

The catalog is similar to the catalog used to resolve public
identifiers.  There are two types of entries:

	PUBLIC pubid pents? cfile
and
	FILE file pents? cfile

where pubid is a public identifier (as a minimum literal), pents is a
optional list of parameter entities and values, file is the file name
of a DTD file and cfile is the name of the complied DTD. The syntax
for pents is 

	`[' (name literal)* `]'

Example:

PUBLIC 	"-//lenst//dtd My DTD//en"	cdtd/bar
FILE	"bar.dtd"			cdtd/bar

To better handle DTDs with options, like TEI and HTML 2.0/+ it is
possible to have several entries for the same DTD with different
parameter entity settings.  The parameters are listed between `[' and
`]' before the file name of the compiled dtd.

FILE 	"~/sgml/htmlplus.dtd"
	[ HTML.emph "INCLUDE" ] "~/sgml/htmlplus.ced"

PUBLIC "-//Text Encoding Initiative//DTD
	P3 3.6.1:  Main TEI document type declaration//EN"
	[ TEI.prose 'INCLUDE'  TEI.analysis 'INCLUDE' ] "tei2an.cdtd"

PUBLIC "-//Text Encoding Initiative//DTD
	  P3 3.6.1:  Main TEI document type declaration//EN"
	[ TEI.prose 'INCLUDE'  TEI.verse 'INCLUDE' ] "tei2verse.cdtd"

The entries will be searched in order and the first matching will be
used.  Put more specific entries before less specific.  Matching is
done by matching pubid or file and checking that all the listed
parameters are defined with the listed values.



** Example: setting up for editing HTML

If you have the files for the html.dtd in ~/sgml. 
Put in ~/sgml/CATALOG:
    PUBLIC	"-//IETF//DTD HTML//EN"  			html.dtd
    PUBLIC 	"-//IETF//DTD HTML//EN//2.0"  			html.dtd
    PUBLIC	"-//IETF//DTD HTML Level 1//EN//2.0"		html-1.dtd
    PUBLIC	"-//IETF//ENTITIES Added Latin 1 for HTML//EN"	ISOlat1.sgml
    DOCTYPE	HTML						html.dtd

Put in ~/sgml/ECAT:
    FILE html.dtd	[ HTML.Recommended "INCLUDE" ]	cdtd/html-r
    FILE html.dtd					cdtd/html

Put ~/sgml/CATALOG in sgml-catalog-files and ~/sgml/ECAT in
sgml-ecat-files.

Now it should be possible to edit html files if you put them in
sgml-mode.  The file must either start with a proper DOCTYPE or with a
<html> tag.  To be abel to start with empty files and to edit files
not starting with <html> you can create a html-mode that sets the
default document type name:

(defun html-mode ()
  (interactive)
  (sgml-mode)
  (make-local-variable 'sgml-declaration)
  (make-local-variable 'sgml-default-doctype-name)
  (setq sgml-declaration             "~/sgml/html.decl"
	sgml-default-doctype-name    "html"
	sgml-always-quote-attributes t 
	sgml-indent-step             2
	sgml-indent-data	     t
	sgml-minimize-attributes     nil
	sgml-omittag                 t
	sgml-shortag                 t  ))


* 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 acceptabled in
the current element and defined with `O O ANY'.

** An end-tag for an element that is not currently open will be ignored.


* I have (as an experiment) turned off all warnings. Warnings are only
given if the sgml-next-trouble-spot is used or while parsing the DTD.


* Entity manager

** sgml-system-path is no longer used for entity lookup

** PSGML will recognize that a catalog file has been changed


News in version 1.0 a3

* Change in user options

** sgml-live-element-indicator no longer buffer local

** sgml-save-options only saves:
  (sgml-parent-document sgml-omittag sgml-shorttag
   sgml-minimize-attributes sgml-always-quote-attributes sgml-indent-step
   sgml-indent-data sgml-default-dtd-file sgml-exposed-tags) 
 and saves all of them, even if they have no buffer local value

** Options menu split in to two menus

* 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")
	))


* Some bug fixes
Including new default for sgml-catalog-files is
"CATALOG" and "/usr/local/lib/sgml/CATALOG".

* Some tuning


News in version 1.0 a2

* Support for short references

** 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 generaly entity
references.

** sgml-normalize: 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'.  


* Variable: 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.


* face setting 
If `sgml-set-face' is true and the DTD has been activated, PSGML will
automatically set the face of markup in the buffer.  This is done by
parsing, with error messages turned off, as much as possible after
every command.  The parsing is interrupted by input and is almost
transparent.

* Local catalog files
Variabel `sgml-local-catalogs'
A list of SGML entity catalogs to be searched first when parsing the buffer.
This is used in addtion to `sgml-catalog-files',  and `sgml-public-map'.
This variable is automatically local to the buffer.

* New commands
Thanks to David Megginson the custom menus are now reacable from the
keyboard:
** C-c C-u C-d  (sgml-custom-dtd)
** C-c C-u C-m  (sgml-custom-markup)

* New command: sgml-expand-entity-reference
Insert the text of the entity referenced at point.

* sgml-validate-command is now a format string


News in version 1.0 a1

* A lot of internal changes

* Support for general entities

* New entity manager

The new entity manager will handle an entity thus:

1. 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.
2. Next the entity manager will try the catalogue, and 
3. if not found there use the sgml-public-map.

The catalogue files searched is given by the variable
sgml-catalog-files (I suppose it would be confusing to call it
sgml-catalogue-files.)  This variable is initialised from the
environment variable SGML_CATALOG_FILES (should be a colon separated
list of files).

The sgml-public-map is initialised 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).


* 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-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)


* 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-exposed-tags' is local to each buffer in which it has been set;
use `setq-default' to set it to a value that is shared among buffers.