diff --git a/docs/dev/analysis/features/header-footer-2.rst b/docs/dev/analysis/features/header-footer-2.rst new file mode 100644 index 000000000..b62382163 --- /dev/null +++ b/docs/dev/analysis/features/header-footer-2.rst @@ -0,0 +1,185 @@ +================= +Header and Footer +================= + +In a WordprocessingML document, a page header is text that is separated from +the main body of text and appears at the top of a printed page. The page +headers in a document are often the same from page to page, with only small +differences in content, such as a section and/or page number. Such a header is +also known as a running head. + +In book-printed documents, where pages are intended to bound on the long edge +and presented side-by-side, the header on the right-hand (recto) pages is often +different than that on the left-hand (verso) pages. The need to support this +difference gives rise to the option to have an even-page header that differs +from the default odd-page header in a document. + +A page footer is analogous in every way to a page header except that it appears +at the bottom of a page. It should not be confused with a footnote, which is +not uniform between pages. + +In WordprocessingML, a header or footer appears within the margin area of a +page. With a few exceptions, a header or footer can contain all types of +content that can appear in the main body, including text and images. Each +section has its own set of headers and footers, although a section can be +configured to "inherit" headers and footers from the prior section. + +Each section can have three distinct header definitions and footer definitions. +These apply to odd pages (the default), even pages, and the first page of the +section. All three are optional. + +For brevity in the discussion below I will occasionally use the term *header* +to refer to either a header and footer object, trusting the reader to +understand its applicability to either type of object. + +Note on Styles: +--------------- + +The header and footer has access to all the normal styles defined in +``/word/styles.xml``. + +Candidate Protocol +================== + +TODO + +Specimen XML +============ + +There are seven different permutations of headers: + +This most basic scenario a single header on all pages of the document: + +.. code-block:: xml + + + + + ... + + + +Now just an odd header. The section is exactly the same as above but `settings.xml`: + +.. code-block:: xml + + + + + +Now both even and odd header. `settings.xml` still has `w:evenAndOddHeaders` +and the section looks like this: + +.. code-block:: xml + + + + + + ... + + +One header appears on the first page, and a different header on all subsequent pages: + +.. code-block:: xml + + + + + + ... + + +In this scenario one header appears on the first page, and then alternating even/odd headers appear on all subsequent pages. + +The ``settings.xml`` contains the ``w:evenAndOddHeaders`` element. + +.. code-block:: xml + + + + + + + ... + + +To better understand the header / footer XML, see also: +`Header Part `_ + +XML Semantics +============= + +`` seems to work equivalently to `` + +`` seems to work equivalently to `` + +TODO: confirm. + +Word Behavior +============= + +When you turn off even/odd headers, Word sets the value of +`w:evenAndOddHeaders` to 0, but does not actually remove the even header. + +When you turn off first page header, Word sets the value of +`w:titlePg` to 0, but does not actually remove the even header. + +Word will load a file with an even page header but no odd page header. + +MS API +====== + +WdHeaderFooterIndex Enumeration + +.. code-block:: python + + EVEN_PAGES = 3 + FIRST_PAGE = 2 + PRIMARY = 1 + +.. code-block:: python + + section = Document.Sections(1) + footers = section.Footers # a HeadersFooters collection object + default_footer = footers(wdHeaderFooterPrimary) + default_footer.Range.Text = "Footer text" + +PageSetup object + +.. code-block:: python + + DifferentFirstPageHeaderFooter: Read/write {True, False, WD_UNDEFINED} + OddAndEvenPagesHeaderFooter: Read/write {True, False, WD_UNDEFINED} + + +Schema Excerpt +============== + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/dev/analysis/features/header-footer-3.rst b/docs/dev/analysis/features/header-footer-3.rst new file mode 100644 index 000000000..f43256013 --- /dev/null +++ b/docs/dev/analysis/features/header-footer-3.rst @@ -0,0 +1,282 @@ +================= +Header and Footer +================= + +In a WordprocessingML document, a page header is text that is separated from +the main body of text and appears at the top of a printed page. The page +headers in a document are often the same from page to page, with only small +differences in content, such as a section and/or page number. Such a header is +also known as a running head. + +In book-printed documents, where pages are intended to bound on the long edge +and presented side-by-side, the header on the right-hand (recto) pages is often +different than that on the left-hand (verso) pages. The need to support this +difference gives rise to the option to have an even-page header that differs +from the default odd-page header in a document. + +A page footer is analogous in every way to a page header except that it appears +at the bottom of a page. It should not be confused with a footnote, which is +not uniform between pages. + +In WordprocessingML, a header or footer appears within the margin area of a +page. With a few exceptions, a header or footer can contain all types of +content that can appear in the main body, including text and images. Each +section has its own set of headers and footers, although a section can be +configured to "inherit" headers and footers from the prior section. + +Each section can have three distinct header definitions and footer definitions. +These apply to odd pages (the default), even pages, and the first page of the +section. All three are optional. + +For brevity in the discussion below I will occasionally use the term *header* +to refer to either a header and footer object, trusting the reader to +understand its applicability to either type of object. + +Note on Styles: + +The header and footer has access to all the normal styles defined in +``/word/styles.xml``. + +Candidate Protocol +================== + + +.. code-block:: xml + + # every section has a header; it is never None + + >>> header = section.header + >>> header + + + # Header.text - read/write, full text, no character formatting, \n for line + # break, \n\n for paragraph (or whatever other .text bits do). Assignment can + # only be a single paragraph; can include tabs and line breaks, but no + # paragraphs. + +Header inherits from docx.blkcntnr.BlockItemContainer. It has access to all the +normal header.add_paragraph, paragraph.add_run, paragraph.add_image functions. + +.. code-block:: xml + + # if a section has no w:headerReference, it inherits from the prior + # section + + >>> header.is_linked_to_previous + True + +constructive editing operations transparently operate on the source +header, that of the first prior section having a header (if the current +section has none). If no prior sections have a header, one is created +in the first section of the document on the first constructive edit +call. + +.. code-block:: xml + + >>> header = document.sections[0].header + >>> header.is_linked_to_previous + True + >>> header.text = 'foobar' + >>> header.is_linked_to_previous + False + + # A header can be explicitly added to a section by assigning False to + # Header.is_linked_to_previous + + >>> header.is_linked_to_previous + True + >>> header.is_linked_to_previous = False + >>> header.is_linked_to_previous + False + + # after setting is_linked_to_previous = False, the variable header changes + # from the header from the previous section to a brand new copy of the header + # from the previous section. edits to header will affect the current section, + # not the previous section. + + # Conversely, a header can be deleted from a section by assigning True to + # Header.is_linked_to_previous + + >>> header.is_linked_to_previous + False + >>> header.is_linked_to_previous = True + >>> header.is_linked_to_previous + True + +There are three headers: header, even_header, and first_page_header. They all +function similarly to header described above. + +.. code-block:: xml + + >>> document.settings.different_even_odd_headers = True + # the first time this is set to True, this creates a blank even header + # in the first section which all other sections inherit. + # because by default "linked_to_previous" == True + + >>> header = document.sections[0].header + # if different_even_odd_headers is False, then header will be on all pages + # if different_even_odd_headers is True, then header will be on odd pages + + >>> even_header = document.sections[0].even_header + # creates a new even_header just like header + # if different_even_odd_headers is False, then even_header will be present + # but not displayed + # if different_even_odd_headers is True, then even_header will be displayed + # on even pages + + >>> section = document.sections[2] + >>> section.different_first_page_header + False + >>> section.different_first_page_header = True + # if there is no first_page_header, a new blank first_page_header is + # created in the first section + >>> section.different_first_page_header + True + + >>> first_page_header = document.sections[0].first_page_header + # get_or_creates a new first_page_header just like header + # if section.different_first_page_header is True, the first_page_header is + # displayed on the first page of the section + # if section.different_first_page_header is False, the first_page_header is + # not displayed + # by default new sections have different_first_page_header set to False + + +Specimen XML +============ + +There are seven different permutations of headers: + +This most basic scenario a single header on all pages of the document: + +.. code-block:: xml + + + + + ... + + + +Now just an odd header. The section is exactly the same as above but `settings.xml`: + +.. code-block:: xml + + + + + +Now both even and odd header. `settings.xml` still has `w:evenAndOddHeaders` +and the section looks like this: + +.. code-block:: xml + + + + + + ... + + +One header appears on the first page, and a different header on all subsequent pages: + +.. code-block:: xml + + + + + + ... + + +In this scenario one header appears on the first page, and then alternating even/odd headers appear on all subsequent pages. + +The ``settings.xml`` contains the ``w:evenAndOddHeaders`` element. + +.. code-block:: xml + + + + + + + ... + + +To better understand the header / footer XML, see also: +`Header Part `_ + +XML Semantics +============= + +`` seems to work equivalently to `` + +`` seems to work equivalently to `` + +Word Behavior +============= + +When you turn off even/odd headers, Word sets the value of +`w:evenAndOddHeaders` to 0, but does not actually remove the even header. + +When you turn off first page header, Word sets the value of +`w:titlePg` to 0, but does not actually remove the even header. + +Word will load a file with an even page header but no odd page header. + +MS API +====== + +WdHeaderFooterIndex Enumeration + +.. code-block:: python + + EVEN_PAGES = 3 + FIRST_PAGE = 2 + PRIMARY = 1 + +.. code-block:: python + + section = Document.Sections(1) + footers = section.Footers # a HeadersFooters collection object + default_footer = footers(wdHeaderFooterPrimary) + default_footer.Range.Text = "Footer text" + +PageSetup object + +.. code-block:: python + + DifferentFirstPageHeaderFooter: Read/write {True, False, WD_UNDEFINED} + OddAndEvenPagesHeaderFooter: Read/write {True, False, WD_UNDEFINED} + + +Schema Excerpt +============== + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/dev/analysis/features/header-footer-4.rst b/docs/dev/analysis/features/header-footer-4.rst new file mode 100644 index 000000000..20f6a6a84 --- /dev/null +++ b/docs/dev/analysis/features/header-footer-4.rst @@ -0,0 +1,404 @@ +================= +Header and Footer +================= + +In a WordprocessingML document, a page header is text that is separated from +the main body of text and appears at the top of a printed page. The page +headers in a document are often the same from page to page, with only small +differences in content, such as a section and/or page number. Such a header is +also known as a running head. + +In book-printed documents, where pages are intended to bound on the long edge +and presented side-by-side, the header on the right-hand (recto) pages is often +different than that on the left-hand (verso) pages. The need to support this +difference gives rise to the option to have an even-page header that differs +from the default odd-page header in a document. + +A page footer is analogous in every way to a page header except that it appears +at the bottom of a page. It should not be confused with a footnote, which is +not uniform between pages. + +In WordprocessingML, a header or footer appears within the margin area of a +page. With a few exceptions, a header or footer can contain all types of +content that can appear in the main body, including text and images. Each +section has its own set of headers and footers, although a section can be +configured to "inherit" headers and footers from the prior section. + +Each section can have three distinct header definitions and footer definitions. +These apply to odd pages (the default), even pages, and the first page of the +section. All three are optional. + +For brevity in the discussion below I will occasionally use the term *header* +to refer to either a header and footer object, trusting the reader to +understand its applicability to either type of object. + +Note on Styles: + +The header and footer has access to all the normal styles defined in +``/word/styles.xml``. + +Candidate Protocol +================== + + +.. code-block:: xml + + # every section has a header; it is never None + + >>> header = section.header + >>> header + + +There are three headers: header, even_header, and first_page_header. They all +function similarly to header. + +Header inherits from docx.blkcntnr.BlockItemContainer. It has access to all the +normal header.add_paragraph, paragraph.add_run, paragraph.add_image functions. + +.. code-block:: xml + + # if a section has no w:headerReference, it inherits from the prior + # section + + >>> header.is_linked_to_previous + True + +constructive editing operations transparently operate on the source +header, that of the first prior section having a header (if the current +section has none). If no prior sections have a header, one is created +in the first section of the document on the first constructive edit +call. + +.. code-block:: xml + + >>> header = document.sections[0].header + >>> header.is_linked_to_previous + True + >>> header.text = 'foobar' + >>> header.is_linked_to_previous + False + + # A blank header can be explicitly added to a section by assigning False to + # Header.is_linked_to_previous + + >>> header.is_linked_to_previous + True + >>> header.is_linked_to_previous = False + >>> header.is_linked_to_previous + False + + # after setting is_linked_to_previous = False, the variable header changes + # from the header from the previous section to a new blank header on the + # current section. + + # Conversely, a header can be deleted from a section by assigning True to + # Header.is_linked_to_previous + + >>> header.is_linked_to_previous + False + # There's a bit of a conundrum here, where .is_linked_to_previous can be + # True on the first section, even though by definition there can't be a + # previous section. For the first section, "is_linked_to_previous" is + # really just a way to create blank headers or delete headers. + + >>> header.is_linked_to_previous = True + >>> header.is_linked_to_previous + True + + >>> document.settings.odd_and_even_pages_header_footer = True + >>> header = document.sections[0].header + # if odd_and_even_pages_header_footer is False, then header will be on all pages + # if odd_and_even_pages_header_footer is True, then header will be on odd pages + + >>> even_header = document.sections[0].even_header + >>> even_header.add_paragraph('foobar') + # creates a new blank even_header + # if odd_and_even_pages_header_footer is False, then even_header will be present + # but not displayed + # if odd_and_even_pages_header_footer is True, then even_header will be displayed + # on even pages + + >>> section = document.sections[2] + >>> section.different_first_page_header_footer + False + >>> section.different_first_page_header_footer = True + >>> section.different_first_page_header_footer + True + + >>> first_page_header = document.sections[0].first_page_header + >>> first_page_header.add_paragraph('barbar') + # if section.different_first_page_header_footer is True, the first_page_header is + # displayed on the first page of the section + # if section.different_first_page_header_footer is False, the first_page_header is + # not displayed + # by default new sections have different_first_page_header_footer set to False + + # Header.text - read/write, full text, no character formatting, \n for line + # break, \n\n for paragraph (or whatever other .text bits do). Assignment can + # only be a single paragraph; can include tabs and line breaks, but no + # paragraphs. + + +Specimen XML +============ + +There are seven different permutations of headers: + +This most basic scenario a single header on all pages of the document: + +.. code-block:: xml + + + + + ... + + + +Now just an odd header. The section is exactly the same as above but +`settings.xml` has the the `` property: + +.. code-block:: xml + + + ... + + + +Now both even and odd header. `settings.xml` still has `w:evenAndOddHeaders` +and the section looks like this: + +.. code-block:: xml + + + + + + ... + + +One header appears on the first page, and a different header on all subsequent pages: + +.. code-block:: xml + + + + + + ... + + +In this scenario one header appears on the first page, and then alternating even/odd headers appear on all subsequent pages. + +The ``settings.xml`` contains the ``w:evenAndOddHeaders`` element. + +.. code-block:: xml + + + + + + + ... + + +To better understand the header / footer XML, see also: +`Header Part `_ + +XML Semantics +============= + +`` seems to work equivalently to `` + +`` seems to work equivalently to `` + +Word Behavior +============= + +When you turn off even/odd headers, Word sets the value of +`w:evenAndOddHeaders` to 0, but does not actually remove the even header. + +When you turn off first page header, Word sets the value of +`w:titlePg` to 0, but does not actually remove the even header. + +Word will load a file with an even page header but no odd page header. + +MS API +====== + +WdHeaderFooterIndex Enumeration + +.. code-block:: python + + EVEN_PAGES = 3 + FIRST_PAGE = 2 + PRIMARY = 1 + +.. code-block:: python + + section = Document.Sections(1) + footers = section.Footers # a HeadersFooters collection object + default_footer = footers(wdHeaderFooterPrimary) + default_footer.Range.Text = "Footer text" + +PageSetup object + +.. code-block:: python + + DifferentFirstPageHeaderFooter: Read/write {True, False, WD_UNDEFINED} + OddAndEvenPagesHeaderFooter: Read/write {True, False, WD_UNDEFINED} + + +Schema Excerpt +============== + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/dev/analysis/features/header-footer.rst b/docs/dev/analysis/features/header-footer.rst new file mode 100644 index 000000000..d5911d391 --- /dev/null +++ b/docs/dev/analysis/features/header-footer.rst @@ -0,0 +1,488 @@ +================= +Header and Footer +================= + +Word supports headers and footers on documents. Headers and footers can include paragraphs with styles, text, and images. + +Many documents use headers in order to have a logo at the top of every page. + +Or use a footer to have company contact information at the bottom of every page. + +For brevity in the discussion below I will occasionally use the term *header* to refer to either a header and footer object, trusting the reader to understand its applicability to either type of object. + +Structure +========= + +For the sake of simplicity, we will assume we have a single header applied to all pages. + +This header consists of five parts: + +1. /word/header1.xml +-------------------- + +This file contains the header contents. It could be named anything but it is often named header1. + +A file can contain multiple headers. Each one should be stored in a different file: +``/word/header1.xml``, ``/word/header2.xml``, etc. + +Here's a simple example: + +.. code-block:: xml + + + + + + + + + + This is a header. + + + + +Footers are identical to headers except they use the ```` tag instead of ````. + +2. /word/_rels/document.xmls.rels +--------------------------------- + +This file contains unique relationship ids between all the different parts of a document: settings, styles, numbering, images, themes, fonts, etc. + +When a header, it too will have a unique relationship id. + +Here's an example, with the header as defined above having ``rId3``: + +.. code-block:: xml + + + + + + + +3. /word/document.xml +--------------------- + +This file is the motherload: it contains the bulk of the document contents. + +With respect to the headers though, this file contains very little: all it contains is a reference to the header in the sentinel sectPr (the final and often only sectPr in a document just before the closing body tag) via the relationship id defined in ``/word/_rels/document.xml.rels`` + +Here's an example, again with the ``header1.xml`` as ``rId3``: + +.. code-block:: xml + + + ... + + + + + + + + + +Footers are identical to headers except they use the ```` +instead of the ```` tag. + +The ```` (if present) should be the first element of the sentinel sectPr, and the ```` should be the next element. (The OpenXML SDK 2.5 docx validator gives a warning if the ```` is not the first element.) + +4. [Content Types].xml +----------------------- + +If the header is present, it needs to be added to the ``[Content Types].xml`` file. Like so: + +.. code-block:: xml + + + + + + + + + + + + +The footer if present also needs to be added. Its ``ContentType`` should be + +.. code-block:: xml + + "application/vnd.openxmlformats-officedocument.wordprocessingml.footer+xml" + +All header and footer files referenced in document.xml.rels need to be added to ``[Content Types].xml.`` + + +5. /word/_rels/header1.xml.rels +------------------------------- + +(OPTIONAL) This file is only present if the header has an image. + +This is the header's relationships file. It is similar to the document's relationships file at ``/word/_rels/document.xml.rels``. + +This file is stored with the same name as the header xml file under ``/word/_rels/``. + +Suppose the header above had an image stored at ``/word/media/image1.png``. + +The relationships file would be stored ``/word/_rels/header1.xml.rels``. It will look like this: + +.. code-block:: xml + + + + + + +Note the ``rIds`` of the header are completely independent of the relationships of the main ``document.xml``. + + +All Pages, Even Pages, Odd Pages, First Page +-------------------------------------------- + +There are seven different permutations of headers: + +1. All Pages +~~~~~~~~~~~~ + +This most basic scenario was used above. When there is a single header of type ``default`` and ``settings.xml`` does not contain the ``w:evenAndOddHeaders`` element, then the header will appear on every page. + +.. code-block:: xml + + + + ... + + + + + + + + + + +2. Odd Pages +~~~~~~~~~~~~ + +The next scenario is just an odd header. In this scenario the ``document.xml`` is exactly the same as above, but the ``settings.xml`` contains the ``w:evenAndOddHeaders`` element. + + +3. Even Pages +~~~~~~~~~~~~~ + +In this scenario the ``settings.xml`` contains the ``w:evenAndOddHeaders`` element. And the ``document.xml`` looks exactly the same as the odd page scenario, except the ``w:type`` of the ``w:headerReference`` has changed from ``default`` to ``even``. + +.. code-block:: xml + + + + ... + + + + + + + + + + +4. Even and Odd Pages +~~~~~~~~~~~~~~~~~~~~~ + +In this scenario the document has two different headers: one for even pages, and another for odd pages. The ``settings.xml`` contains the ``w:evenAndOddHeaders`` element. And the ``document.xml`` has two ``w:headerReferences``: + +.. code-block:: xml + + + + ... + + + + + + + + + + + +5. First Page +~~~~~~~~~~~~~ + +In this scenario a header appears on the first page and only the first page. The ``settings.xml`` may or may not contain the ``w:evenAndOddHeaders`` element. And the ``document.xml`` has a single ``w:headerReference`` of type ``first``: + +.. code-block:: xml + + + + ... + + + + + + + + + + +6. First Page Then All Pages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In this scenario one header appears on the first page and a different header appears on all subsequent pages. The ``settings.xml`` does not contain the ``w:evenAndOddHeaders`` element. And the ``document.xml`` has two ``w:headerReferences``: + +.. code-block:: xml + + + + ... + + + + + + + + + + + +7. First Page Then Even/Odd Pages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In this scenario one header appears on the first page, and then alternating even/odd headers appear on all subsequent pages. The ``settings.xml`` contains the ``w:evenAndOddHeaders`` element. And the ``document.xml`` has two ``w:headerReferences``: + +.. code-block:: xml + + + + ... + + + + + + + + + + + +It's also theoretically possible to have a first page header then just an even page header, or a first page then just an odd page header. + + +Note on Styles: +--------------- + +The header and footer has access to all the normal styles defined in ``/word/styles.xml``. + + +Candidate Protocol +================== + +Section +------- + +headers +------- + +:class:`docx.section.Section` has a read_only ``headers`` property which is a list of headers +in the section of type :class:`docx.header.Header`: + +.. code-block:: python + + >>> from docx import Document + >>> document = Document('document_with_single_header.docx') + >>> section = document.sections[-1] + >>> isinstance(section.headers, list) + True + >>> len(section.headers) + 1 + >>> section.headers[0] + + +This property is present in the MS API: https://msdn.microsoft.com/en-us/library/office/ff820779.aspx + +header +---------------- + +read-only property, returns the default type header if present, else ``None`` + +even_page_header +---------------- + +read-only property, returns the even page header if present, else ``None`` + +In theory an odd_page_header property could also be added. But for v1 we can just leave that to the user to figure out where their ``default`` header represents an all-pages header and when it represents an odd-page header. + +first_page_header +----------------- + +read-only property, returns the first page header if present, else ``None`` + +clear_headers +------------- + +:class:`docx.section.Section` has a ``clear_headers`` method which removes all headers +from the section + +.. code-block:: python + + >>> from docx import Document + >>> document = Document('document_with_single_header.docx') + >>> section = document.sections[-1] + >>> section.clear_headers() + >>> len(section.headers) + 0 + +If you wanted to clear all headers from every section you could iterate over every section and call ``clear_headers`` on each. + +By default the sections will then inherit the headers you define on the ``w:sectPr`` of ``w:body``. (TODO: IS THIS TRUE? CONFIRM!) + +This method also removes the ```` element from ``settings.xml`` so that any subsequent headers added are added to all pages. + + +add_header +------------- + +:class:`docx.section.Section` has an ``add_header`` method which adds an instance +of type :class:`docx.header.Header` with no text to the document and returns the new +header instance. + +.. code-block:: python + + >>> from docx import Document + >>> document = Document('document_without_header.docx') + >>> section = document.sections[-1] + >>> header = section.add_header() + >>> isinstance(header, Header) + True + >>> header.type + 'default' + +:class:`docx.section.Section`'s ``add_header`` method will raise an ``Exception`` (of type ?) +if a header of type default already exists on the document. + +.. code-block:: python + + >>> from docx import Document + >>> document = Document('document_with_default_header.docx') + >>> section = document.sections[-1] + >>> section.add_header() + *** Exception: Document already has a default header! + +The user should remove the existing header explicitly with clear_headers and then they can add a header. + +add_even_page_header +-------------------- + +:class:`docx.section.Section` has an ``add_even_page_header`` method which adds the +```` element to ``settings.xml`` (if not already present) +and adds a header of type :class:`docx.header.Header` with no text to the document, and returns the new +header instance. + +.. code-block:: python + + >>> from docx import Document + >>> document = Document('document_without_header.docx') + >>> section = document.sections[-1] + >>> header = section.add_even_page_header() + >>> isinstance(header, Header) + True + +:class:`docx.section.Section`'s ``add_even_page_header`` method will raise an ``Exception`` (of type ?) +if a header of type even already exists on the document. + +.. code-block:: python + + >>> from docx import Document + >>> document = Document('document_with_even_header.docx') + >>> section = document.sections[-1] + >>> section.add_even_page_header() + *** Exception: Document already has an even header! + +NOTE: + +Because ``add_even_page_header`` implicitly sets the ```` property of ``settings.xml``, this could confuse people. + +If they want to add a header to every page, they may need to remove all headers with ``clear_headers`` and then call ``add_header`` if a document already has ````. + +Still, that seems like the simplest way to expose this functionality so that users of the API don't have to understand all the internal implementation details of headers. + +Especially if in the docs it is specified that for even/odd page headers you first call ``add_header`` then call ``add_even_page_header``. + +And the docs should also point out, if you want to add headers to a document that might already have them, it is generally a good idea to call ``clear_headers`` first then add your headers. + +add_first_page_header +--------------------- + +:class:`docx.section.Section` has an ``add_first_page_header`` method adds a header of type :class:`docx.header.Header` with no text to the document, and returns the new header instance. + +.. code-block:: python + + >>> from docx import Document + >>> document = Document('document_without_header.docx') + >>> section = document.sections[-1] + >>> header = section.add_first_page_header() + >>> isinstance(header, Header) + True + +:class:`docx.section.Section`'s ``add_first_page_header`` method will raise an ``Exception`` (of type ?) +if a header of type first already exists on the document. + +.. code-block:: python + + >>> from docx import Document + >>> document = Document('document_with_first_header.docx') + >>> section = document.sections[-1] + >>> section.add_first_page_header() + *** Exception: Document already has a first header! + + +Header +====== + +A :class:`docx.header.Header` instance behaves just like any other BlockItemContainer subclass +(e.g. ``_Body``). + +header.add_paragraph +-------------------- +Headers possesses methods for adding and removing child paragraphs, which in turn +have methods for adding and removing runs. + +.. code-block:: python + + from docx.text.run import Run + from docx.text.paragraph import Paragraph + >>> paragraph = header.add_paragraph() + >>> isinstance(paragraph, Paragraph) + True + >>> run1 = paragraph.add_run('Some text for the header') + >>> isinstance(run1, Run) + True + >>> run2 = paragraph.add_run('More text for the header') + >>> isinstance(run2, Run) + True + +A :class:`docx.text.run.Run` instance inside of a :class:`docx.header.Header` can add an image. + +.. code-block:: python + + >>> from docx.shared import Pt + >>> from docx.shape import InlineShape + >>> width = Pt(160) + >>> height = Pt(40) + >>> picture = run2.add_picture('/logo.png', width, height) + >>> isinstance(picture, InlineShape) + True + +Styles work in the normal way on both paragraphs and runs. + +footer stuff +------------ + +:class:`docx.document.Document` has all the same methods for footers. diff --git a/docs/dev/analysis/features/header-inheritance2.rst b/docs/dev/analysis/features/header-inheritance2.rst new file mode 100644 index 000000000..78cdfb9dd --- /dev/null +++ b/docs/dev/analysis/features/header-inheritance2.rst @@ -0,0 +1,168 @@ +I confirmed that toggling "Different even and odd headers" in the UI is always global and affects all sections simultaneously. Which makes perfect sense given the XML! + +Experiment 1: +============= + +Summary: "Different first page" can be toggled section by section. "Different first page" only applies to default, even, and first headers individually. + +Steps: +------ + +> Create new file, set even-odd headers on +> Create an even header and a different odd header with content S1Even and S1Odd respectively +> Add a second section. +> Add second page to second section + +Section 2 inherits S1Even and S1Odd header from Section 1. + +> Toggle "Different First Page" on section 1 header. Add content S1First. + +Section 2 page 2 still shows S1Odd + +> Toggle "Different First Page" on section 2 header + +Section 2 header shows S1First + +> Alternate scenario: Toggle "Different First Page" on section 1 before adding Section 2. + +Same end result. Section 2 still starts off with "Different First Page" as false. + +In other words, for new sections, Word defaults to "Different First Page" being false and inherits the appropriate even/odd header from the previous section. Which seems like a reasonable default we should copy. + +> Uncheck "Different First Page" for Section 1 and 2 +> Add a third section. +> Add second page to third section. + +Section 3 has S1Odd and S1Even headers. + +> Change the default (odd) header for section 2 to S2Odd + +Both Section 3 AND Section 1 headers flip to S2Odd. + +> Set Section 2 "Link to Previous" to False./ + +Section 1 header remains "S2Odd" + +> Change Section 2 header to "S3Odd" + +Section 1 header remains "S2Odd" whereas Section 3 header becomes "S3Odd" (as you'd expect). + +> Set Section 2 "Different First Page" to True. + +Section 2 "Link to Previous" flips from True to False. (Weird) Section 2 header now has the S1First header. + +> Set Section 2 "Link to Previous" to false. + +Section 2 remains S1First. + +> Change Section 2 to "S2First" + +Section 1 remains S1First. + +It looks like "Link to Previous" operates independently for first / odd headers. That's why when you flip on "Different First Page" it switches automagically to "Link to Previous". The odd header has had "Link to Previous" set to false, but the first page header has not! + +Experiment 2: +============= + +Document with two two-page sections. + +Purpose: Examining the XML behavior of "Link to Previous" + +Summary: + +"Link to previous" is not actually reflected in the Word XML as such. It's just a UI affordance to copy/paste headers. + +Word Header/Footer Inheritance is copypasta. Setting "Link to Previous" to False actually means: copy first section's sectPr's header to sentinel sectPr. + +Setting "Link to Previous" to True means: remove sentinel sectPr's header. +Whereupon Word by default will inherit the first section's headers. + +Steps: +------ + +> Create new file, set even-odd headers on +> Create an even header and a different odd header with content S1Even and S1Odd respectively +> Add a second section. +> Add second page to second section + +XML: even / odd header in last paragraph of Section 1. no headers in sentinel sectPr. + +> Set "link to previous" to False in section 2's odd header. + +XML: even / odd header in last paragraph of Section 1. odd header in sentinel sectPr. + +> Change Section 2 odd header to "S2Odd" + +XML: text in sentinel sectPr odd header changed to "S2Odd". Confirmed: Section 2 is displaying sentinel sectPr's header data. + +> Set "link to previous" back to True on section 1's + +Word displays alert: "Do you want to delete this header/footer and connect to the header/footer in the previous section?" + +> Click "Yes". + +XML: sentinel sectPr header is gone. + +Experiment 2: +============= + +Setup: +------ + +Document with four two-page sections. + +Purpose: +-------- + +Set "Link to Previous" to False at Section 3 Pg header. Examine how Section 1/2 inherit, vs Section 3/4. + +Summary: +-------- + +The sectPr of the last paragraph of section 1 has even/odd headers. + +The sectPr of the last paragraph of section 3 has odd header. + +No sentinel sectPr header. + +Experiment 3: +============= + +Purpose: +-------- + +Discover when exactly the sentinel sectPr is used, vs the sectPr of the last paragraph of the section. + +Setup: +------ + +Document with three two-page sections. + +Summary: +-------- + +If the last section has "Link to Previous" set to False, the header used by the previous section will be copied to the sentinel sectPr. + +If any non-last section has "Link to Previous" set to False, the header used by the previous section will be copied to the sectPr of the final paragraph of the that section. + +Steps: +------ + +Scenario 1: + +> Set Section 3's Odd Header "Link to Previous" to False. + +XML: Header is in sentinel sectPr + +Scenario 2: + +> Set Section 2's Odd Header "Link to Previous" to False. + +XML: Header is in sectPr of last paragraph of section 2, not in sentinel sectPr. + +Scenario 3: + +> Set Section 3's Odd Header "Link to Previous" to False. +> Add Section 4 + +XML: Header is in sectPr of last paragraph of section 3, not in sentinel sectPr. diff --git a/docs/dev/analysis/features/header-inheritance3.rst b/docs/dev/analysis/features/header-inheritance3.rst new file mode 100644 index 000000000..78cdfb9dd --- /dev/null +++ b/docs/dev/analysis/features/header-inheritance3.rst @@ -0,0 +1,168 @@ +I confirmed that toggling "Different even and odd headers" in the UI is always global and affects all sections simultaneously. Which makes perfect sense given the XML! + +Experiment 1: +============= + +Summary: "Different first page" can be toggled section by section. "Different first page" only applies to default, even, and first headers individually. + +Steps: +------ + +> Create new file, set even-odd headers on +> Create an even header and a different odd header with content S1Even and S1Odd respectively +> Add a second section. +> Add second page to second section + +Section 2 inherits S1Even and S1Odd header from Section 1. + +> Toggle "Different First Page" on section 1 header. Add content S1First. + +Section 2 page 2 still shows S1Odd + +> Toggle "Different First Page" on section 2 header + +Section 2 header shows S1First + +> Alternate scenario: Toggle "Different First Page" on section 1 before adding Section 2. + +Same end result. Section 2 still starts off with "Different First Page" as false. + +In other words, for new sections, Word defaults to "Different First Page" being false and inherits the appropriate even/odd header from the previous section. Which seems like a reasonable default we should copy. + +> Uncheck "Different First Page" for Section 1 and 2 +> Add a third section. +> Add second page to third section. + +Section 3 has S1Odd and S1Even headers. + +> Change the default (odd) header for section 2 to S2Odd + +Both Section 3 AND Section 1 headers flip to S2Odd. + +> Set Section 2 "Link to Previous" to False./ + +Section 1 header remains "S2Odd" + +> Change Section 2 header to "S3Odd" + +Section 1 header remains "S2Odd" whereas Section 3 header becomes "S3Odd" (as you'd expect). + +> Set Section 2 "Different First Page" to True. + +Section 2 "Link to Previous" flips from True to False. (Weird) Section 2 header now has the S1First header. + +> Set Section 2 "Link to Previous" to false. + +Section 2 remains S1First. + +> Change Section 2 to "S2First" + +Section 1 remains S1First. + +It looks like "Link to Previous" operates independently for first / odd headers. That's why when you flip on "Different First Page" it switches automagically to "Link to Previous". The odd header has had "Link to Previous" set to false, but the first page header has not! + +Experiment 2: +============= + +Document with two two-page sections. + +Purpose: Examining the XML behavior of "Link to Previous" + +Summary: + +"Link to previous" is not actually reflected in the Word XML as such. It's just a UI affordance to copy/paste headers. + +Word Header/Footer Inheritance is copypasta. Setting "Link to Previous" to False actually means: copy first section's sectPr's header to sentinel sectPr. + +Setting "Link to Previous" to True means: remove sentinel sectPr's header. +Whereupon Word by default will inherit the first section's headers. + +Steps: +------ + +> Create new file, set even-odd headers on +> Create an even header and a different odd header with content S1Even and S1Odd respectively +> Add a second section. +> Add second page to second section + +XML: even / odd header in last paragraph of Section 1. no headers in sentinel sectPr. + +> Set "link to previous" to False in section 2's odd header. + +XML: even / odd header in last paragraph of Section 1. odd header in sentinel sectPr. + +> Change Section 2 odd header to "S2Odd" + +XML: text in sentinel sectPr odd header changed to "S2Odd". Confirmed: Section 2 is displaying sentinel sectPr's header data. + +> Set "link to previous" back to True on section 1's + +Word displays alert: "Do you want to delete this header/footer and connect to the header/footer in the previous section?" + +> Click "Yes". + +XML: sentinel sectPr header is gone. + +Experiment 2: +============= + +Setup: +------ + +Document with four two-page sections. + +Purpose: +-------- + +Set "Link to Previous" to False at Section 3 Pg header. Examine how Section 1/2 inherit, vs Section 3/4. + +Summary: +-------- + +The sectPr of the last paragraph of section 1 has even/odd headers. + +The sectPr of the last paragraph of section 3 has odd header. + +No sentinel sectPr header. + +Experiment 3: +============= + +Purpose: +-------- + +Discover when exactly the sentinel sectPr is used, vs the sectPr of the last paragraph of the section. + +Setup: +------ + +Document with three two-page sections. + +Summary: +-------- + +If the last section has "Link to Previous" set to False, the header used by the previous section will be copied to the sentinel sectPr. + +If any non-last section has "Link to Previous" set to False, the header used by the previous section will be copied to the sectPr of the final paragraph of the that section. + +Steps: +------ + +Scenario 1: + +> Set Section 3's Odd Header "Link to Previous" to False. + +XML: Header is in sentinel sectPr + +Scenario 2: + +> Set Section 2's Odd Header "Link to Previous" to False. + +XML: Header is in sectPr of last paragraph of section 2, not in sentinel sectPr. + +Scenario 3: + +> Set Section 3's Odd Header "Link to Previous" to False. +> Add Section 4 + +XML: Header is in sectPr of last paragraph of section 3, not in sentinel sectPr. diff --git a/docs/dev/analysis/features/header-part.rst b/docs/dev/analysis/features/header-part.rst new file mode 100644 index 000000000..7f23f6dea --- /dev/null +++ b/docs/dev/analysis/features/header-part.rst @@ -0,0 +1,143 @@ +=========== +Header Part +=========== + +For the sake of simplicity, we will assume we have a single header applied to +all pages. + +This header consists of five parts: + +1. /word/header1.xml +-------------------- + +This file contains the header contents. It could be named anything but it is +often named header1. + +A file can contain multiple headers. Each one should be stored in a different +file: ``/word/header1.xml``, ``/word/header2.xml``, etc. + +Here's a simple example: + +.. code-block:: xml + + + + + + + + + + This is a header. + + + + +Footers are identical to headers except they use the ```` tag instead of +````. + +2. /word/_rels/document.xmls.rels +--------------------------------- + +This file contains unique relationship ids between all the different parts of a +document: settings, styles, numbering, images, themes, fonts, etc. + +When a header, it too will have a unique relationship id. + +Here's an example, with the header as defined above having ``rId3``: + +.. code-block:: xml + + + + + + + +3. /word/document.xml +--------------------- + +This file is the motherload: it contains the bulk of the document contents. + +With respect to the headers though, this file contains very little: all it +contains is a reference to the header in the sentinel sectPr (the final and +often only sectPr in a document just before the closing body tag) via the +relationship id defined in ``/word/_rels/document.xml.rels`` + +Here's an example, again with the ``header1.xml`` as ``rId3``: + +.. code-block:: xml + + + ... + + + + + + + + + +Footers are identical to headers except they use the ```` +instead of the ```` tag. + +The ```` (if present) should be the first element of the +sentinel sectPr, and the ```` should be the next element. +(The OpenXML SDK 2.5 docx validator gives a warning if the +```` is not the first element.) + +4. [Content Types].xml +----------------------- + +If the header is present, it needs to be added to the ``[Content Types].xml`` +file. Like so: + +.. code-block:: xml + + + + + + + + + + + + +The footer if present also needs to be added. Its ``ContentType`` should be + +.. code-block:: xml + + "application/vnd.openxmlformats-officedocument.wordprocessingml.footer+xml" + +All header and footer files referenced in document.xml.rels need to be added to +``[Content Types].xml.`` + + +5. /word/_rels/header1.xml.rels +------------------------------- + +(OPTIONAL) This file is only present if the header has an image. + +This is the header's relationships file. It is similar to the document's +relationships file at ``/word/_rels/document.xml.rels``. + +This file is stored with the same name as the header xml file under +``/word/_rels/``. + +Suppose the header above had an image stored at ``/word/media/image1.png``. + +The relationships file would be stored ``/word/_rels/header1.xml.rels``. It +will look like this: + +.. code-block:: xml + + + + + + +Note the ``rIds`` of the header are completely independent of the relationships +of the main ``document.xml``. diff --git a/docs/dev/analysis/features/headerfooter.rst b/docs/dev/analysis/features/headerfooter.rst new file mode 100644 index 000000000..9730c9807 --- /dev/null +++ b/docs/dev/analysis/features/headerfooter.rst @@ -0,0 +1,266 @@ + +Headers and Footers +=================== + +In a WordprocessingML document, a page header is text that is separated from +the main body of text and appears at the top of a printed page. The page +headers in a document are often the same from page to page, with only small +differences in content, such as a section and/or page number. Such a header +is also known as a *running head*. + +In book-printed documents, where pages are intended to bound on the long edge +and presented side-by-side, the header on the right-hand (recto) pages is +often different than that on the left-hand (verso) pages. The need to support +this difference gives rise to the option to have an *even-page* header that +differs from the default *odd-page* header in a document. + +A page footer is analogous in every way to a page header except that it +appears at the bottom of a page. It should not be confused with a footnote, +which is not uniform between pages. + +In WordprocessingML, a header or footer appears within the margin area of +a page. With a few exceptions, a header or footer can contain all types of +content that can appear in the main body, including text and images. Each +section has its own set of headers and footers, although a section can be +configured to "inherit" headers and footers from the prior section. + +Each section can have three distinct header definitions and footer +definitions. These apply to odd pages (the default), even pages, and the +first page of the section. All three are optional. + +For brevity in the discussion below I will occasionally use the term *header* +to refer to either a header and footer object, trusting the reader to +understand its applicability to either type of object. + + +Header and footer parts +----------------------- + +Each header or footer definition is a distinct part in the WordprocessingML +package. + +A header/footer part is related to the document part by a relationship entry. +That relationship is referenced by a section in the document by its rId key. + +A default document will contain no header or footer parts and no +`w:headerReference` or `w:footerReference` elements in its `w:sectPr` +element. + + +Research TODO +------------- + +1. [ ] default blank document baseline +2. [ ] add section break +3. [ ] add section 2 header + + A. does Word create a blank default header for section 1? + +4. [ ] set odd/even True on document with 2 sections, no header/footers + + A. does Word create a blank default header/footer for section 1? + +5. [ ] if not, set a header on section 2 and document what happens +6. [ ] try the same on section 1 and see what happens + +See if a pattern is discernable. + +Hypothesis: Word inserts blank headers and footers only as needed to provide +a running default when the first section has no default. It does this for +both headers and footers whenever it does it at all. + + +Acceptance Tests +---------------- + +:: + + Given a default blank document + Then document.section[0].header is None + And document.section[0].footer is None + + + Given a document with a single section having a header and footer + Then document.section[0].header is a Header object + And document.section[0].footer is a Footer object + + + Given a document with two sections having no headers or footers + When I assign True to document.odd_and_even_pages_header_footer + Then document.section[0].even_page_header is a blank Header object + And document.section[0].footer is a blank Footer object + And document.section[1].header is None + And document.section[1].footer is None + + +Candidate Protocol +------------------ + +:: + + >>> document = Document() + >>> section = document.sections[-1] + + >>> section.header + None + >>> section.add_header() + + + >>> section.even_page_header + None + >>> section.add_even_page_header() + + + >>> section.first_page_header + None + >>> section.add_first_page_header() + + + +MS API +------ + +.. highlight:: python + +WdHeaderFooterIndex Enumeration:: + + EVEN_PAGES = 3 + FIRST_PAGE = 2 + PRIMARY = 1 + +:: + + section = Document.Sections(1) + footers = section.Footers # a HeadersFooters collection object + default_footer = footers(wdHeaderFooterPrimary) + default_footer.Range.Text = "Footer text" + +PageSetup object:: + + DifferentFirstPageHeaderFooter: Read/write {True, False, WD_UNDEFINED} + OddAndEvenPagesHeaderFooter: Read/write {True, False, WD_UNDEFINED} + + +Specimen XML +------------ + +.. highlight:: xml + +Baseline blank document (some unrelated details omitted):: + + + + + + + + + + + +after adding a header:: + + + + + + + + + + + +after then adding an even-page header:: + + + + + + + + + + + + + +Implementation sequence +----------------------- + +* [ ] Implement skeleton SettingsPart +* [ ] A settings part is constructed by loader using the custom part +* [ ] Access header from section + +* [ ] Implement skeleton HeaderPart, consider a HeaderFooterPart base class. +* [ ] A header/footer part is constructed by loader using the custom part +* [ ] Access header from section + +Open topics +----------- + +* [ ] notion that specifying different even/first header/footers is distinct + from implementing different even/first header/footers. Auto-insertion + of blank items on set different, when needed. Document Word behaviors. +* [ ] settings.xml `w:evenAndOddHeaders` +* [ ] interaction with `w:sectPr/w:titlePg` element for different first-page + header and footer. +* [ ] describe inheritance behavior from user perspective, with examples, of + header/footers and different even and first page header/footers. +* [ ] positioning of header and footer block in `w:pgMar` element +* [ ] part name/location is `word/header1.xml` + +* [X] test whether Word will load a file with an even page header but no odd + page header. Yes, works fine. + + +Differences between a document without and with a header +-------------------------------------------------------- + +If you create a default document and save it (let's call that test.docx), +then add a header to it like so... + + This is a header. x of xx + +...the following changes will occur in the package: + +1) A part called header1.xml will be added to the package with the following + pathname: + + /word/header1.xml + +2) A new relationship is specified at word/_rels/document.xml.rels: + +:: + + * + +3) Within the element of document.xml, there will be a new element + called headerReference: + +:: + + + * + ... + + + +Different Even/Odd Page Headers and Footers +------------------------------------------- + +The `w:evenAndOddHeaders` element in the settings part specifies whether +sections have different headers and footers for even +and odd pages. This setting determines this behavior for all sections in the +document whether they have an even page header/footer defined or not. +A section not having an even-page header or footer defined will inherit it +from the prior section. + +When this setting is set to |True|, a blank header and/or footer is created +in the first document section when one is not present and becomes the default +for the sections that follow until a header/footer is explicitly defined. diff --git a/docs/dev/analysis/index.rst b/docs/dev/analysis/index.rst index 9a8201afc..e809a74b0 100644 --- a/docs/dev/analysis/index.rst +++ b/docs/dev/analysis/index.rst @@ -10,6 +10,7 @@ Feature Analysis .. toctree:: :titlesonly: + features/headerfooter features/settings features/text/index features/table/index diff --git a/docx/opc/oxml.py b/docx/opc/oxml.py index 0c09312b5..494b31dca 100644 --- a/docx/opc/oxml.py +++ b/docx/opc/oxml.py @@ -16,7 +16,7 @@ # configure XML parser element_class_lookup = etree.ElementNamespaceClassLookup() -oxml_parser = etree.XMLParser(remove_blank_text=True) +oxml_parser = etree.XMLParser(remove_blank_text=True, resolve_entities=False) oxml_parser.set_element_class_lookup(element_class_lookup) nsmap = { diff --git a/docx/oxml/__init__.py b/docx/oxml/__init__.py index d3b4d9fac..af18be148 100644 --- a/docx/oxml/__init__.py +++ b/docx/oxml/__init__.py @@ -14,7 +14,7 @@ # configure XML parser element_class_lookup = etree.ElementNamespaceClassLookup() -oxml_parser = etree.XMLParser(remove_blank_text=True) +oxml_parser = etree.XMLParser(remove_blank_text=True, resolve_entities=False) oxml_parser.set_element_class_lookup(element_class_lookup) diff --git a/docx/oxml/table.py b/docx/oxml/table.py index 30d349373..24d91690e 100644 --- a/docx/oxml/table.py +++ b/docx/oxml/table.py @@ -651,7 +651,7 @@ def _tbl(self): """ The tbl element this tc element appears in. """ - return self.xpath('./ancestor::w:tbl')[0] + return self.xpath('./ancestor::w:tbl[position()=1]')[0] @property def _tc_above(self): @@ -675,7 +675,7 @@ def _tr(self): """ The tr element this tc element appears in. """ - return self.xpath('./ancestor::w:tr')[0] + return self.xpath('./ancestor::w:tr[position()=1]')[0] @property def _tr_above(self):