Skip to content

Commit 597617a

Browse files
author
Steve Canny
committed
docs: document feature analysis for sections
1 parent 15fbe51 commit 597617a

File tree

2 files changed

+206
-185
lines changed

2 files changed

+206
-185
lines changed

‎docs/dev/analysis/features/sections.rst‎

Lines changed: 168 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@ a ``<w:br>`` element in a run.
1313
Implementation notes
1414
--------------------
1515

16-
It's probably not going to make a lot of sense to implement this before having
17-
the ability to set at least a core subset of the section properties. First ones
16+
Implementing adding a section break should probably wait until after the
17+
ability to set at least a core subset of the section properties. First ones
1818
are probably:
1919

2020
* page size
@@ -33,19 +33,34 @@ I'm thinking the sequence is:
3333
Candidate protocol
3434
------------------
3535

36-
The following interactive session demonstrates the protocol for working with
37-
sections::
36+
The following interactive session demonstrates the proposed protocol for
37+
working with sections::
3838

3939
>>> sections = document.sections
40+
>>> sections
41+
<docx.section.Sections object at 0x1deadbeef>
4042
>>> len(sections)
4143
3
42-
>>> first_section = sections[0]
43-
>>> last_section = sections[-1]
44-
45-
>>> p = body.add_paragraph()
46-
>>> p.section_properties
47-
None
48-
>>> p.add_section_break()
44+
>>> section = sections[-1] # the sentinel section
45+
>>> section
46+
<docx.section.Section object at 0x1deadbeef>
47+
>>> section.section_start
48+
WD_SECTION.CONTINUOUS (0)
49+
>>> page_setup = section.page_setup
50+
>>> page_setup
51+
<docx.section.PageSetup object at 0x1deadbeef>
52+
>>> page_setup.page_width
53+
7772400 # Inches(8.5)
54+
>>> page_setup.page_height
55+
10058400 # Inches(11)
56+
>>> page_setup.orientation
57+
WD_ORIENT.PORTRAIT
58+
>>> page_setup.left_margin # and .right_, .top_, .bottom_
59+
914400
60+
>>> page_setup.header_distance # and .footer_distance
61+
457200 # Inches(0.5)
62+
>>> page_setup.gutter
63+
0
4964

5065

5166
Word behavior
@@ -59,6 +74,73 @@ items are copied, but it at least includes the page size, margins, and column
5974
spacing.
6075

6176

77+
Enumerations
78+
------------
79+
80+
* `WdSectionStart Enumeration on MSDN`_
81+
82+
.. _WdSectionStart Enumeration on MSDN:
83+
http://msdn.microsoft.com/en-us/library/office/bb238171.aspx
84+
85+
::
86+
87+
@alias(WD_SECTION)
88+
class WD_SECTION_START(Enumeration):
89+
90+
CONTINUOUS (0)
91+
Continuous section break.
92+
93+
EVENPAGE (3)
94+
Even pages section break.
95+
96+
NEWCOLUMN (1)
97+
New column section break.
98+
99+
NEWPAGE (2)
100+
New page section break.
101+
102+
ODDPAGE (4)
103+
Odd pages section break.
104+
105+
106+
* `WdOrientation Enumeration on MSDN`_
107+
108+
.. _WdOrientation Enumeration on MSDN:
109+
http://msdn.microsoft.com/en-us/library/office/ff837902.aspx
110+
111+
::
112+
113+
@alias(WD_ORIENT)
114+
class WD_ORIENTATION(Enumeration):
115+
116+
LANDSCAPE (1)
117+
Landscape orientation.
118+
119+
PORTRAIT (0)
120+
Portrait orientation.
121+
122+
::
123+
124+
@alias(WD_SECTION)
125+
class WD_SECTION_START(Enumeration):
126+
127+
CONTINUOUS (0)
128+
Continuous section break.
129+
130+
EVENPAGE (3)
131+
Even pages section break.
132+
133+
NEWCOLUMN (1)
134+
New column section break.
135+
136+
NEWPAGE (2)
137+
New page section break.
138+
139+
ODDPAGE (4)
140+
Odd pages section break.
141+
142+
143+
62144
Specimen XML
63145
------------
64146

@@ -131,7 +213,10 @@ Schema excerpt
131213

132214
<xsd:complexType name="CT_SectPr"> <!-- denormalized -->
133215
<xsd:sequence>
134-
<xsd:group ref="EG_HdrFtrReferences" minOccurs="0" maxOccurs="6"/>
216+
<xsd:choice minOccurs="0" maxOccurs="6"/>
217+
<xsd:element name="headerReference" type="CT_HdrFtrRef"/>
218+
<xsd:element name="footerReference" type="CT_HdrFtrRef"/>
219+
</xsd:choice>
135220
<xsd:element name="footnotePr" type="CT_FtnProps" minOccurs="0"/>
136221
<xsd:element name="endnotePr" type="CT_EdnProps" minOccurs="0"/>
137222
<xsd:element name="type" type="CT_SectType" minOccurs="0"/>
@@ -153,19 +238,78 @@ Schema excerpt
153238
<xsd:element name="printerSettings" type="CT_Rel" minOccurs="0"/>
154239
<xsd:element name="sectPrChange" type="CT_SectPrChange" minOccurs="0"/>
155240
</xsd:sequence>
156-
<xsd:attributeGroup ref="AG_SectPrAttributes"/>
157-
</xsd:complexType>
158-
159-
<xsd:group name="EG_HdrFtrReferences">
160-
<xsd:choice>
161-
<xsd:element name="headerReference" type="CT_HdrFtrRef" minOccurs="0"/>
162-
<xsd:element name="footerReference" type="CT_HdrFtrRef" minOccurs="0"/>
163-
</xsd:choice>
164-
</xsd:group>
165-
166-
<xsd:attributeGroup name="AG_SectPrAttributes">
167241
<xsd:attribute name="rsidRPr" type="ST_LongHexNumber"/>
168242
<xsd:attribute name="rsidDel" type="ST_LongHexNumber"/>
169243
<xsd:attribute name="rsidR" type="ST_LongHexNumber"/>
170244
<xsd:attribute name="rsidSect" type="ST_LongHexNumber"/>
171-
</xsd:attributeGroup>
245+
</xsd:complexType>
246+
247+
<xsd:complexType name="CT_HdrFtrRef">
248+
<xsd:attribute ref="r:id" use="required"/>
249+
<xsd:attribute name="type" type="ST_HdrFtr" use="required"/>
250+
</xsd:complexType>
251+
252+
<xsd:simpleType name="ST_HdrFtr">
253+
<xsd:restriction base="xsd:string">
254+
<xsd:enumeration value="even"/>
255+
<xsd:enumeration value="default"/>
256+
<xsd:enumeration value="first"/>
257+
</xsd:restriction>
258+
</xsd:simpleType>
259+
260+
<xsd:complexType name="CT_SectType">
261+
<xsd:attribute name="val" type="ST_SectionMark"/>
262+
</xsd:complexType>
263+
264+
<xsd:simpleType name="ST_SectionMark">
265+
<xsd:restriction base="xsd:string">
266+
<xsd:enumeration value="nextPage"/>
267+
<xsd:enumeration value="nextColumn"/>
268+
<xsd:enumeration value="continuous"/>
269+
<xsd:enumeration value="evenPage"/>
270+
<xsd:enumeration value="oddPage"/>
271+
</xsd:restriction>
272+
</xsd:simpleType>
273+
274+
<xsd:complexType name="CT_PageSz">
275+
<xsd:attribute name="w" type="s:ST_TwipsMeasure"/>
276+
<xsd:attribute name="h" type="s:ST_TwipsMeasure"/>
277+
<xsd:attribute name="orient" type="ST_PageOrientation"/>
278+
<xsd:attribute name="code" type="ST_DecimalNumber"/>
279+
</xsd:complexType>
280+
281+
<xsd:simpleType name="ST_PageOrientation">
282+
<xsd:restriction base="xsd:string">
283+
<xsd:enumeration value="portrait"/>
284+
<xsd:enumeration value="landscape"/>
285+
</xsd:restriction>
286+
</xsd:simpleType>
287+
288+
<xsd:complexType name="CT_PageMar">
289+
<xsd:attribute name="top" type="ST_SignedTwipsMeasure" use="required"/>
290+
<xsd:attribute name="right" type="s:ST_TwipsMeasure" use="required"/>
291+
<xsd:attribute name="bottom" type="ST_SignedTwipsMeasure" use="required"/>
292+
<xsd:attribute name="left" type="s:ST_TwipsMeasure" use="required"/>
293+
<xsd:attribute name="header" type="s:ST_TwipsMeasure" use="required"/>
294+
<xsd:attribute name="footer" type="s:ST_TwipsMeasure" use="required"/>
295+
<xsd:attribute name="gutter" type="s:ST_TwipsMeasure" use="required"/>
296+
</xsd:complexType>
297+
298+
<xsd:simpleType name="ST_SignedTwipsMeasure">
299+
<xsd:union memberTypes="xsd:integer s:ST_UniversalMeasure"/>
300+
</xsd:simpleType>
301+
302+
<xsd:complexType name="CT_Columns">
303+
<xsd:sequence minOccurs="0">
304+
<xsd:element name="col" type="CT_Column" maxOccurs="45"/>
305+
</xsd:sequence>
306+
<xsd:attribute name="equalWidth" type="s:ST_OnOff"/>
307+
<xsd:attribute name="space" type="s:ST_TwipsMeasure"/>
308+
<xsd:attribute name="num" type="ST_DecimalNumber"/>
309+
<xsd:attribute name="sep" type="s:ST_OnOff"/>
310+
</xsd:complexType>
311+
312+
<xsd:complexType name="CT_Column">
313+
<xsd:attribute name="w" type="s:ST_TwipsMeasure"/>
314+
<xsd:attribute name="space" type="s:ST_TwipsMeasure"/>
315+
</xsd:complexType>

0 commit comments

Comments
 (0)