content/xml/tests/docbooktest.xml@deefc01c0e14 (annotated)
content/xml/tests/docbooktest.xml
Thu, 15 Jan 2015 21:03:48 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 15 Jan 2015 21:03:48 +0100
- branch
- TOR_BUG_9701
- changeset 11
- deefc01c0e14
- permissions
- -rw-r--r--
Integrate friendly tips from Tor colleagues to make (or not) 4.5 alpha 3;
This includes removal of overloaded (but unused) methods, and addition of
a overlooked call to DataStruct::SetData(nsISupports, uint32_t, bool.)
| michael@0 | 1 | <?xml version="1.0"?> |
| michael@0 | 2 | <?xml-stylesheet href="docbook.css" type="text/css"?> |
| michael@0 | 3 | <!DOCTYPE Book SYSTEM "docbook.dtd"> |
| michael@0 | 4 | <Book xmlns:xlink="http://www.w3.org/1999/xlink"> |
| michael@0 | 5 | <Title>SoftQuad |
| michael@0 | 6 | Inc.</Title> |
| michael@0 | 7 | <p xmlns="http://www.w3.org/1999/xhtml" xmlns:h="http://www.w3.org/1999/xhtml"> |
| michael@0 | 8 | <h:img src="flamer.gif"/> |
| michael@0 | 9 | <img src="flamer.gif"/> |
| michael@0 | 10 | <button><b>some text</b></button> |
| michael@0 | 11 | </p> |
| michael@0 | 12 | <BookInfo> <BookBiblio> <Title>Demo Product Documentation</Title> |
| michael@0 | 13 | <AuthorGroup><CorpAuthor>SoftQuad Inc.</CorpAuthor></AuthorGroup> |
| michael@0 | 14 | </BookBiblio> </BookInfo> <Preface> <Title><Anchor |
| michael@0 | 15 | Id="SDK3"/>Element Overview</Title> |
| michael@0 | 16 | <BridgeHead>Introduction to Elements</BridgeHead> |
| michael@0 | 17 | <Para>By far the vast majority of objects (apart from text) that authors |
| michael@0 | 18 | encounter when traversing a document are Element nodes. </Para> </Preface> |
| michael@0 | 19 | <Part> <Title><Anchor Id="SDK273"/>Element Interfaces</Title> |
| michael@0 | 20 | <Chapter Label="1"> <Title><Anchor Id="SDK274"/>Elements and |
| michael@0 | 21 | Attributes</Title> |
| michael@0 | 22 | <Sect1> <Title><Anchor Id="SDK279"/>Introduction to Attributes |
| michael@0 | 23 | </Title> |
| michael@0 | 24 | <Para>Elements may have attributes associated with them; since the Element |
| michael@0 | 25 | interface inherits from Node, the generic Node interface method |
| michael@0 | 26 | <Function>getAttributes</Function> may be used to retrieve the set of all |
| michael@0 | 27 | attributes for an element. </Para> |
| michael@0 | 28 | <Para>There are methods on the Element interface to retrieve either an Attr |
| michael@0 | 29 | object by name or an attribute value by name. In XML, where an attribute value |
| michael@0 | 30 | may contain entity references, an Attr object should be retrieved to examine |
| michael@0 | 31 | the possibly fairly complex sub-tree representing the attribute value. On the |
| michael@0 | 32 | other hand, in HTML, where all attributes have simple string values, methods to |
| michael@0 | 33 | directly access an attribute value can safely be used as a convenience. </Para> |
| michael@0 | 34 | |
| michael@0 | 35 | <Para>Before you can access an Attribute, you must first gain access to the |
| michael@0 | 36 | associated Element.</Para> </Sect1> |
| michael@0 | 37 | <Sect1> <Title><Anchor Id="SDK378"/>Setting the Attribute |
| michael@0 | 38 | Values</Title> |
| michael@0 | 39 | <Para>Attr objects inherit the Node interface, but since they are not actually |
| michael@0 | 40 | child nodes of the element they describe, the DOM does not consider them part |
| michael@0 | 41 | of the document tree. Thus, the Node attributes parentNode, previousSibling, |
| michael@0 | 42 | and nextSibling have a null value for Attr objects. The DOM takes the view that |
| michael@0 | 43 | attributes are properties of elements rather than having a separate identity |
| michael@0 | 44 | from the elements they are associated with; this should make it more efficient |
| michael@0 | 45 | to implement such features as default attributes associated with all elements |
| michael@0 | 46 | of a given type. Furthermore, Attr nodes may not be immediate children of a |
| michael@0 | 47 | DocumentFragment. However, they can be associated with Element nodes contained |
| michael@0 | 48 | within a DocumentFragment. In short, users and implementors of the DOM need to |
| michael@0 | 49 | be aware that Attr nodes have some things in common with other objects |
| michael@0 | 50 | inheriting the Node interface, but they also are quite distinct. </Para> |
| michael@0 | 51 | <Para>The attribute's effective value is determined as follows:</Para> |
| michael@0 | 52 | <ItemizedList Mark="Bullet"> <ListItem> |
| michael@0 | 53 | <Para>If this attribute has been explicitly assigned any value, that value is |
| michael@0 | 54 | the attribute's effective value</Para></ListItem> <ListItem> |
| michael@0 | 55 | <Para>Otherwise, if there is a declaration for this attribute, and that |
| michael@0 | 56 | declaration includes a default value, then that default value is the |
| michael@0 | 57 | attribute's effective value</Para></ListItem> <ListItem> |
| michael@0 | 58 | <Para>Otherwise, the attribute does not exist on this element in the structure |
| michael@0 | 59 | model until it has been explicitly added.</Para></ListItem> </ItemizedList> |
| michael@0 | 60 | <Para>In XML, where the value of an attribute can contain entity references, |
| michael@0 | 61 | the child nodes of the Attr node provide a representation in which entity |
| michael@0 | 62 | references are not expanded. These child nodes may be either Text or |
| michael@0 | 63 | EntityReference nodes. Because the attribute type may be unknown, there are no |
| michael@0 | 64 | tokenized attribute values. </Para> |
| michael@0 | 65 | <Para>The following topics describe DOM attributes: </Para> |
| michael@0 | 66 | <ItemizedList Mark="Bullet"> <ListItem> |
| michael@0 | 67 | <Para> |
| michael@0 | 68 | <ULink xlink:type="simple" xlink:show="replace" |
| michael@0 | 69 | xlink:href="http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#ID-637646024">Interface |
| michael@0 | 70 | Attr</ULink> </Para></ListItem> <ListItem> |
| michael@0 | 71 | <Para> |
| michael@0 | 72 | <ULink xlink:type="simple" xlink:show="new" |
| michael@0 | 73 | xlink:href="http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#ID-745549614"> |
| michael@0 | 74 | Interface Element</ULink> </Para></ListItem> </ItemizedList> </Sect1></Chapter> |
| michael@0 | 75 | |
| michael@0 | 76 | <Chapter Label="26" Role="funcref"> <Title><Anchor |
| michael@0 | 77 | Id="SDK48"/>DOM Level 1 Core: Element Functions</Title> |
| michael@0 | 78 | <RefEntry> <RefMeta><RefEntryTitle> <Anchor Id="setAttribute"/>setAttribute |
| michael@0 | 79 | </RefEntryTitle></RefMeta> <RefNameDiv> <RefName>setAttribute</RefName> |
| michael@0 | 80 | <RefPurpose>Sets the Attributes on the associated Element object</RefPurpose> |
| michael@0 | 81 | <RefClass>Fundamental</RefClass> </RefNameDiv> <RefSynopsisDiv> <Title> |
| michael@0 | 82 | <Anchor Id="SDK85"/>Syntax</Title> |
| michael@0 | 83 | <RefSect2> <Title>OMG IDL</Title> |
| michael@0 | 84 | <Synopsis><Type>void</Type> <Function>setAttribute</Function> (in |
| michael@0 | 85 | <Type>DOMString</Type> <Parameter>name</Parameter>, in <Type>DOMString</Type> |
| michael@0 | 86 | <Parameter>value</Parameter>) raises (<ErrorType>DOMException</ErrorType>); |
| michael@0 | 87 | </Synopsis></RefSect2><RefSect2> <Title><Anchor Id="SDK86"/>Java</Title> |
| michael@0 | 88 | <Synopsis><Type>public void</Type> <Function>setAttribute</Function> ( |
| michael@0 | 89 | <Type>String</Type> <Parameter>name</Parameter>, <Type>String</Type> |
| michael@0 | 90 | <Parameter>value</Parameter>) throws (<ErrorType>DOMException</ErrorType>); |
| michael@0 | 91 | </Synopsis> </RefSect2><RefSect2> <Title><Anchor Id="SDK87"/>ECMA Script |
| michael@0 | 92 | </Title> |
| michael@0 | 93 | <Synopsis> <Function>setAttribute</Function> (<Parameter>name, value |
| michael@0 | 94 | </Parameter>)</Synopsis> </RefSect2></RefSynopsisDiv><RefSect1> <Title> |
| michael@0 | 95 | <Anchor Id="SDK88"/>Parameters</Title> |
| michael@0 | 96 | <VariableList> <VarListEntry><Term> <Parameter>name</Parameter></Term> |
| michael@0 | 97 | <ListItem> |
| michael@0 | 98 | <Para>(IN) The name of the attribute to create or alter.</Para> </ListItem> |
| michael@0 | 99 | </VarListEntry><VarListEntry><Term> <Parameter>value</Parameter></Term> |
| michael@0 | 100 | <ListItem> |
| michael@0 | 101 | <Para>(IN) Value to set in string form</Para> </ListItem></VarListEntry> |
| michael@0 | 102 | </VariableList></RefSect1><RefSect1> <Title><Anchor Id="SDK89"/>Exceptions |
| michael@0 | 103 | </Title> |
| michael@0 | 104 | <Para>These are the applicable exceptions. </Para> <InformalTable> <TGroup cols="2"> |
| michael@0 | 105 | <colspec colname="1" colnum="1" colwidth="0.630in"/> |
| michael@0 | 106 | <colspec colname="2" colnum="2" colwidth="5.203in"/> <tbody> |
| michael@0 | 107 | <row> <entry colname="1"> |
| michael@0 | 108 | <Para>INVALID_CHARACTER_ERR</Para></entry> <entry colname="2"> |
| michael@0 | 109 | <Para>Raised if the specified name contains an invalid character.</Para> |
| michael@0 | 110 | </entry></row> <row> <entry colname="1"> |
| michael@0 | 111 | <Para> NO_MODIFICATION_ALLOWED_ERR</Para></entry> <entry colname="2"> |
| michael@0 | 112 | <Para>Raised if this node is readonly.</Para></entry> </row> |
| michael@0 | 113 | </tbody> |
| michael@0 | 114 | </TGroup></InformalTable></RefSect1><RefSect1> <Title><Anchor |
| michael@0 | 115 | Id="SDK90"/>Remarks</Title> |
| michael@0 | 116 | <Para> <Function>setAttribute</Function> adds a new attribute. If an attribute |
| michael@0 | 117 | with that name is already present in the element, its value is changed to be |
| michael@0 | 118 | that of the value parameter. This value is a simple string, it is not parsed as |
| michael@0 | 119 | it is being set. So any markup (such as syntax to be recognized as an entity |
| michael@0 | 120 | reference) is treated as literal text, and needs to be appropriately escaped by |
| michael@0 | 121 | the implementation when it is written out.</Para> |
| michael@0 | 122 | <Para> In order to assign an attribute value that contains entity references, |
| michael@0 | 123 | the user must create an Attr node plus any Text and EntityReference nodes, |
| michael@0 | 124 | build the appropriate subtree, and use <Function>setAttributeNode</Function> to |
| michael@0 | 125 | assign it as the value of an attribute. </Para> </RefSect1></RefEntry> |
| michael@0 | 126 | </Chapter></Part></Book> |
