|
0
|
1 \input texinfo @c -*-texinfo-*-
|
|
|
2 @c %**start of header
|
|
|
3 @setfilename psgml-api.info
|
|
|
4 @settitle psgml-api
|
|
|
5 @c @setchapternewpage odd
|
|
|
6 @c %**end of header
|
|
|
7 @c $Id: psgml-api.texi,v 1.1.1.1 1996/12/18 03:36:11 steve Exp $
|
|
|
8
|
|
|
9 @ifinfo
|
|
|
10 Documentation for PSGML, a major mode for SGML.
|
|
|
11
|
|
|
12 Copyright 1994 Lennart Staflin
|
|
|
13
|
|
|
14 Permission is granted to make and distribute verbatim
|
|
|
15 copies of this manual provided the copyright notice and
|
|
|
16 this permission notice are preserved on all copies.
|
|
|
17
|
|
|
18 @ignore
|
|
|
19 Permission is granted to process this file through TeX
|
|
|
20 and print the results, provided the printed document
|
|
|
21 carries a copying permission notice identical to this
|
|
|
22 one except for the removal of this paragraph (this
|
|
|
23 paragraph not being relevant to the printed manual).
|
|
|
24
|
|
|
25 @end ignore
|
|
|
26 Permission is granted to copy and distribute modified
|
|
|
27 versions of this manual under the conditions for
|
|
|
28 verbatim copying, and provided that the entire
|
|
|
29 resulting derived work is distributed under the terms
|
|
|
30 of a permission notice identical to this one.
|
|
|
31
|
|
|
32 Permission is granted to copy and distribute
|
|
|
33 translations of this manual into another language,
|
|
|
34 under the above conditions for modified versions,
|
|
|
35 except that this permission notice may be stated in a
|
|
|
36 translation approved by the Free Software Foundation.
|
|
|
37
|
|
|
38 @end ifinfo
|
|
|
39
|
|
|
40 @titlepage
|
|
|
41
|
|
|
42 @title Internals of PSGML
|
|
|
43 @author Lennart Staflin
|
|
|
44
|
|
|
45 @c The following two commands
|
|
|
46 @c start the copyright page.
|
|
|
47 @page
|
|
|
48 @vskip 0pt plus 1filll
|
|
|
49 Copyright @copyright{} 1994 Lennart Staflin
|
|
|
50
|
|
|
51 @c Published by ...
|
|
|
52
|
|
|
53 Permission is granted to make and distribute verbatim
|
|
|
54 copies of this manual provided the copyright notice and
|
|
|
55 this permission notice are preserved on all copies.
|
|
|
56
|
|
|
57 @ignore
|
|
|
58 Permission is granted to process this file through TeX
|
|
|
59 and print the results, provided the printed document
|
|
|
60 carries a copying permission notice identical to this
|
|
|
61 one except for the removal of this paragraph (this
|
|
|
62 paragraph not being relevant to the printed manual).
|
|
|
63
|
|
|
64 @end ignore
|
|
|
65 Permission is granted to copy and distribute modified
|
|
|
66 versions of this manual under the conditions for
|
|
|
67 verbatim copying, and provided that the entire
|
|
|
68 resulting derived work is distributed under the terms
|
|
|
69 of a permission notice identical to this one.
|
|
|
70
|
|
|
71 Permission is granted to copy and distribute
|
|
|
72 translations of this manual into another language,
|
|
|
73 under the above conditions for modified versions,
|
|
|
74 except that this permission notice may be stated in a
|
|
|
75 translation approved by the Free Software Foundation.
|
|
|
76 @end titlepage
|
|
|
77
|
|
|
78 @node Top, Types, (dir), (dir)
|
|
|
79 @comment node-name, next, previous, up
|
|
|
80 @ifinfo
|
|
|
81 @top PSGML Internals
|
|
|
82 @end ifinfo
|
|
|
83
|
|
|
84 @menu
|
|
|
85 * Types:: Types and operations
|
|
|
86 * Hooks:: Hooks
|
|
|
87 * Implementation:: Implementation notes
|
|
|
88 * Index:: Index
|
|
|
89
|
|
|
90 --- The Detailed Node Listing ---
|
|
|
91
|
|
|
92 Types and operations
|
|
|
93
|
|
|
94 * element:: The element structure
|
|
|
95 * attribute:: Attribute Types
|
|
|
96 * parser state:: Parser state
|
|
|
97 * DTD:: DTD
|
|
|
98 * entities:: Entities
|
|
|
99 @end menu
|
|
|
100
|
|
|
101 @node Types, Hooks, Top, Top
|
|
|
102 @comment node-name, next, previous, up
|
|
|
103 @chapter Types and operations
|
|
|
104
|
|
|
105 NOTE:
|
|
|
106 Names of element types, attributes and entities should be treated as far
|
|
|
107 as possible as a real type. In versions prior to 1.0 names are
|
|
|
108 represented by lisp symbols but in 1.0 they are strings.
|
|
|
109
|
|
|
110 Perhaps I should make a @file{psgml-api.el} that defines some functions
|
|
|
111 to deal with names. Then it would be possible to write code that works
|
|
|
112 in both 0.4 and 1.0.
|
|
|
113
|
|
|
114
|
|
|
115 @menu
|
|
|
116 * element:: The element structure
|
|
|
117 * attribute:: Attribute Types
|
|
|
118 * parser state:: Parser state
|
|
|
119 * DTD:: DTD
|
|
|
120 * entities:: Entities
|
|
|
121 @end menu
|
|
|
122
|
|
|
123 @node element, attribute, Types, Types
|
|
|
124 @comment node-name, next, previous, up
|
|
|
125 @section The element structure
|
|
|
126
|
|
|
127 @deftp {Data type} element
|
|
|
128 The basic data type representing the element structure is the Element (this
|
|
|
129 happens to be a node in the parse tree).
|
|
|
130 @end deftp
|
|
|
131
|
|
|
132
|
|
|
133 @subsection Mapping buffer positions to elements
|
|
|
134
|
|
|
135 @defun sgml-find-context-of pos
|
|
|
136 Return the element current at buffer position @var{pos}. If @var{pos}
|
|
|
137 is in markup, @code{sgml-markup-type} will be a symbol identifying the
|
|
|
138 markup type. It will be @code{nil} if @var{pos} is outside markup.
|
|
|
139 @end defun
|
|
|
140
|
|
|
141 @defun sgml-find-element-of pos
|
|
|
142 Return the element containing the character at buffer position @var{pos}.
|
|
|
143 @end defun
|
|
|
144
|
|
|
145
|
|
|
146 @subsection Functions operating on elements
|
|
|
147
|
|
|
148 @defun sgml-element-name element
|
|
|
149 Returns the name of the element. (obsolete)
|
|
|
150 @end defun
|
|
|
151
|
|
|
152 @defun sgml-element-gi element
|
|
|
153 Return the general identifier (string) of @var{element}.
|
|
|
154 @end defun
|
|
|
155
|
|
|
156 @defun sgml-element-level element
|
|
|
157 Returns the level of @var{element} in the element structure. The
|
|
|
158 document element is level 1.
|
|
|
159 @end defun
|
|
|
160
|
|
|
161 @subsubsection Structure
|
|
|
162
|
|
|
163 @defun sgml-top-element
|
|
|
164 Return the document element.
|
|
|
165 @end defun
|
|
|
166
|
|
|
167 @defun sgml-off-top-p element
|
|
|
168 True if @var{element} is the pseudo element above the document element.
|
|
|
169 @end defun
|
|
|
170
|
|
|
171 These functions return other related elements, or possibly @code{nil}.
|
|
|
172
|
|
|
173 @defun sgml-element-content element
|
|
|
174 First element in content of @var{element}, or nil.
|
|
|
175 @end defun
|
|
|
176
|
|
|
177 @defun sgml-element-next element
|
|
|
178 Next sibling of @var{element}. To loop thru all sub elements of an
|
|
|
179 element, @code{el}, You could do like this:
|
|
|
180
|
|
|
181 @lisp
|
|
|
182 (let ((c (sgml-element-content el)))
|
|
|
183 (while c
|
|
|
184 <<Do something with c>>
|
|
|
185 (setq c (sgml-element-next c))))
|
|
|
186 @end lisp
|
|
|
187 @end defun
|
|
|
188
|
|
|
189 @defun sgml-element-parent element
|
|
|
190 Parent of @var{element}.
|
|
|
191 @end defun
|
|
|
192
|
|
|
193
|
|
|
194 @subsubsection Tags
|
|
|
195
|
|
|
196 @defun sgml-element-stag-optional element
|
|
|
197 Return true if the start-tag of @var{element} is omissible.
|
|
|
198 @end defun
|
|
|
199
|
|
|
200 @defun sgml-element-etag-optional element
|
|
|
201 Return true if the end-tag of @var{element} is omissible.
|
|
|
202 @end defun
|
|
|
203
|
|
|
204 @defun sgml-element-stag-len element
|
|
|
205 Return the length of the start-tag of @var{element}. If the start-tag
|
|
|
206 has been omitted the length is 0.
|
|
|
207 @end defun
|
|
|
208
|
|
|
209 @defun sgml-element-etag-len element
|
|
|
210 Return the length of the end-tag of @var{element}. If the end-tag
|
|
|
211 has been omitted the length is 0.
|
|
|
212 @end defun
|
|
|
213
|
|
|
214 @defun sgml-element-net-enabled element
|
|
|
215 Return true, if @var{element} or some parent of the element has null end
|
|
|
216 tag (NET) enabled. Return @code{t}, if it is @var{element} that has NET
|
|
|
217 enabled.
|
|
|
218 @end defun
|
|
|
219
|
|
|
220
|
|
|
221 @subsubsection Positions
|
|
|
222
|
|
|
223 These functions relates an element to positions in the buffer.
|
|
|
224
|
|
|
225 @defun sgml-element-start element
|
|
|
226 Position of start of @var{element}.
|
|
|
227 @end defun
|
|
|
228
|
|
|
229 @defun sgml-element-end element
|
|
|
230 Position after @var{element}.
|
|
|
231 @end defun
|
|
|
232
|
|
|
233 @defun sgml-element-stag-end element
|
|
|
234 Position after start-tag of @var{element}.
|
|
|
235 @end defun
|
|
|
236
|
|
|
237 @defun sgml-element-etag-start element
|
|
|
238 Position before end-tag of @var{element}.
|
|
|
239 @end defun
|
|
|
240
|
|
|
241
|
|
|
242 @subsubsection Attributes
|
|
|
243
|
|
|
244 @defun sgml-element-attlist element
|
|
|
245 Return the attribute declaration list for @var{element}.
|
|
|
246 @end defun
|
|
|
247
|
|
|
248 @defun sgml-element-attribute-specification-list element
|
|
|
249 Return the attribute specification list for @var{element}.
|
|
|
250 @end defun
|
|
|
251
|
|
|
252 @defun sgml-element-attval element attribute
|
|
|
253 Return the value of the @var{attribute} in @var{element}, string or nil.
|
|
|
254 @end defun
|
|
|
255
|
|
|
256
|
|
|
257 @subsubsection Misc technical
|
|
|
258
|
|
|
259
|
|
|
260 @defun sgml-element-data-p element
|
|
|
261 True if @var{element} can contain data characters.
|
|
|
262 @end defun
|
|
|
263
|
|
|
264 @defun sgml-element-mixed element
|
|
|
265 True if @var{element} has mixed content.
|
|
|
266 @end defun
|
|
|
267
|
|
|
268 @defun sgml-element-eltype element
|
|
|
269 @end defun
|
|
|
270
|
|
|
271 @defun sgml-element-empty element
|
|
|
272 True if @var{element} is empty.
|
|
|
273 @end defun
|
|
|
274
|
|
|
275 @defun sgml-element-excludes element
|
|
|
276 @end defun
|
|
|
277
|
|
|
278 @defun sgml-element-includes element
|
|
|
279 @end defun
|
|
|
280
|
|
|
281 @defun sgml-element-model element
|
|
|
282 Declared content or content model of @var{element}.
|
|
|
283 @end defun
|
|
|
284
|
|
|
285 @defun sgml-element-context-string element
|
|
|
286 Return string describing context of @var{element}.
|
|
|
287 @end defun
|
|
|
288
|
|
|
289 @c ----------------------------------------------------------------------
|
|
|
290 @node attribute, parser state, element, Types
|
|
|
291 @comment node-name, next, previous, up
|
|
|
292 @section Attribute Types
|
|
|
293
|
|
|
294 Basic types for attributes are names and values. (See note about names
|
|
|
295 in @ref{Types}.) And attribute values (attval) by lisp strings.
|
|
|
296
|
|
|
297
|
|
|
298 @subsection Attribute Declaration List Type
|
|
|
299
|
|
|
300 @deftp {Data type} attlist attdecl*
|
|
|
301 This is the result of the ATTLIST declarations in the DTD.
|
|
|
302 All attribute declarations for an element is the elements
|
|
|
303 attlist.
|
|
|
304 @end deftp
|
|
|
305
|
|
|
306 @defun sgml-lookup-attdecl name attlist
|
|
|
307 Return attribute declaration (attdecl) for attribute @var{name} in
|
|
|
308 attribute declaration list @var{attlist}.
|
|
|
309 @end defun
|
|
|
310
|
|
|
311 @defun sgml-attribute-with-declared-value attlist declared-value
|
|
|
312 Find the first attribute in @var{attlist} that has @var{declared-value}.
|
|
|
313 @end defun
|
|
|
314
|
|
|
315
|
|
|
316 @subsection Attribute Declaration Type
|
|
|
317
|
|
|
318 @deftp {Data type} attdecl name declared-value default-value
|
|
|
319 This is the representation of an individual attribute declaration
|
|
|
320 contained in an ATTLIST declaration.
|
|
|
321 @end deftp
|
|
|
322
|
|
|
323 @defun sgml-make-attdecl name declared-value default-value
|
|
|
324 Produces an attdecl.
|
|
|
325 @end defun
|
|
|
326
|
|
|
327 @defun sgml-attdecl-name attdecl
|
|
|
328 Returns the name of an attribute declaration.
|
|
|
329 @end defun
|
|
|
330
|
|
|
331 @defun sgml-attdecl-declared-value attdecl
|
|
|
332 Returns the declared-value of attribute declaration @var{attdecl}.
|
|
|
333 @end defun
|
|
|
334
|
|
|
335 @defun sgml-attdecl-default-value: attdecl
|
|
|
336 Returns the default-value of attribute declaration @var{attdecl}.
|
|
|
337 @end defun
|
|
|
338
|
|
|
339
|
|
|
340 @subsection Declared Value Type
|
|
|
341
|
|
|
342 @deftp {Data type} declared-value (token-group | notation | simple)
|
|
|
343 A declared value of an SGML attribute can be of different kinds. If the
|
|
|
344 declared value is a token group there is an associated list of name
|
|
|
345 tokens. For notation there is also a list of associated names, the
|
|
|
346 allowed notation names. The other declared values are represented by the
|
|
|
347 type name as a lisp symbol.
|
|
|
348 @c token-group = nametoken+
|
|
|
349 @c notation = nametoken+
|
|
|
350 @c simple = symbol
|
|
|
351 @end deftp
|
|
|
352
|
|
|
353 @defun sgml-declared-value-token-group declared-value
|
|
|
354 Return the name token group for the @var{declared-value}.
|
|
|
355 This applies to name token groups. For other declared values nil is
|
|
|
356 returned.
|
|
|
357 @end defun
|
|
|
358
|
|
|
359 @defun sgml-declared-value-notation declared-value
|
|
|
360 Return the list of notation names for the @var{declared-value}.
|
|
|
361 This applies to notation declared value. For other declared values
|
|
|
362 nil is returned.
|
|
|
363 @end defun
|
|
|
364
|
|
|
365
|
|
|
366 @subsection Default Value Type
|
|
|
367
|
|
|
368 @deftp {Data type} default-value (required | implied | conref | specified )
|
|
|
369 @c implied, conref = constant symbol
|
|
|
370 @c specified = (fixed | normal)
|
|
|
371 @c fixed, normal = attval
|
|
|
372 There are several kinds of default values. The @var{required},
|
|
|
373 @var{implied}, and @var{conref} has no associated information. The
|
|
|
374 @var{specified} have an associated attribute value and can be either
|
|
|
375 @code{fixed} or @code{normal}.
|
|
|
376 @end deftp
|
|
|
377
|
|
|
378 @defun sgml-make-default-value type &optional attval
|
|
|
379 @end defun
|
|
|
380
|
|
|
381 @defun sgml-default-value-attval default-value
|
|
|
382 Return the actual default value of the declared @var{default-value}.
|
|
|
383 The actual value is a string. Return @code{nil} if no actual value.
|
|
|
384 @end defun
|
|
|
385
|
|
|
386 @defun sgml-default-value-type-p type default-value
|
|
|
387 Return true if @var{default-value} is of @var{type}. Where @var{type}
|
|
|
388 is a symbol, one of @code{required}, @code{implied}, @code{conref}, or
|
|
|
389 @code{fixed}.
|
|
|
390 @end defun
|
|
|
391
|
|
|
392
|
|
|
393 @subsection Attribute Specification Type
|
|
|
394
|
|
|
395 @deftp {Data type} attspec name attval
|
|
|
396 This is the result of parsing an attribute specification.
|
|
|
397 @end deftp
|
|
|
398
|
|
|
399 @defun sgml-make-attspec name attval
|
|
|
400 Create an attspec from @var{name} and @var{attval}.
|
|
|
401 Special case, if @var{attval} is @code{nil} this is an implied attribute.
|
|
|
402 @end defun
|
|
|
403
|
|
|
404 @defun sgml-attspec-name attspec
|
|
|
405 Return the name of the attribute specified by @var{attspec}.
|
|
|
406 @end defun
|
|
|
407
|
|
|
408 @defun sgml-attspec-attval attspec
|
|
|
409 Return the value (attval) of attribute specification @var{attspec}.
|
|
|
410 If @var{attspec} is @code{nil}, @code{nil} is returned.
|
|
|
411 @end defun
|
|
|
412
|
|
|
413
|
|
|
414 @subsection Attribute Specification List Type
|
|
|
415
|
|
|
416 @deftp {Data type} asl attspec*
|
|
|
417 This is the result of parsing an attribute specification list.
|
|
|
418 @end deftp
|
|
|
419
|
|
|
420 @defun sgml-lookup-attspec name asl
|
|
|
421 Return the attribute specification for attribute with @var{name} in the
|
|
|
422 attribute specification list @var{asl}. If the attribute is unspecified
|
|
|
423 @code{nil} is returned.
|
|
|
424 @end defun
|
|
|
425
|
|
|
426
|
|
|
427
|
|
|
428 @c ------------------------------------------------------------------
|
|
|
429 @node parser state, DTD, attribute, Types
|
|
|
430 @comment node-name, next, previous, up
|
|
|
431 @section Parser state
|
|
|
432
|
|
|
433 The state of the parser that needs to be kept between commands are
|
|
|
434 stored in a buffer local variable. Some global variables are
|
|
|
435 initialised from this variable when parsing starts.
|
|
|
436
|
|
|
437 @defvar sgml-buffer-parse-state
|
|
|
438 The state of the parser that is kept between commands. The value of
|
|
|
439 this variable is of type pstate.
|
|
|
440 @end defvar
|
|
|
441
|
|
|
442 @deftp {Data type} pstate
|
|
|
443 The parser state.
|
|
|
444 @end deftp
|
|
|
445
|
|
|
446 @defun sgml-pstate-dtd pstate
|
|
|
447 The document type information (dtd) for the parser.
|
|
|
448 @end defun
|
|
|
449
|
|
|
450
|
|
|
451 @c ------------------------------------------------------------------
|
|
|
452 @node DTD, entities, parser state, Types
|
|
|
453 @comment node-name, next, previous, up
|
|
|
454 @section DTD
|
|
|
455
|
|
|
456 @deftp {Data type} dtd
|
|
|
457 Represents what PSGML knows about the DTD.
|
|
|
458 @end deftp
|
|
|
459
|
|
|
460 @defun sgml-dtd-doctype dtd
|
|
|
461 The document type name.
|
|
|
462 @end defun
|
|
|
463
|
|
|
464 @defun sgml-dtd-eltypes dtd
|
|
|
465 The table of element types.
|
|
|
466 @end defun
|
|
|
467
|
|
|
468 @defun sgml-dtd-entities dtd
|
|
|
469 The table of declared general entities (entity-table).
|
|
|
470 @end defun
|
|
|
471
|
|
|
472 @defun sgml-dtd-parameters dtd
|
|
|
473 The table of declared parameter entities (entity-table).
|
|
|
474 @end defun
|
|
|
475
|
|
|
476 @defun sgml-dtd-shortmaps dtd
|
|
|
477 The list of short reference maps.
|
|
|
478 @end defun
|
|
|
479
|
|
|
480 @defun sgml-dtd-notations dtd
|
|
|
481 Not yet implemented.
|
|
|
482 @end defun
|
|
|
483
|
|
|
484
|
|
|
485
|
|
|
486 @c ------------------------------------------------------------------
|
|
|
487 @node entities, , DTD, Types
|
|
|
488 @comment node-name, next, previous, up
|
|
|
489 @section Entities
|
|
|
490
|
|
|
491 @deftp {Data type} entity
|
|
|
492 An entity has the following properties:
|
|
|
493
|
|
|
494 @table @var
|
|
|
495 @item name
|
|
|
496 The name of the entity (a string). This is either the name of a
|
|
|
497 declared entity (general or parameter) or the doctype name if it is the
|
|
|
498 implicit entity referred to by the doctype declaration.
|
|
|
499
|
|
|
500 @item type
|
|
|
501 This is a symbol. It is @code{text} if it is a text entity, other
|
|
|
502 values are @code{cdata}, @code{ndata}, @code{sdata}, @code{sgml} or
|
|
|
503 @code{dtd}.
|
|
|
504
|
|
|
505 @item text
|
|
|
506 This is the text of the entity, either a string or an external
|
|
|
507 identifier.
|
|
|
508 @end table
|
|
|
509 @end deftp
|
|
|
510
|
|
|
511 Operations on entities
|
|
|
512
|
|
|
513 @defun sgml-make-entity name type text
|
|
|
514 Create an entity.
|
|
|
515 @end defun
|
|
|
516
|
|
|
517 @defun sgml-entity-name entity
|
|
|
518 The name of the entity.
|
|
|
519 @end defun
|
|
|
520
|
|
|
521 @defun sgml-entity-type entity
|
|
|
522 The type of the entity.
|
|
|
523 @end defun
|
|
|
524
|
|
|
525 @defun sgml-entity-text entity
|
|
|
526 The text of the entity.
|
|
|
527 @end defun
|
|
|
528
|
|
|
529 @defun sgml-entity-insert-text entity
|
|
|
530 Insert the text of the entity into the current buffer at point.
|
|
|
531 @end defun
|
|
|
532
|
|
|
533 @defun sgml-entity-data-p entity
|
|
|
534 True if @var{entity} is a data entity, that is not of type @code{text}.
|
|
|
535 @end defun
|
|
|
536
|
|
|
537
|
|
|
538 @deftp {Data type} entity-table
|
|
|
539 A table of entities that can be referenced by entity name.
|
|
|
540 @end deftp
|
|
|
541
|
|
|
542 @defun sgml-lookup-entity name entity-table
|
|
|
543 The entity with named @var{name} in the table @var{entity-table}. If no
|
|
|
544 such entity exists, @code{nil} is returned.
|
|
|
545 @end defun
|
|
|
546
|
|
|
547 @defun sgml-entity-declare name entity-table type text
|
|
|
548 Create an entity from @var{name}, @var{type} and @var{text}; and enter
|
|
|
549 the entity into the table @var{entity-table}.
|
|
|
550 @end defun
|
|
|
551
|
|
|
552 @defun sgml-entity-completion-table entity-table
|
|
|
553 Make a completion table from the @var{entity-table}.
|
|
|
554 @end defun
|
|
|
555
|
|
|
556 @defun sgml-map-entities fn entity-table &optional collect
|
|
|
557 Apply the function @var{fn} to all entities in @var{entity-table}. If
|
|
|
558 @var{collect} is @code{t}, the results of the applications are collected
|
|
|
559 in a list and returned.
|
|
|
560 @end defun
|
|
|
561
|
|
|
562
|
|
|
563
|
|
|
564 @c ------------------------------------------------------------------
|
|
|
565 @node Hooks, Implementation, Types, Top
|
|
|
566 @comment node-name, next, previous, up
|
|
|
567 @chapter Hooks
|
|
|
568
|
|
|
569 @defvar sgml-open-element-hook
|
|
|
570 The hook run by @code{sgml-open-element}.
|
|
|
571 Theses functions are called with two arguments, the first argument is
|
|
|
572 the opened element and the second argument is the attribute specification
|
|
|
573 list. It is probably best not to refer to the content or the end-tag of
|
|
|
574 the element.
|
|
|
575 @end defvar
|
|
|
576
|
|
|
577 @defvar sgml-close-element-hook
|
|
|
578 The hook run by @code{sgml-close-element}. These functions are invoked
|
|
|
579 with @code{sgml-current-tree} bound to the element just parsed.
|
|
|
580 @end defvar
|
|
|
581
|
|
|
582 @defvar sgml-doctype-parsed-hook
|
|
|
583 This hook is called after the doctype has been parsed.
|
|
|
584 It can be used to load any additional information into the DTD structure.
|
|
|
585 @end defvar
|
|
|
586
|
|
|
587 @defvar sgml-sysid-resolve-functions
|
|
|
588 This variable should contain a list of functions.
|
|
|
589 Each function should take one argument, the system identifier of an entity.
|
|
|
590 If the function can handle that identifier, it should insert the text
|
|
|
591 of the entity into the current buffer at point and return t. If the
|
|
|
592 system identifier is not handled the function should return nil.
|
|
|
593 @end defvar
|
|
|
594
|
|
|
595
|
|
|
596 @c ------------------------------------------------------------------
|
|
|
597 @node Implementation, Index, Hooks, Top
|
|
|
598 @comment node-name, next, previous, up
|
|
|
599 @chapter Implementation notes
|
|
|
600
|
|
|
601 @section Data Types and Operations
|
|
|
602
|
|
|
603 @subsection Element Type
|
|
|
604
|
|
|
605 @deftp {Data type} eltype
|
|
|
606 Data type representing the information about an element type. An
|
|
|
607 @code{eltype} has information from @samp{ELEMENT} and @samp{ATTLIST}
|
|
|
608 declarations. It can also store data for the application.
|
|
|
609 @end deftp
|
|
|
610
|
|
|
611 The element types are symbols in a special oblist. The oblist is the
|
|
|
612 table of element types. The symbols name is the GI, its value is used
|
|
|
613 to store three flags and the function definition holds the content
|
|
|
614 model. Other information about the element type is stored on the
|
|
|
615 property list.
|
|
|
616
|
|
|
617 @defun sgml-eltype-name et
|
|
|
618 The name (a string) of the element type @var{et}.
|
|
|
619 @end defun
|
|
|
620
|
|
|
621 @defun sgml-eltype-appdata et prop
|
|
|
622 Get application data from element type @var{et} with name @var{prop}.
|
|
|
623 @var{prop} should be a symbol, reserved names are: flags, model, attlist,
|
|
|
624 includes, excludes, conref-regexp, mixed, stag-optional, etag-optional.
|
|
|
625
|
|
|
626 This function can be used as a place in @code{setf}, @code{push} and
|
|
|
627 other functions from the CL library.
|
|
|
628 @end defun
|
|
|
629
|
|
|
630 @defun sgml-eltype-all-miscdata eltype
|
|
|
631 A list of all data properties for eltype except for flags, model,
|
|
|
632 includes and excludes. This function filters the property list of
|
|
|
633 @var{eltype}. Used when saving the parsed DTD.
|
|
|
634 @end defun
|
|
|
635
|
|
|
636 @defun sgml-eltype-set-all-miscdata eltype miscdata
|
|
|
637 Append the @var{miscdata} data properties to the properties of
|
|
|
638 @var{eltype}.
|
|
|
639 @end defun
|
|
|
640
|
|
|
641 @defun sgml-eltype-attlist et
|
|
|
642 The attribute specification list for the element type @var{et}.
|
|
|
643 @end defun
|
|
|
644
|
|
|
645 @defun sgml-eltype-completion-table eltypes
|
|
|
646 Make a completion table from a list, @var{eltypes}, of element types.
|
|
|
647 @end defun
|
|
|
648
|
|
|
649 @defun sgml-eltype-stag-optional et
|
|
|
650 True if the element type @var{et} has optional start-tag.
|
|
|
651 @end defun
|
|
|
652
|
|
|
653 @defun sgml-eltype-etag-optional et
|
|
|
654 True if the element type @var{et} has optional end-tag.
|
|
|
655 @end defun
|
|
|
656
|
|
|
657 @defun sgml-eltype-excludes et
|
|
|
658 The list of excluded element types for element type @var{et}.
|
|
|
659 @end defun
|
|
|
660
|
|
|
661 @defun sgml-eltype-includes et
|
|
|
662 The list of included element types for element type @var{et}.
|
|
|
663 @end defun
|
|
|
664
|
|
|
665 @defun sgml-eltype-flags et
|
|
|
666 Contains three flags as a number. The flags are stag-optional,
|
|
|
667 etag-optional and mixed.
|
|
|
668 @end defun
|
|
|
669
|
|
|
670 @defun sgml-eltype-mixed et
|
|
|
671 True if element type @var{et} has mixed content.
|
|
|
672 @end defun
|
|
|
673
|
|
|
674 @defun sgml-eltype-model et
|
|
|
675 The content model of element type @var{et}. The content model is either
|
|
|
676 the start state in the DFA for the content model or a symbol identifying
|
|
|
677 a declared content.
|
|
|
678 @end defun
|
|
|
679
|
|
|
680 @defun sgml-eltype-shortmap et
|
|
|
681 The name of the shortmap associated with element type @var{et}. This
|
|
|
682 can also be the symbol @code{empty} (if declared with a @samp{<!USEMAP
|
|
|
683 gi #EMPTY>} or @code{nil} (if no associated map).
|
|
|
684 @end defun
|
|
|
685
|
|
|
686
|
|
|
687 @defun sgml-eltype-token et
|
|
|
688 Return a token for the element type @var{et}.
|
|
|
689 @end defun
|
|
|
690
|
|
|
691 @defun sgml-eltypes-in-state state tree
|
|
|
692 List of element types valid in @var{state} and @var{tree}.
|
|
|
693 @end defun
|
|
|
694
|
|
|
695
|
|
|
696 @subsection DTD
|
|
|
697
|
|
|
698 The DTD data type is realised as a lisp vector using @code{defstruct}.
|
|
|
699
|
|
|
700 There are two additional fields for internal use: dependencies and
|
|
|
701 merged.
|
|
|
702
|
|
|
703 @defun sgml-dtd-dependencies dtd
|
|
|
704 The list of files used to create this DTD.
|
|
|
705 @end defun
|
|
|
706
|
|
|
707 @defun sgml-dtd-merged dtd
|
|
|
708 The pair (@var{file} . @var{merged-dtd}), if the DTD has had a
|
|
|
709 precompiled dtd merged into it. @var{File} is the file containing the
|
|
|
710 compiled DTD and @var{merged-dtd} is the DTD loaded from that file.
|
|
|
711 @end defun
|
|
|
712
|
|
|
713
|
|
|
714 @subsection Element and Tree
|
|
|
715
|
|
|
716 @deftp {Data Type} tree
|
|
|
717 This is the data type for the nodes in the tree build by the parser.
|
|
|
718 @end deftp
|
|
|
719
|
|
|
720 The tree nodes are represented as lisp vectors, using @code{defstruct}
|
|
|
721 to define basic operations.
|
|
|
722
|
|
|
723 The Element data type is a view of the tree built by the parser.
|
|
|
724
|
|
|
725
|
|
|
726 @section Parsing model
|
|
|
727
|
|
|
728 PSGML uses finite state machines and a stack to parse SGML. Every
|
|
|
729 element type has an associated DFA (deterministic finite automaton).
|
|
|
730 This DFA is constructed from the content model.
|
|
|
731
|
|
|
732 SGML restricts the allowed content models in such a way that it is
|
|
|
733 easy to directly construct a DFA.
|
|
|
734
|
|
|
735 To be able to determine when a start-tag can be omitted the DFA need to
|
|
|
736 contain some more information than the traditional DFA. In PSGML a DFA
|
|
|
737 has a set of states and two sets of edges. The edges are associated
|
|
|
738 with tokens (corresponding to SGML's primitive content tokens). I call
|
|
|
739 these moves. One set of moves, the @dfn{optional moves}, represents
|
|
|
740 optional tokens. I call the other set @dfn{required moves}. The
|
|
|
741 correspondence to SGML definitions are: if there is precisely one
|
|
|
742 required move from one state, then the associated token is required.
|
|
|
743 A state is final if there is not required move from that state.
|
|
|
744
|
|
|
745 The SGML construct @samp{(...&...&...)} (@dfn{AND-group}) is another
|
|
|
746 problem. There is a simple translation to sequence- and or-connectors.
|
|
|
747 For example @samp{(a & b & c)} is can be translated to:
|
|
|
748
|
|
|
749 @example
|
|
|
750 ((a, b, c) | (a, c, b) |
|
|
|
751 (b, a, c) | (b, c, a) |
|
|
|
752 (c, a, b) | (c, b, a))
|
|
|
753 @end example
|
|
|
754
|
|
|
755 But this grows too fast to be of direct practical use. PSGML represents
|
|
|
756 an AND-group with one DFA for every (SGML) token in the group. During
|
|
|
757 parsing of an AND-group there is a pointer to a state in one of the
|
|
|
758 group's DFAs, and a list of the DFAs for the tokens not yet satisfied.
|
|
|
759 Most of this is hidden by the primitives for the state type. The parser
|
|
|
760 only sees states in a DFA and moves.
|
|
|
761
|
|
|
762
|
|
|
763 @section Entity manager
|
|
|
764
|
|
|
765 @defun sgml-push-to-entity entity &optional ref-start type
|
|
|
766 Set current buffer to a buffer containing the entity @var{entity}.
|
|
|
767 @var{entity} can also be a file name. Optional argument @var{ref-start}
|
|
|
768 should be the start point of the entity reference. Optional argument
|
|
|
769 @var{type}, overrides the entity type in entity look up.
|
|
|
770 @end defun
|
|
|
771
|
|
|
772
|
|
|
773 @defun sgml-pop-entity
|
|
|
774 Should be called after a @code{sgml-push-to-entity} (or similar).
|
|
|
775 Restore the current buffer to the buffer that was current when the push
|
|
|
776 to this buffer was made.
|
|
|
777 @end defun
|
|
|
778
|
|
|
779 @defun sgml-push-to-string string
|
|
|
780 Create an entity from @var{string} and push it on the top of the entity
|
|
|
781 stack. After this the current buffer will be a scratch buffer containing
|
|
|
782 the text of the new entity with point at the first character.
|
|
|
783
|
|
|
784 Use @code{sgml-pop-entity} to exit from this buffer.
|
|
|
785 @end defun
|
|
|
786
|
|
|
787
|
|
|
788 @c @section Lexical
|
|
|
789
|
|
|
790 @section Parser functions
|
|
|
791
|
|
|
792 @defun sgml-need-dtd
|
|
|
793 This makes sure that the buffer has a DTD and set global variables
|
|
|
794 needed by parsing routines. One global variable is @code{sgml-dtd-info}
|
|
|
795 which contain the DTD (type dtd).
|
|
|
796 @end defun
|
|
|
797
|
|
|
798
|
|
|
799 @defun sgml-parse-to goal &optional extra-cond quiet
|
|
|
800 This is the low level interface to the parser.
|
|
|
801
|
|
|
802 Parse until (at least) @var{goal}, a buffer position. Optional argument
|
|
|
803 @var{extra-cond} should be a function. This function is called in the
|
|
|
804 parser loop, and the loop is exited if the function returns t. If third
|
|
|
805 argument @var{quit} is non-@code{nil}, no "@samp{Parsing...}" message
|
|
|
806 will be displayed.
|
|
|
807 @end defun
|
|
|
808
|
|
|
809
|
|
|
810 @defun sgml-reparse-buffer shortref-fun
|
|
|
811 Reparse the buffer and let @var{shortref-fun} take care of short
|
|
|
812 references. @var{shortref-fun} is called with the entity as
|
|
|
813 argument and @code{sgml-markup-start} pointing to start of short
|
|
|
814 reference and point pointing to the end.
|
|
|
815 @end defun
|
|
|
816
|
|
|
817
|
|
|
818 @section Saved DTD Format
|
|
|
819 @format
|
|
|
820 File = Comment,
|
|
|
821 File version,
|
|
|
822 S-expression --dependencies--,
|
|
|
823 Parameter entites,
|
|
|
824 Document type name,
|
|
|
825 Elements,
|
|
|
826 General entities,
|
|
|
827 S-expression --shortref maps--,
|
|
|
828 S-expression --notations--
|
|
|
829
|
|
|
830 Elements = Counted Sequence of S-expression --element type name--,
|
|
|
831 Counted Sequence of Element type description
|
|
|
832
|
|
|
833 File version = "(sgml-saved-dtd-version 5)
|
|
|
834 "
|
|
|
835
|
|
|
836 Comment = (";",
|
|
|
837 (CASE
|
|
|
838 OF [0-9]
|
|
|
839 OF [11-255])*,
|
|
|
840 [10] --end of line marker--)*
|
|
|
841
|
|
|
842 Element type description = S-expression --Misc info--,
|
|
|
843 CASE
|
|
|
844 OF [0-7] --Flags 1:stag-opt, 2:etag-opt, 4:mixed--,
|
|
|
845 Content specification,
|
|
|
846 Token list --includes--,
|
|
|
847 Token list --excludes--
|
|
|
848 OF [128] --Flag undefined element--
|
|
|
849
|
|
|
850 Content specification = CASE
|
|
|
851 OF [0] --cdata--
|
|
|
852 OF [1] --rcdata--
|
|
|
853 OF [2] --empty--
|
|
|
854 OF [3] --any--
|
|
|
855 OF [4] --undefined--
|
|
|
856 OF [128] --model follows--,
|
|
|
857 Model --nodes in the finite state automaton--
|
|
|
858
|
|
|
859 Model = Counted Sequence of Node
|
|
|
860
|
|
|
861 Node = CASE
|
|
|
862 OF Normal State
|
|
|
863 OF And Node
|
|
|
864
|
|
|
865 Normal State = Moves --moves for optional tokens--,
|
|
|
866 Moves --moves for required tokens--
|
|
|
867
|
|
|
868 Moves = Counted Sequence of (Token,
|
|
|
869 OCTET --state #--)
|
|
|
870
|
|
|
871 And Node = [255] --signals an AND node--,
|
|
|
872 Number --next state (node number)--,
|
|
|
873 Counted Sequence of Model --set of models--
|
|
|
874
|
|
|
875 Token = Number --index in list of elements--
|
|
|
876
|
|
|
877 Number = CASE
|
|
|
878 OF [0-250] --Small number 0--250--
|
|
|
879 OF [251-255] --Big number, first octet--,
|
|
|
880 OCTET --Big number, second octet--
|
|
|
881
|
|
|
882 Token list = Counted Sequence of Token
|
|
|
883
|
|
|
884 Parameter entites = S-expression --internal representation of parameter entities--
|
|
|
885
|
|
|
886 General entities = S-expression --internal representation of general entities--
|
|
|
887
|
|
|
888 Document type name = S-expression --name of document type as a string--
|
|
|
889
|
|
|
890 S-expression = OTHER
|
|
|
891
|
|
|
892 Counted Sequence = Number_a --length of sequence--,
|
|
|
893 (ARG_1)^a
|
|
|
894
|
|
|
895
|
|
|
896 @end format
|
|
|
897
|
|
|
898
|
|
|
899
|
|
|
900 @c ------------------------------------------------------------------
|
|
|
901 @node Index, , Implementation, Top
|
|
|
902 @comment node-name, next, previous, up
|
|
|
903 @chapter Index
|
|
|
904
|
|
|
905 Types
|
|
|
906 @printindex tp
|
|
|
907
|
|
|
908 @bye
|
