Mercurial > hg > xemacs-beta
comparison man/psgml-api.texi @ 0:376386a54a3c r19-14
Import from CVS: tag r19-14
author | cvs |
---|---|
date | Mon, 13 Aug 2007 08:45:50 +0200 |
parents | |
children | ac2d302a0011 |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:376386a54a3c |
---|---|
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 |