Skip to content

Commit fdca6ea

Browse files
eupharisscanny
eupharis
authored and
scanny
committed
docs: update header/footer analysis
1 parent 5dcb24c commit fdca6ea

File tree

2 files changed

+125
-37
lines changed

2 files changed

+125
-37
lines changed

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

Lines changed: 65 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -3,39 +3,54 @@
33
Header and Footer
44
=================
55

6-
In a WordprocessingML document, a page header is text that is separated from
7-
the main body of text and appears at the top of a printed page. The page
8-
headers in a document are often the same from page to page, with only small
9-
differences in content, such as a section title or page number. Such a header
10-
is also known as a running head.
11-
12-
In book-printed documents, where pages are intended to be bound on the long
13-
edge and presented side-by-side, the header on a right-hand (recto) page is
14-
often different than that on a left-hand (verso) page. Supporting this
15-
difference gives rise to the option to have an even-page header that differs
16-
from the default odd-page header in a document.
17-
18-
A page footer is analogous in every way to a page header except that it
19-
appears at the bottom of a page. It should not be confused with a footnote,
20-
which is not uniform between pages. For brevity's sake, the term *header* is
21-
often used below to refer to what may be either a header or footer object,
22-
trusting the reader to understand its applicability to both object types.
23-
24-
In WordprocessingML, a header or footer appears within the margin area of
25-
a page. With a few exceptions, a header or footer may contain all the types
26-
of content that can appear in the main body, including text and images. Each
27-
header and footer has access to the styles defined in ``/word/styles.xml``.
28-
29-
Each section has its own set of headers and footers, although a section can
30-
be configured to "inherit" headers and footers from the prior section. Each
31-
section can have three header definitions, the default header, even header,
32-
and first page header. When different even/odd headers are not enabled, the
33-
default header appears on both even and odd numbered pages. If even/odd
34-
headers are enabled, the default header is used for odd pages.
35-
A corresponding set of three footer definitions are also possible. All
6+
In a WordprocessingML document, a page header is text that is separated from the main
7+
body of text and appears at the top of a printed page. The page headers in a document
8+
are often the same from page to page, with only small differences in content, such as
9+
a section title or page number. Such a header is also known as a running head.
10+
11+
A page footer is analogous in every way to a page header except that it appears at the
12+
bottom of a page. It should not be confused with a footnote, which is not uniform
13+
between pages. For brevity's sake, the term *header* is often used here to refer to what
14+
may be either a header or footer object, trusting the reader to understand its
15+
applicability to both object types.
16+
17+
In book-printed documents, where pages are printed on both sides, when opened, the front
18+
or *recto* side of each page appears to the right of the bound edge and the back or
19+
*verso* side of each page appears on the left. The first printed page receives the
20+
page-number "1", and is always a recto page. Because pages are numbered consecutively,
21+
each recto page receives an *odd* page number and each verso page receives an *even*
22+
page number.
23+
24+
The header appearing on a recto page often differs from that on a verso page. Supporting
25+
this difference gives rise to the option to have an even-page header that differs from
26+
the default odd-page header in a document. This "both odd-and-even headers" option is
27+
applied at the document level and affects all sections of the document.
28+
29+
The header appearing on the first page of a section (e.g. a chapter) may differ from
30+
that appearing on subsequent pages. Supporting this difference gives rise to the option
31+
to set a distinct first-page header. This "different first-page-header" option is
32+
applied at the section level and may differ from section-to-section in the document.
33+
34+
In WordprocessingML, a header or footer appears within the margin area of a page. With
35+
a few exceptions, a header or footer may contain all the types of content that can
36+
appear in the main body, including text and images. Each header and footer has access to
37+
the styles defined in ``/word/styles.xml``.
38+
39+
Each section has its own set of headers and footers, although a section can be
40+
configured to "inherit" headers and footers from the prior section. Each section can
41+
have three header definitions, the default header, even header, and first page header.
42+
When different even/odd headers are not enabled, the default header appears on both even
43+
and odd numbered pages. If even/odd headers are enabled, the default header is used for
44+
odd pages. A corresponding set of three footer definitions are also possible. All
3645
header/footer definitions are optional.
3746

3847

48+
Open Questions
49+
--------------
50+
51+
* What about a continuous section break? What is the header/footer behavior there?
52+
53+
3954
Candidate Protocol
4055
------------------
4156

@@ -96,12 +111,12 @@ Conversely, an existing header is deleted from a section by assigning True to
96111
>>> header.is_linked_to_previous
97112
True
98113

99-
The document settings object has a read/write
100-
`.odd_and_even_pages_header_footer` property that indicates verso and recto
101-
pages will have a different header. An existing even page header definition is
102-
preserved when `.odd_and_even_pages_header_footer` is False; it is simply not
103-
rendered by Word. Assigning `True` to `.odd_and_even_pages_header_footer`
104-
does not automatically create a new even header definition::
114+
The document settings object has a read/write `.odd_and_even_pages_header_footer`
115+
property that indicates verso and recto pages will have a different header. Any existing
116+
even page header definitions are preserved when `.odd_and_even_pages_header_footer` is
117+
False; they are simply not rendered by Word. Assigning `True` to
118+
`.odd_and_even_pages_header_footer` does not automatically create new even header
119+
definitions::
105120

106121
>>> document.settings.odd_and_even_pages_header_footer
107122
False
@@ -174,6 +189,19 @@ Distinct first, even, and odd page headers::
174189
...
175190
</w:sectPr>
176191

192+
A header part::
193+
194+
<w:hdr>
195+
<w:p>
196+
<w:pPr>
197+
<w:pStyle w:val="Header"/>
198+
</w:pPr>
199+
<w:r>
200+
<w:t>Header for section-1</w:t>
201+
</w:r>
202+
</w:p>
203+
</w:hdr>
204+
177205

178206
Word Behavior
179207
-------------
@@ -250,7 +278,7 @@ Schema Excerpt
250278
</xsd:complexType>
251279
252280
<xsd:complexType name="CT_HdrFtrRef">
253-
<xsd:attribute ref="r:id" use="required"/>
281+
<xsd:attribute ref="r:id" use="required"/>
254282
<xsd:attribute name="type" type="ST_HdrFtr" use="required"/>
255283
</xsd:complexType>
256284

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

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,66 @@ Candidate Protocol
2525
<docx.settings.Settings object at 0xdeadbeef4>
2626

2727

28+
Specimen XML
29+
------------
30+
31+
.. highlight:: xml
32+
33+
Default `settings.xml` part for a new document in Word 2016::
34+
35+
<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
36+
<w:settings
37+
xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math"
38+
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
39+
xmlns:o="urn:schemas-microsoft-com:office:office"
40+
xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"
41+
xmlns:sl="http://schemas.openxmlformats.org/schemaLibrary/2006/main"
42+
xmlns:v="urn:schemas-microsoft-com:vml"
43+
xmlns:w10="urn:schemas-microsoft-com:office:word"
44+
xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml"
45+
xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml"
46+
xmlns:w16cid="http://schemas.microsoft.com/office/word/2016/wordml/cid"
47+
xmlns:w16se="http://schemas.microsoft.com/office/word/2015/wordml/symex"
48+
xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
49+
mc:Ignorable="w14 w15 w16se w16cid"
50+
>
51+
<w:zoom w:percent="150"/>
52+
<w:defaultTabStop w:val="720"/>
53+
<w:characterSpacingControl w:val="doNotCompress"/>
54+
<w:compat>
55+
<w:compatSetting w:name="compatibilityMode" w:uri="http://schemas.microsoft.com/office/word" w:val="15"/>
56+
<w:compatSetting w:name="overrideTableStyleFontSizeAndJustification" w:uri="http://schemas.microsoft.com/office/word" w:val="1"/>
57+
<w:compatSetting w:name="enableOpenTypeFeatures" w:uri="http://schemas.microsoft.com/office/word" w:val="1"/>
58+
<w:compatSetting w:name="doNotFlipMirrorIndents" w:uri="http://schemas.microsoft.com/office/word" w:val="1"/>
59+
<w:compatSetting w:name="differentiateMultirowTableHeaders" w:uri="http://schemas.microsoft.com/office/word" w:val="1"/>
60+
<w:compatSetting w:name="useWord2013TrackBottomHyphenation" w:uri="http://schemas.microsoft.com/office/word" w:val="0"/>
61+
</w:compat>
62+
<w:rsids>
63+
<w:rsidRoot w:val="005968A6"/>
64+
<w:rsid w:val="00480A2E"/>
65+
<w:rsid w:val="005968A6"/>
66+
</w:rsids>
67+
<m:mathPr>
68+
<m:mathFont m:val="Cambria Math"/>
69+
<m:brkBin m:val="before"/>
70+
<m:brkBinSub m:val="--"/>
71+
<m:smallFrac m:val="0"/>
72+
<m:dispDef/>
73+
<m:lMargin m:val="0"/>
74+
<m:rMargin m:val="0"/>
75+
<m:defJc m:val="centerGroup"/>
76+
<m:wrapIndent m:val="1440"/>
77+
<m:intLim m:val="subSup"/>
78+
<m:naryLim m:val="undOvr"/>
79+
</m:mathPr>
80+
<w:themeFontLang w:val="en-US"/>
81+
<w:clrSchemeMapping w:bg1="light1" w:t1="dark1" w:bg2="light2" w:t2="dark2" w:accent1="accent1" w:accent2="accent2" w:accent3="accent3" w:accent4="accent4" w:accent5="accent5" w:accent6="accent6" w:hyperlink="hyperlink" w:followedHyperlink="followedHyperlink"/>
82+
<w:decimalSymbol w:val="."/>
83+
<w:listSeparator w:val=","/>
84+
<w15:chartTrackingRefBased/>
85+
<w15:docId w15:val="{3E989880-FF70-7C4D-8D4E-02DC7E104B81}"/>
86+
</w:settings>
87+
2888
Schema Excerpts
2989
---------------
3090

0 commit comments

Comments
 (0)