Skip to content

Commit 8837a45

Browse files
author
Steve Canny
committed
docs: document analysis for run-bool-props
1 parent fde03bb commit 8837a45

File tree

4 files changed

+274
-166
lines changed

4 files changed

+274
-166
lines changed

‎docs/dev/analysis/features/bool-run-props.rst‎

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
2+
Boolean Run properties
3+
======================
4+
5+
Character formatting that is either on or off, such as bold, italic, and
6+
small caps. Certain of these properties are *toggle properties* that may
7+
cancel each other out if they appear more than once in the style hierarchy.
8+
See §17.7.3 for more details on toggle properties. They don't affect the API
9+
specified here.
10+
11+
The following run properties are boolean (tri-state) properties:
12+
13+
+-----------------+------------+-------------------------------------------+
14+
| element | spec | name |
15+
+=================+============+===========================================+
16+
| `<b/>` | §17.3.2.1 | Bold |
17+
+-----------------+------------+-------------------------------------------+
18+
| `<bCs/>` | §17.3.2.2 | Complex Script Bold |
19+
+-----------------+------------+-------------------------------------------+
20+
| `<caps/>` | §17.3.2.5 | Display All Characters as Capital Letters |
21+
+-----------------+------------+-------------------------------------------+
22+
| `<cs/>` | §17.3.2.7 | Use Complex Script Formatting on Run |
23+
+-----------------+------------+-------------------------------------------+
24+
| `<dstrike/>` | §17.3.2.9 | Double Strikethrough |
25+
+-----------------+------------+-------------------------------------------+
26+
| `<emboss/>` | §17.3.2.13 | Embossing |
27+
+-----------------+------------+-------------------------------------------+
28+
| `<i/>` | §17.3.2.16 | Italics |
29+
+-----------------+------------+-------------------------------------------+
30+
| `<iCs/>` | §17.3.2.17 | Complex Script Italics |
31+
+-----------------+------------+-------------------------------------------+
32+
| `<imprint/>` | §17.3.2.18 | Imprinting |
33+
+-----------------+------------+-------------------------------------------+
34+
| `<noProof/>` | §17.3.2.21 | Do Not Check Spelling or Grammar |
35+
+-----------------+------------+-------------------------------------------+
36+
| `<oMath/>` | §17.3.2.22 | Office Open XML Math |
37+
+-----------------+------------+-------------------------------------------+
38+
| `<outline/>` | §17.3.2.23 | Display Character Outline |
39+
+-----------------+------------+-------------------------------------------+
40+
| `<rtl/>` | §17.3.2.30 | Right To Left Text |
41+
+-----------------+------------+-------------------------------------------+
42+
| `<shadow/>` | §17.3.2.31 | Shadow |
43+
+-----------------+------------+-------------------------------------------+
44+
| `<smallCaps/>` | §17.3.2.33 | Small Caps |
45+
+-----------------+------------+-------------------------------------------+
46+
| `<snapToGrid/>` | §17.3.2.34 | Use Document Grid Settings For Inter- |
47+
| | | Character Spacing |
48+
+-----------------+------------+-------------------------------------------+
49+
| `<specVanish/>` | §17.3.2.36 | Paragraph Mark is Always Hidden |
50+
+-----------------+------------+-------------------------------------------+
51+
| `<strike/>` | §17.3.2.37 | Single Strikethrough |
52+
+-----------------+------------+-------------------------------------------+
53+
| `<vanish/>` | §17.3.2.41 | Hidden Text |
54+
+-----------------+------------+-------------------------------------------+
55+
| `<webHidden/>` | §17.3.2.44 | Web Hidden Text |
56+
+-----------------+------------+-------------------------------------------+
57+
58+
59+
Protocol
60+
--------
61+
62+
At the API level, each of the boolean run properties is a read/write
63+
'tri-state' property, having the possible values |True|, |False|, and |None|.
64+
65+
The following interactive session demonstrates the protocol for querying and
66+
applying run-level properties::
67+
68+
>>> run = p.add_run()
69+
>>> run.bold
70+
None
71+
>>> run.bold = True
72+
>>> run.bold
73+
True
74+
>>> run.bold = False
75+
>>> run.bold
76+
False
77+
>>> run.bold = None
78+
>>> run.bold
79+
None
80+
81+
The semantics of the three values are as follows:
82+
83+
+-------+-------------------------------------------------------------+
84+
| value | meaning |
85+
+=======+=============================================================+
86+
| True | The effective value of the property is unconditional *on*. |
87+
| | Contrary settings in the style hierarchy have no effect. |
88+
+-------+-------------------------------------------------------------+
89+
| False | The effective value of the property is unconditional *off*. |
90+
| | Contrary settings in the style hierarchy have no effect. |
91+
+-------+-------------------------------------------------------------+
92+
| None | The element is not present. The effective value is |
93+
| | inherited from the style hierarchy. If no value for this |
94+
| | property is present in the style hierarchy, the effective |
95+
| | value is *off*. |
96+
+-------+-------------------------------------------------------------+
97+
98+
99+
Specimen XML
100+
------------
101+
102+
.. highlight:: xml
103+
104+
::
105+
106+
<w:r w:rsidRPr="00FA3070">
107+
<w:rPr>
108+
<w:b/>
109+
<w:i/>
110+
<w:smallCaps/>
111+
<w:strike/>
112+
<w:sz w:val="28"/>
113+
<w:szCs w:val="28"/>
114+
<w:u w:val="single"/>
115+
</w:rPr>
116+
<w:t>bold, italic, small caps, strike, size, and underline, applied in
117+
reverse order but not to paragraph mark</w:t>
118+
</w:r>
119+
120+
121+
Schema excerpt
122+
--------------
123+
124+
.. highlight:: xml
125+
126+
It appears the run properties may appear in any order and may appear multiple
127+
times each. Not sure what the semantics of that would be or why one would
128+
want to do it, but something to note. Word seems to place them in the order
129+
below when it writes the file.::
130+
131+
<xsd:complexType name="CT_R"> <!-- denormalized -->
132+
<xsd:sequence>
133+
<xsd:element name="rPr" type="CT_RPr" minOccurs="0"/>
134+
<xsd:group ref="EG_RunInnerContent" minOccurs="0" maxOccurs="unbounded"/>
135+
</xsd:sequence>
136+
<xsd:attribute name="rsidRPr" type="ST_LongHexNumber"/>
137+
<xsd:attribute name="rsidDel" type="ST_LongHexNumber"/>
138+
<xsd:attribute name="rsidR" type="ST_LongHexNumber"/>
139+
</xsd:complexType>
140+
141+
<xsd:complexType name="CT_RPr">
142+
<xsd:sequence>
143+
<xsd:group ref="EG_RPrContent" minOccurs="0"/>
144+
</xsd:sequence>
145+
</xsd:complexType>
146+
147+
<xsd:group name="EG_RPrContent">
148+
<xsd:sequence>
149+
<xsd:group ref="EG_RPrBase" minOccurs="0" maxOccurs="unbounded"/>
150+
<xsd:element name="rPrChange" type="CT_RPrChange" minOccurs="0"/>
151+
</xsd:sequence>
152+
</xsd:group>
153+
154+
<xsd:group name="EG_RPrBase">
155+
<xsd:choice>
156+
<xsd:element name="rStyle" type="CT_String"/>
157+
<xsd:element name="rFonts" type="CT_Fonts"/>
158+
<xsd:element name="b" type="CT_OnOff"/>
159+
<xsd:element name="bCs" type="CT_OnOff"/>
160+
<xsd:element name="i" type="CT_OnOff"/>
161+
<xsd:element name="iCs" type="CT_OnOff"/>
162+
<xsd:element name="caps" type="CT_OnOff"/>
163+
<xsd:element name="smallCaps" type="CT_OnOff"/>
164+
<xsd:element name="strike" type="CT_OnOff"/>
165+
<xsd:element name="dstrike" type="CT_OnOff"/>
166+
<xsd:element name="outline" type="CT_OnOff"/>
167+
<xsd:element name="shadow" type="CT_OnOff"/>
168+
<xsd:element name="emboss" type="CT_OnOff"/>
169+
<xsd:element name="imprint" type="CT_OnOff"/>
170+
<xsd:element name="noProof" type="CT_OnOff"/>
171+
<xsd:element name="snapToGrid" type="CT_OnOff"/>
172+
<xsd:element name="vanish" type="CT_OnOff"/>
173+
<xsd:element name="webHidden" type="CT_OnOff"/>
174+
<xsd:element name="color" type="CT_Color"/>
175+
<xsd:element name="spacing" type="CT_SignedTwipsMeasure"/>
176+
<xsd:element name="w" type="CT_TextScale"/>
177+
<xsd:element name="kern" type="CT_HpsMeasure"/>
178+
<xsd:element name="position" type="CT_SignedHpsMeasure"/>
179+
<xsd:element name="sz" type="CT_HpsMeasure"/>
180+
<xsd:element name="szCs" type="CT_HpsMeasure"/>
181+
<xsd:element name="highlight" type="CT_Highlight"/>
182+
<xsd:element name="u" type="CT_Underline"/>
183+
<xsd:element name="effect" type="CT_TextEffect"/>
184+
<xsd:element name="bdr" type="CT_Border"/>
185+
<xsd:element name="shd" type="CT_Shd"/>
186+
<xsd:element name="fitText" type="CT_FitText"/>
187+
<xsd:element name="vertAlign" type="CT_VerticalAlignRun"/>
188+
<xsd:element name="rtl" type="CT_OnOff"/>
189+
<xsd:element name="cs" type="CT_OnOff"/>
190+
<xsd:element name="em" type="CT_Em"/>
191+
<xsd:element name="lang" type="CT_Language"/>
192+
<xsd:element name="eastAsianLayout" type="CT_EastAsianLayout"/>
193+
<xsd:element name="specVanish" type="CT_OnOff"/>
194+
<xsd:element name="oMath" type="CT_OnOff"/>
195+
</xsd:choice>
196+
</xsd:group>
197+
198+
<xsd:complexType name="CT_OnOff">
199+
<xsd:attribute name="val" type="s:ST_OnOff"/>
200+
</xsd:complexType>
201+
202+
<xsd:simpleType name="ST_OnOff">
203+
<xsd:union memberTypes="xsd:boolean ST_OnOff1"/>
204+
</xsd:simpleType>
205+
206+
<xsd:simpleType name="ST_OnOff1">
207+
<xsd:restriction base="xsd:string">
208+
<xsd:enumeration value="on"/>
209+
<xsd:enumeration value="off"/>
210+
</xsd:restriction>
211+
</xsd:simpleType>
212+
213+
214+
Toggle properties
215+
-----------------
216+
217+
Certain of the boolean run properties are *toggle properties*. A toggle
218+
property is one that behaves like a *toggle* at certain places in the style
219+
hierarchy. Toggle here means that setting the property on has the effect of
220+
reversing the prior setting rather than unconditionally setting the property
221+
on.
222+
223+
This behavior allows these properties to be overridden (turned off) in
224+
inheriting styles. For example, consider a character style `emphasized` that
225+
sets bold on. Another style, `strong` inherits from `emphasized`, but should
226+
display in italic rather than bold. Setting bold off has no effect because it
227+
is overridden by the bold in `strong` (I think). Because bold is a toggle
228+
property, setting bold on in `emphasized` causes its value to be toggled, to
229+
False, achieving the desired effect. See §17.7.3 for more details on toggle
230+
properties.
231+
232+
The following run properties are toggle properties:
233+
234+
+----------------+------------+-------------------------------------------+
235+
| element | spec | name |
236+
+================+============+===========================================+
237+
| `<b/>` | §17.3.2.1 | Bold |
238+
+----------------+------------+-------------------------------------------+
239+
| `<bCs/>` | §17.3.2.2 | Complex Script Bold |
240+
+----------------+------------+-------------------------------------------+
241+
| `<caps/>` | §17.3.2.5 | Display All Characters as Capital Letters |
242+
+----------------+------------+-------------------------------------------+
243+
| `<emboss/>` | §17.3.2.13 | Embossing |
244+
+----------------+------------+-------------------------------------------+
245+
| `<i/>` | §17.3.2.16 | Italics |
246+
+----------------+------------+-------------------------------------------+
247+
| `<iCs/>` | §17.3.2.17 | Complex Script Italics |
248+
+----------------+------------+-------------------------------------------+
249+
| `<imprint/>` | §17.3.2.18 | Imprinting |
250+
+----------------+------------+-------------------------------------------+
251+
| `<outline/>` | §17.3.2.23 | Display Character Outline |
252+
+----------------+------------+-------------------------------------------+
253+
| `<shadow/>` | §17.3.2.31 | Shadow |
254+
+----------------+------------+-------------------------------------------+
255+
| `<smallCaps/>` | §17.3.2.33 | Small Caps |
256+
+----------------+------------+-------------------------------------------+
257+
| `<strike/>` | §17.3.2.37 | Single Strikethrough |
258+
+----------------+------------+-------------------------------------------+
259+
| `<vanish/>` | §17.3.2.41 | Hidden Text |
260+
+----------------+------------+-------------------------------------------+
261+
262+
263+
Resources
264+
---------
265+
266+
* `WdBreakType Enumeration on MSDN`_
267+
* `Range.InsertBreak Method (Word) on MSDN`_
268+
269+
.. _WdBreakType Enumeration on MSDN:
270+
http://msdn.microsoft.com/en-us/library/office/ff195905.aspx
271+
272+
.. _Range.InsertBreak Method (Word) on MSDN:
273+
http://msdn.microsoft.com/en-us/library/office/ff835132.aspx

0 commit comments

Comments
 (0)