Skip to content

Commit a7d9915

Browse files
author
Steve Canny
committed
docs: document analysis for Document.add_section()
1 parent 65a59c6 commit a7d9915

File tree

1 file changed

+163
-99
lines changed

1 file changed

+163
-99
lines changed

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

Lines changed: 163 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -9,32 +9,49 @@ from line, page, and column breaks. The former adds a ``<w:pPr><w:sectPr>``
99
element to the last paragraph in the new section. The latter inserts
1010
a ``<w:br>`` element in a run.
1111

12+
The last section in a document is specified by a ``<w:sectPr>`` element
13+
appearing as the last child of the ``<w:body>`` element. While this element
14+
is optional, it appears that Word creates it for all files. Since most files
15+
have only a single section, the most common case is where this is the only
16+
``<w:sectPr>`` element.
1217

13-
Implementation notes
14-
--------------------
18+
Additional sections are specified by a ``w:p/w:pPr/w:sectPr`` element in the
19+
last paragraph of the section. Any content in that paragraph is part of the
20+
section defined by its ``<w:sectPr>`` element. The subsequent section begins
21+
with the following paragraph.
1522

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
18-
are probably:
23+
When a section break is inserted using the Word UI, the following steps
24+
occur:
1925

20-
* page size
21-
* margins
26+
1. The next-occurring ``<w:sectPr>`` element is copied and added to the
27+
current paragraph. (It would be interesting to see what happens when that
28+
paragraph already has a ``<w:sectPr>`` element.)
29+
2. A new paragraph is inserted after the current paragraph. The text occuring
30+
after the cursor position is moved to the new paragraph.
31+
3. The start-type (e.g. next page) of the next-occuring ``<w:sectPr>``
32+
element is changed to reflect the type chosen by the user from the UI.
2233

23-
The other thing it will entail is locating the next ``<w:sectPr>`` element in
24-
document order and copying its child elements.
2534

26-
I'm thinking the sequence is:
35+
Candidate protocol
36+
------------------
2737

28-
1. document.sections
29-
2. section page setup properties
30-
3. paragraph.make_section_break() (or whatever, something better perhaps)
38+
The following interactive session demonstrates the proposed protocol for
39+
inserting a section break, illustrating adding a landscape section after an
40+
existing portrait section::
3141

42+
>>> section_1 = document.sections[0]
43+
>>> document.add_paragraph('This paragraph appears in section 1.')
44+
>>> section_2 = document.add_section(WD_SECTION.EVEN_PAGE)
45+
>>> section_2.orientation
46+
PORTRAIT (0)
47+
>>> section_2.orientation = WD_ORIENT.LANDSCAPE
48+
>>> section_2.page_width = section_1.page_height
49+
>>> section_2.page_height = section_1.page_width
50+
>>> document.add_paragraph('This paragraph appears in section 2.')
3251

33-
Candidate protocol
34-
------------------
3552

3653
The following interactive session demonstrates the proposed protocol for
37-
working with sections::
54+
setting section properties::
3855

3956
>>> sections = document.sections
4057
>>> sections
@@ -66,52 +83,155 @@ working with sections::
6683
Word behavior
6784
-------------
6885

69-
When inserting a section break in Word, there is no dialog box presented and no
70-
parameters are supplied. Word simply copies the section details from the
71-
current section (the next ``<w:sectPr>`` element in the document) to provide
72-
the starting point. Experimentation would be required to determine exactly what
73-
items are copied, but it at least includes the page size, margins, and column
74-
spacing.
86+
* A paragraph containing a section break (<w:sectPr> element) does not
87+
produce a ¶ glyph in the Word UI.
88+
* The section break indicator/double-line appears directly after the text of
89+
the paragraph in which the <w:sectPr> appears. If the section break
90+
paragraph has no text, the indicator line appears immediately after the
91+
paragraph mark of the prior paragraph.
92+
93+
94+
Before and after analysis
95+
~~~~~~~~~~~~~~~~~~~~~~~~~
96+
97+
.. highlight:: xml
98+
99+
Baseline document containing two paragraphs::
100+
101+
<w:body>
102+
<w:p>
103+
<w:r>
104+
<w:t>Paragraph 1</w:t>
105+
</w:r>
106+
</w:p>
107+
<w:p>
108+
<w:r>
109+
<w:t>Paragraph 2</w:t>
110+
</w:r>
111+
</w:p>
112+
<w:sectPr>
113+
<w:pgSz w:w="12240" w:h="15840"/>
114+
<w:pgMar w:top="1440" w:right="1800" w:bottom="1440" w:left="1800"
115+
w:header="720" w:footer="720" w:gutter="0"/>
116+
<w:cols w:space="720"/>
117+
<w:docGrid w:linePitch="360"/>
118+
</w:sectPr>
119+
</w:body>
120+
121+
122+
Odd-page section inserted before paragraph mark in Paragraph 1::
123+
124+
<w:body>
125+
<w:p>
126+
<w:pPr>
127+
<w:sectPr>
128+
<w:pgSz w:w="12240" w:h="15840"/>
129+
<w:pgMar w:top="1440" w:right="1800" w:bottom="1440" w:left="1800"
130+
w:header="720" w:footer="720" w:gutter="0"/>
131+
<w:cols w:space="720"/>
132+
<w:docGrid w:linePitch="360"/>
133+
</w:sectPr>
134+
</w:pPr>
135+
<w:r>
136+
<w:t>Paragraph 1</w:t>
137+
</w:r>
138+
</w:p>
139+
<w:p/>
140+
<w:p>
141+
<w:r>
142+
<w:t>Paragraph 2</w:t>
143+
</w:r>
144+
</w:p>
145+
<w:sectPr w:rsidR="00F039D0" w:rsidSect="006006E7">
146+
<w:type w:val="oddPage"/>
147+
<w:pgSz w:w="12240" w:h="15840"/>
148+
<w:pgMar w:top="1440" w:right="1800" w:bottom="1440" w:left="1800"
149+
w:header="720" w:footer="720" w:gutter="0"/>
150+
<w:cols w:space="720"/>
151+
<w:docGrid w:linePitch="360"/>
152+
</w:sectPr>
153+
</w:body>
154+
155+
UI shows empty ¶ mark in first position of new next page. Section break
156+
indicator appears directly after Paragraph 1 text, with no intervening
157+
¶ mark.
158+
159+
160+
Even-page section break inserted before first character in Paragraph 2::
161+
162+
<w:body>
163+
<w:p>
164+
<w:r>
165+
<w:t>Paragraph 1</w:t>
166+
</w:r>
167+
</w:p>
168+
<w:p>
169+
<w:pPr>
170+
<w:sectPr>
171+
<w:type w:val="oddPage"/>
172+
<w:pgSz w:w="12240" w:h="15840"/>
173+
<w:pgMar w:top="1440" w:right="1800" w:bottom="1440" w:left="1800"
174+
w:header="720" w:footer="720" w:gutter="0"/>
175+
<w:cols w:space="720"/>
176+
<w:docGrid w:linePitch="360"/>
177+
</w:sectPr>
178+
</w:pPr>
179+
</w:p>
180+
<w:p>
181+
<w:r>
182+
<w:lastRenderedPageBreak/>
183+
<w:t>Paragraph 2</w:t>
184+
</w:r>
185+
</w:p>
186+
<w:sectPr>
187+
<w:type w:val="evenPage"/>
188+
<w:pgSz w:w="12240" w:h="15840"/>
189+
<w:pgMar w:top="1440" w:right="1800" w:bottom="1440" w:left="1800"
190+
w:header="720" w:footer="720" w:gutter="0"/>
191+
<w:cols w:space="720"/>
192+
<w:docGrid w:linePitch="360"/>
193+
</w:sectPr>
194+
</w:body>
75195

76196

77197
Enumerations
78198
------------
79199

80-
* `WdSectionStart Enumeration on MSDN`_
200+
WD_SECTION_START
201+
~~~~~~~~~~~~~~~~
81202

82-
.. _WdSectionStart Enumeration on MSDN:
83-
http://msdn.microsoft.com/en-us/library/office/bb238171.aspx
203+
alias: **WD_SECTION**
84204

85-
::
205+
`WdSectionStart Enumeration on MSDN`_
86206

87-
@alias(WD_SECTION)
88-
class WD_SECTION_START(Enumeration):
207+
.. _WdSectionStart Enumeration on MSDN:
208+
http://msdn.microsoft.com/en-us/library/office/bb238171.aspx
89209

90210
CONTINUOUS (0)
91211
Continuous section break.
92212

93-
EVENPAGE (3)
94-
Even pages section break.
95-
96-
NEWCOLUMN (1)
213+
NEW_COLUMN (1)
97214
New column section break.
98215

99-
NEWPAGE (2)
216+
NEW_PAGE (2)
100217
New page section break.
101218

102-
ODDPAGE (4)
219+
EVEN_PAGE (3)
220+
Even pages section break.
221+
222+
ODD_PAGE (4)
103223
Odd pages section break.
104224

105225

106-
* `WdOrientation Enumeration on MSDN`_
226+
WD_ORIENTATION
227+
~~~~~~~~~~~~~~
107228

108-
.. _WdOrientation Enumeration on MSDN:
109-
http://msdn.microsoft.com/en-us/library/office/ff837902.aspx
229+
alias: **WD_ORIENT**
110230

111-
::
231+
`WdOrientation Enumeration on MSDN`_
112232

113-
@alias(WD_ORIENT)
114-
class WD_ORIENTATION(Enumeration):
233+
.. _WdOrientation Enumeration on MSDN:
234+
http://msdn.microsoft.com/en-us/library/office/ff837902.aspx
115235

116236
LANDSCAPE (1)
117237
Landscape orientation.
@@ -120,29 +240,6 @@ PORTRAIT (0)
120240
Portrait orientation.
121241

122242

123-
Specimen XML
124-
------------
125-
126-
.. highlight:: xml
127-
128-
Inserting a section break (next page) produces this XML::
129-
130-
<w:p>
131-
<w:pPr>
132-
<w:sectPr>
133-
<w:type w:val="oddPage"/>
134-
<w:pgSz w:w="12240" w:h="15840"/>
135-
<w:pgMar w:top="1440" w:right="1800" w:bottom="1440" w:left="1800" w:header="720" w:footer="720" w:gutter="0"/>
136-
<w:cols w:space="720"/>
137-
<w:docGrid w:linePitch="360"/>
138-
</w:sectPr>
139-
</w:pPr>
140-
<w:r>
141-
<w:t>Text before section break insertion point}</w:t>
142-
</w:r>
143-
</w:p>
144-
145-
146243
Schema excerpt
147244
--------------
148245

@@ -152,42 +249,9 @@ Schema excerpt
152249

153250
<xsd:complexType name="CT_PPr"> <!-- denormalized -->
154251
<xsd:sequence>
155-
<xsd:element name="pStyle" type="CT_String" minOccurs="0"/>
156-
<xsd:element name="keepNext" type="CT_OnOff" minOccurs="0"/>
157-
<xsd:element name="keepLines" type="CT_OnOff" minOccurs="0"/>
158-
<xsd:element name="pageBreakBefore" type="CT_OnOff" minOccurs="0"/>
159-
<xsd:element name="framePr" type="CT_FramePr" minOccurs="0"/>
160-
<xsd:element name="widowControl" type="CT_OnOff" minOccurs="0"/>
161-
<xsd:element name="numPr" type="CT_NumPr" minOccurs="0"/>
162-
<xsd:element name="suppressLineNumbers" type="CT_OnOff" minOccurs="0"/>
163-
<xsd:element name="pBdr" type="CT_PBdr" minOccurs="0"/>
164-
<xsd:element name="shd" type="CT_Shd" minOccurs="0"/>
165-
<xsd:element name="tabs" type="CT_Tabs" minOccurs="0"/>
166-
<xsd:element name="suppressAutoHyphens" type="CT_OnOff" minOccurs="0"/>
167-
<xsd:element name="kinsoku" type="CT_OnOff" minOccurs="0"/>
168-
<xsd:element name="wordWrap" type="CT_OnOff" minOccurs="0"/>
169-
<xsd:element name="overflowPunct" type="CT_OnOff" minOccurs="0"/>
170-
<xsd:element name="topLinePunct" type="CT_OnOff" minOccurs="0"/>
171-
<xsd:element name="autoSpaceDE" type="CT_OnOff" minOccurs="0"/>
172-
<xsd:element name="autoSpaceDN" type="CT_OnOff" minOccurs="0"/>
173-
<xsd:element name="bidi" type="CT_OnOff" minOccurs="0"/>
174-
<xsd:element name="adjustRightInd" type="CT_OnOff" minOccurs="0"/>
175-
<xsd:element name="snapToGrid" type="CT_OnOff" minOccurs="0"/>
176-
<xsd:element name="spacing" type="CT_Spacing" minOccurs="0"/>
177-
<xsd:element name="ind" type="CT_Ind" minOccurs="0"/>
178-
<xsd:element name="contextualSpacing" type="CT_OnOff" minOccurs="0"/>
179-
<xsd:element name="mirrorIndents" type="CT_OnOff" minOccurs="0"/>
180-
<xsd:element name="suppressOverlap" type="CT_OnOff" minOccurs="0"/>
181-
<xsd:element name="jc" type="CT_Jc" minOccurs="0"/>
182-
<xsd:element name="textDirection" type="CT_TextDirection" minOccurs="0"/>
183-
<xsd:element name="textAlignment" type="CT_TextAlignment" minOccurs="0"/>
184-
<xsd:element name="textboxTightWrap" type="CT_TextboxTightWrap" minOccurs="0"/>
185-
<xsd:element name="outlineLvl" type="CT_DecimalNumber" minOccurs="0"/>
186-
<xsd:element name="divId" type="CT_DecimalNumber" minOccurs="0"/>
187-
<xsd:element name="cnfStyle" type="CT_Cnf" minOccurs="0"/>
188-
<xsd:element name="rPr" type="CT_ParaRPr" minOccurs="0"/>
189-
<xsd:element name="sectPr" type="CT_SectPr" minOccurs="0"/>
190-
<xsd:element name="pPrChange" type="CT_PPrChange" minOccurs="0"/>
252+
<!-- 34 others ... -->
253+
<xsd:element name="sectPr" type="CT_SectPr" minOccurs="0"/>
254+
<xsd:element name="pPrChange" type="CT_PPrChange" minOccurs="0"/>
191255
</xsd:sequence>
192256
</xsd:complexType>
193257

0 commit comments

Comments
 (0)