Skip to content

Commit 57b6ffe

Browse files
Benjamin ToornstraBenjamin T
Benjamin Toornstra
authored and
Benjamin T
committed
docs: Updated feature proposal
1 parent e8b9aec commit 57b6ffe

File tree

1 file changed

+163
-67
lines changed

1 file changed

+163
-67
lines changed

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

Lines changed: 163 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -50,11 +50,19 @@ Adding a bookmark::
5050
>>> len(bookmarks)
5151
1
5252
>>> bookmarks.get('Target')
53-
docx.text.bookmark.Bookmark object at 0x00fa1afe1>
54-
>>> bookmarks.get(id=1)
55-
docx.text.bookmark.Bookmark object at 0x00fa1afe1>
53+
<docx.bookmark._Bookmark at 0x00fa1afe1>
54+
>>> bookmarks.get_by_id(1)
55+
<docx.bookmark._Bookmark at 0x00fa1afe1>
5656
>>> bookmarks[0]
57-
docx.text.bookmark.Bookmark object at 0x00fa1afe1>
57+
<docx.bookmark._Bookmark at 0x00fa1afe1>
58+
59+
# A bookmark can be deleted:
60+
>>> len(bookmarks)
61+
>>> 2
62+
>>> bookmark = bookmarks[0]
63+
>>> bookmark.delete()
64+
>>> len(bookmarks)
65+
>>> 1
5866

5967

6068
Word Behavior
@@ -82,19 +90,25 @@ Word Behavior
8290
* A bookmark can be *hidden*, which occurs for example when cross-references
8391
are inserted into the document.
8492

85-
* ? Do bookmarks need to be unique across all stories? (like headers, footers,
86-
etc.)? This could be trouble for us because we don't yet have access to
87-
those "stories".
93+
* As bookmarks need to be unique over all document stories, a check should
94+
be done for uniqueness. (The word API replaces the bookmark by a new one
95+
when a duplicate bookmarkname is used to insert a new bookmark.
96+
The word editor removes duplicate bookmarks.)
8897

89-
* ? How do overlapping bookmarks behave? Are those permitted? Like new one
90-
starts before prior one finishes?
98+
* Bookmarks may overlap i.e. A new bookmark is started as the previous
99+
one is not yet ended.
91100

92-
? What about "nested" bookmarks? Are those permitted? Line second bookmark
93-
starts and ends after first one starts and before it ends?
101+
* Bookmarks may be nested i.e. a bookmark may exists within the limits
102+
of another bookmark.
94103

95104
* A bookmark can be added in five different document parts: Body, Header,
96105
Footer, Footnote and Endnote.
97106

107+
* As bookmarks can be added in at different locations as well as different
108+
document parts, the bookmarkStart and bookmarkEnd elements should be added
109+
to different complex types: CT_Body, CT_P and CT_Tbl, as well as CT_HdrFtr
110+
and CT_FtnEdn.
111+
98112

99113
XML Semantics
100114
-------------
@@ -136,81 +150,163 @@ MS API Protocol
136150
The MS API defines a `Bookmarks` object which is a collection of
137151
`Bookmark objects`
138152

139-
.. _Bookmarks object:
140-
https://msdn.microsoft.com/en-us/vba/word-vba/articles/bookmarks-object-word
153+
Bookmarks object:
154+
155+
https://msdn.microsoft.com/en-us/vba/word-vba/articles/bookmarks-object-word
141156

142-
* Bookmarks.Add(name, range)
143-
* Bookmarks.Exists(name)
144-
* Bookmarks.Item(index)
145-
* Bookmarks.DefaultSorting
146-
* Bookmarks.ShowHidden
157+
Methods:
158+
* Bookmarks.Exists(name) - Checks if bookmark name exists in document.
159+
* Bookmarks.Item(index) - Returns bookmark based on id or name.
147160

148-
.. _Bookmark objects:
149-
https://msdn.microsoft.com/en-us/vba/word-vba/articles/bookmark-object-word
161+
Properties:
162+
* Bookmarks.Count - Number of bookmarks
150163

151-
* Bookmark.Delete()
152-
* Bookmark.Column (boolean)
153-
* Bookmark.Empty (boolean, True if contains no text.)
154-
* Bookmark.End
155-
* Bookmark.Name
156-
* Bookmark.Start
157-
* Bookmark.StoryType
164+
Bookmark objects:
165+
https://msdn.microsoft.com/en-us/vba/word-vba/articles/bookmark-object-word
158166

167+
Methods:
168+
* Bookmark.Delete() - Removing the two elements from the document
169+
170+
Properties:
171+
* Bookmark.Column (boolean) - True if bookmark is inside a table Column
172+
* Bookmark.Empty (boolean) - True if the specified bookmark is Empty
173+
* Bookmark.Name - Return name of bookmark.
159174

160175
Schema excerpt
161176
--------------
162177

163178
::
164179

165-
<xsd:element name="document" type="CT_Document"/>
166-
167-
<xsd:element name="endnotes" type="CT_Endnotes"/>
180+
<xsd:complexType name="CT_Body"> <!-- denormalized -->
181+
<xsd:sequence>
182+
<xsd:element name="customXml" type="CT_CustomXmlBlock"/>
183+
<xsd:element name="sdt" type="CT_SdtBlock"/>
184+
<xsd:element name="p" type="CT_P" minOccurs="0" maxOccurs="unbounded"/>
185+
<xsd:element name="tbl" type="CT_Tbl" minOccurs="0" maxOccurs="unbounded"/>
186+
<xsd:element name="proofErr" minOccurs="0" type="CT_ProofErr"/>
187+
<xsd:element name="permStart" minOccurs="0" type="CT_PermStart"/>
188+
<xsd:element name="permEnd" minOccurs="0" type="CT_Perm"/>
189+
<xsd:group ref="EG_RangeMarkupElements" minOccurs="0" maxOccurs="unbounded"/>
190+
<xsd:element name="ins" type="CT_RunTrackChange" minOccurs="0"/>
191+
<xsd:element name="del" type="CT_RunTrackChange" minOccurs="0"/>
192+
<xsd:element name="moveFrom" type="CT_RunTrackChange"/>
193+
<xsd:element name="moveTo" type="CT_RunTrackChange"/>
194+
<xsd:choice>
195+
<xsd:element ref="m:oMathPara"/>
196+
<xsd:element ref="m:oMath"/>
197+
</xsd:choice>
198+
<xsd:element name="altChunk" type="CT_AltChunk" minOccurs="0" maxOccurs="unbounded"/>
199+
<xsd:element name="sectPr" minOccurs="0" maxOccurs="1" type="CT_SectPr"/>
200+
</xsd:sequence>
201+
</xsd:complexType>
168202

169-
<xsd:element name="footnotes" type="CT_Footnotes"/>
203+
<xsd:complexType name="CT_P"> <!-- denormalized -->
204+
<xsd:sequence>
205+
<xsd:element name="pPr" type="CT_PPr" minOccurs="0"/>
206+
<xsd:element name="customXml" type="CT_CustomXmlRun"/>
207+
<xsd:element name="smartTag" type="CT_SmartTagRun"/>
208+
<xsd:element name="sdt" type="CT_SdtRun"/>
209+
<xsd:element name="dir" type="CT_DirContentRun"/>
210+
<xsd:element name="bdo" type="CT_BdoContentRun"/>
211+
<xsd:element name="r" type="CT_R"/>
212+
<xsd:element name="proofErr" minOccurs="0" type="CT_ProofErr"/>
213+
<xsd:element name="permStart" minOccurs="0" type="CT_PermStart"/>
214+
<xsd:element name="permEnd" minOccurs="0" type="CT_Perm"/>
215+
<xsd:group ref="EG_RangeMarkupElements" minOccurs="0" maxOccurs="unbounded"/>
216+
<xsd:element name="ins" type="CT_RunTrackChange" minOccurs="0"/>
217+
<xsd:element name="del" type="CT_RunTrackChange" minOccurs="0"/>
218+
<xsd:element name="moveFrom" type="CT_RunTrackChange"/>
219+
<xsd:element name="moveTo" type="CT_RunTrackChange"/>
220+
<xsd:choice>
221+
<xsd:element ref="m:oMathPara"/>
222+
<xsd:element ref="m:oMath"/>
223+
</xsd:choice>
224+
<xsd:element name="fldSimple" type="CT_SimpleField" minOccurs="0" maxOccurs="unbounded"/>
225+
<xsd:element name="hyperlink" type="CT_Hyperlink"/>
226+
<xsd:element name="subDoc" type="CT_Rel"/>
227+
</xsd:sequence>
228+
<xsd:attribute name="rsidRPr" type="ST_LongHexNumber"/>
229+
<xsd:attribute name="rsidR" type="ST_LongHexNumber"/>
230+
<xsd:attribute name="rsidDel" type="ST_LongHexNumber"/>
231+
<xsd:attribute name="rsidP" type="ST_LongHexNumber"/>
232+
<xsd:attribute name="rsidRDefault" type="ST_LongHexNumber"/>
233+
</xsd:complexType>
170234

171-
<xsd:element name="ftr" type="CT_HdrFtr"/>
235+
<xsd:complexType name="CT_Tbl"> <!-- denormalized -->
236+
<xsd:sequence>
237+
<xsd:group ref="EG_RangeMarkupElements" minOccurs="0" maxOccurs="unbounded"/>
238+
<xsd:element name="tblPr" type="CT_TblPr"/>
239+
<xsd:element name="tblGrid" type="CT_TblGrid"/>
240+
<xsd:group ref="EG_ContentRowContent" minOccurs="0" maxOccurs="unbounded"/>
241+
</xsd:sequence>
242+
</xsd:complexType>
172243

173-
<xsd:element name="hdr" type="CT_HdrFtr"/>
244+
<xsd:complexType name="CT_HdrFtr"> <!-- denormalized -->
245+
<xsd:element name="customXml" type="CT_CustomXmlBlock"/>
246+
<xsd:element name="sdt" type="CT_SdtBlock"/>
247+
<xsd:element name="p" type="CT_P" minOccurs="0" maxOccurs="unbounded"/>
248+
<xsd:element name="tbl" type="CT_Tbl" minOccurs="0" maxOccurs="unbounded"/>
249+
<xsd:element name="proofErr" minOccurs="0" type="CT_ProofErr"/>
250+
<xsd:element name="permStart" minOccurs="0" type="CT_PermStart"/>
251+
<xsd:element name="permEnd" minOccurs="0" type="CT_Perm"/>
252+
<xsd:group ref="EG_RangeMarkupElements" minOccurs="0" maxOccurs="unbounded"/>
253+
<xsd:element name="ins" type="CT_RunTrackChange" minOccurs="0"/>
254+
<xsd:element name="del" type="CT_RunTrackChange" minOccurs="0"/>
255+
<xsd:element name="moveFrom" type="CT_RunTrackChange"/>
256+
<xsd:element name="moveTo" type="CT_RunTrackChange"/>
257+
<xsd:choice>
258+
<xsd:element ref="m:oMathPara"/>
259+
<xsd:element ref="m:oMath"/>
260+
</xsd:choice>
261+
<xsd:element name="altChunk" type="CT_AltChunk" minOccurs="0" maxOccurs="unbounded"/>
262+
</xsd:complexType>
174263

175-
<xsd:complexType name="CT_Body">
264+
<xsd:complexType name="CT_FtnEdn"> <!-- denormalized -->
176265
<xsd:sequence>
177-
<xsd:choice minOccurs="0" maxOccurs="unbounded">
178-
<xsd:element name="p" type="CT_P"/>
179-
<xsd:element name="tbl" type="CT_Tbl"/>
180-
<xsd:element name="customXml" type="CT_CustomXmlBlock"/>
181-
<xsd:element name="sdt" type="CT_SdtBlock"/>
182-
<xsd:element name="proofErr" type="CT_ProofErr"/>
183-
<xsd:element name="permStart" type="CT_PermStart"/>
184-
<xsd:element name="permEnd" type="CT_Perm"/>
185-
<xsd:element name="ins" type="CT_RunTrackChange"/>
186-
<xsd:element name="del" type="CT_RunTrackChange"/>
187-
<xsd:element name="moveFrom" type="CT_RunTrackChange"/>
188-
<xsd:element name="moveTo" type="CT_RunTrackChange"/>
189-
<xsd:element ref="m:oMathPara" type="CT_OMathPara"/>
190-
<xsd:element ref="m:oMath" type="CT_OMath"/>
191-
<xsd:element name="bookmarkStart" type="CT_Bookmark"/>
192-
<xsd:element name="bookmarkEnd" type="CT_MarkupRange"/>
193-
<xsd:element name="moveFromRangeStart" type="CT_MoveBookmark"/>
194-
<xsd:element name="moveFromRangeEnd" type="CT_MarkupRange"/>
195-
<xsd:element name="moveToRangeStart" type="CT_MoveBookmark"/>
196-
<xsd:element name="moveToRangeEnd" type="CT_MarkupRange"/>
197-
<xsd:element name="commentRangeStart" type="CT_MarkupRange"/>
198-
<xsd:element name="commentRangeEnd" type="CT_MarkupRange"/>
199-
<xsd:element name="customXmlInsRangeStart" type="CT_TrackChange"/>
200-
<xsd:element name="customXmlInsRangeEnd" type="CT_Markup"/>
201-
<xsd:element name="customXmlDelRangeStart" type="CT_TrackChange"/>
202-
<xsd:element name="customXmlDelRangeEnd" type="CT_Markup"/>
203-
<xsd:element name="customXmlMoveFromRangeStart" type="CT_TrackChange"/>
204-
<xsd:element name="customXmlMoveFromRangeEnd" type="CT_Markup"/>
205-
<xsd:element name="customXmlMoveToRangeStart" type="CT_TrackChange"/>
206-
<xsd:element name="customXmlMoveToRangeEnd" type="CT_Markup"/>
207-
<xsd:element name="altChunk" type="CT_AltChunk"/>
266+
<xsd:element name="customXml" type="CT_CustomXmlBlock"/>
267+
<xsd:element name="sdt" type="CT_SdtBlock"/>
268+
<xsd:element name="p" type="CT_P" minOccurs="0" maxOccurs="unbounded"/>
269+
<xsd:element name="tbl" type="CT_Tbl" minOccurs="0" maxOccurs="unbounded"/>
270+
<xsd:element name="proofErr" minOccurs="0" type="CT_ProofErr"/>
271+
<xsd:element name="permStart" minOccurs="0" type="CT_PermStart"/>
272+
<xsd:element name="permEnd" minOccurs="0" type="CT_Perm"/>
273+
<xsd:group ref="EG_RangeMarkupElements" minOccurs="0" maxOccurs="unbounded"/>
274+
<xsd:element name="ins" type="CT_RunTrackChange" minOccurs="0"/>
275+
<xsd:element name="del" type="CT_RunTrackChange" minOccurs="0"/>
276+
<xsd:element name="moveFrom" type="CT_RunTrackChange"/>
277+
<xsd:element name="moveTo" type="CT_RunTrackChange"/>
278+
<xsd:choice>
279+
<xsd:element ref="m:oMathPara"/>
280+
<xsd:element ref="m:oMath"/>
208281
</xsd:choice>
209-
<xsd:element name="sectPr" type="CT_SectPr" minOccurs="0" maxOccurs="1"/>
282+
<xsd:element name="altChunk" type="CT_AltChunk" minOccurs="0" maxOccurs="unbounded"/>
210283
</xsd:sequence>
284+
<xsd:attribute name="type" type="ST_FtnEdn" use="optional"/>
285+
<xsd:attribute name="id" type="ST_DecimalNumber" use="required"/>
211286
</xsd:complexType>
212287

213-
<xsd:complexType name="CT_Bookmark">
288+
<xsd:group name="EG_RangeMarkupElements">
289+
<xsd:choice>
290+
<xsd:element name="bookmarkStart" type="CT_Bookmark"/>
291+
<xsd:element name="bookmarkEnd" type="CT_MarkupRange"/>
292+
<xsd:element name="moveFromRangeStart" type="CT_MoveBookmark"/>
293+
<xsd:element name="moveFromRangeEnd" type="CT_MarkupRange"/>
294+
<xsd:element name="moveToRangeStart" type="CT_MoveBookmark"/>
295+
<xsd:element name="moveToRangeEnd" type="CT_MarkupRange"/>
296+
<xsd:element name="commentRangeStart" type="CT_MarkupRange"/>
297+
<xsd:element name="commentRangeEnd" type="CT_MarkupRange"/>
298+
<xsd:element name="customXmlInsRangeStart" type="CT_TrackChange"/>
299+
<xsd:element name="customXmlInsRangeEnd" type="CT_Markup"/>
300+
<xsd:element name="customXmlDelRangeStart" type="CT_TrackChange"/>
301+
<xsd:element name="customXmlDelRangeEnd" type="CT_Markup"/>
302+
<xsd:element name="customXmlMoveFromRangeStart" type="CT_TrackChange"/>
303+
<xsd:element name="customXmlMoveFromRangeEnd" type="CT_Markup"/>
304+
<xsd:element name="customXmlMoveToRangeStart" type="CT_TrackChange"/>
305+
<xsd:element name="customXmlMoveToRangeEnd" type="CT_Markup"/>
306+
</xsd:choice>
307+
</xsd:group>
308+
309+
<xsd:complexType name="CT_Bookmark"> <!-- denormalized -->
214310
<xsd:attribute name="id" type="ST_DecimalNumber" use="required"/>
215311
<xsd:attribute name="name" type="s:ST_String" use="required"/>
216312
<xsd:attribute name="displacedByCustomXml" type="ST_DisplacedByCustomXml"/>

0 commit comments

Comments
 (0)