10000 rfctr: change param ref from asterisk to backticks · python-openxml/python-docx@e88e1d5 · GitHub
[go: up one dir, main page]
Skip to content

Commit e88e1d5

Browse files
scannyscanny
committed
rfctr: change param ref from asterisk to backticks
Sphinx handling is actually better, not only using italic but also a mono-width font.
1 parent cbf940c commit e88e1d5

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

74 files changed

+428
-428
lines changed

‎docs/api/document.rst

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -50,68 +50,68 @@ if that behavior is desired.
5050

5151
.. attribute:: author
5252

53-
*string* -- An entity primarily responsible for making the content of the
53+
`string` -- An entity primarily responsible for making the content of the
5454
resource.
5555

5656
.. attribute:: category
5757

58-
*string* -- A categorization of the content of this package. Example
58+
`string` -- A categorization of the content of this package. Example
5959
values might include: Resume, Letter, Financial Forecast, Proposal,
6060
or Technical Presentation.
6161

6262
.. attribute:: comments
6363

64-
*string* -- An account of the content of the resource.
64+
`string` -- An account of the content of the resource.
6565

6666
.. attribute:: content_status
6767

68-
*string* -- completion status of the document, e.g. 'draft'
68+
`string` -- completion status of the document, e.g. 'draft'
6969

7070
.. attribute:: created
7171

72-
*datetime* -- time of intial creation of the document
72+
`datetime` -- time of intial creation of the document
7373

7474
.. attribute:: identifier
7575

76-
*string* -- An unambiguous reference to the resource within a given
76+
`string` -- An unambiguous reference to the resource within a given
7777
context, e.g. ISBN.
7878

7979
.. attribute:: keywords
8080

81-
*string* -- descriptive words or short phrases likely to be used as
81+
`string` -- descriptive words or short phrases likely to be used as
8282
search terms for this document
8383

8484
.. attribute:: language
8585

86-
*string* -- language the document is written in
86+
`string` -- language the document is written in
8787

8888
.. attribute:: last_modified_by
8989

90-
*string* -- name or other identifier (such as email address) of person
90+
`string` -- name or other identifier (such as email address) of person
9191
who last modified the document
9292

9393
.. attribute:: last_printed
9494

95-
*datetime* -- time the document was last printed
95+
`datetime` -- time the document was last printed
9696

9797
.. attribute:: modified
9898

99-
*datetime* -- time the document was last modified
99+
`datetime` -- time the document was last modified
100100

101101
.. attribute:: revision
102102

103-
*int* -- number of this revision, incremented by Word each time the
103+
`int` -- number of this revision, incremented by Word each time the
104104
document is saved. Note however |docx| does not automatically increment
105105
the revision number when it saves a document.
106106

107107
.. attribute:: subject
108108

109-
*string* -- The topic of the content of the resource.
109+
`string` -- The topic of the content of the resource.
110110

111111
.. attribute:: title
112112

113-
*string* -- The name given to the resource.
113+
`string` -- The name given to the resource.
114114

115115
.. attribute:: version
116116

117-
*string* -- free-form version string
117+
`string` -- free-form version string

‎docs/api/shared.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ allowing values to be expressed in the units most appropriate to the context.
5252
:members:
5353
:undoc-members:
5454

55-
*r*, *g*, and *b* are each an integer in the range 0-255 inclusive. Using
55+
`r`, `g`, and `b` are each an integer in the range 0-255 inclusive. Using
5656
the hexidecimal integer notation, e.g. `0x42` may enhance readability
5757
where hex RGB values are in use::
5858

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,15 @@ a section title or page number. Such a header is also known as a running head.
1010

1111
A page footer is analogous in every way to a page header except that it appears at the
1212
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
13+
between pages. For brevity's sake, the term `header` is often used here to refer to what
1414
may be either a header or footer object, trusting the reader to understand its
1515
applicability to both object types.
1616

1717
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
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
2020
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*
21+
each recto page receives an `odd` page number and each verso page receives an `even`
2222
page number.
2323

2424
The header appearing on a recto page often differs from that on a verso page. Supporting

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
Sections
33
========
44

5-
Word supports the notion of a *section*, having distinct page layout settings.
5+
Word supports the notion of a `section`, having distinct page layout settings.
66
This is how, for example, a document can contain some pages in portrait layout
77
and others in landscape. Section breaks are implemented completely differently
88
from line, page, and column breaks. The former adds a ``<w:pPr><w:sectPr>``

‎docs/dev/analysis/features/shapes/index.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
Shapes (in general)
33
===================
44

5-
A graphical object that appears in a Word document is known as a *shape*.
6-
A shape can be *inline* or *floating*. An inline shape appears on a text
5+
A graphical object that appears in a Word document is known as a `shape`.
6+
A shape can be `inline` or `floating`. An inline shape appears on a text
77
baseline as though it were a character glyph and affects the line height.
88
A floating shape appears at an arbitrary location on the document and text may
99
wrap around it. Several types of shape can be placed, including a picture, a

‎docs/dev/analysis/features/styles/character-style.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ A baseline regular run::
6262
</w:r>
6363
</w:p>
6464

65-
Adding *Emphasis* character style::
65+
Adding `Emphasis` character style::
6666

6767
<w:p>
6868
<w:r>

‎docs/dev/analysis/features/styles/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Styles
1111
character-style
1212
latent-styles
1313

14-
Word supports the definition of *styles* to allow a group of formatting
14+
Word supports the definition of `styles` to allow a group of formatting
1515
properties to be easily and consistently applied to a paragraph, run, table,
1616
or numbering scheme, all at once. The mechanism is similar to how Cascading
1717
Style Sheets (CSS) works with HTML.

‎docs/dev/analysis/features/styles/latent-styles.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@ The `w:latentStyles` element used in the default Word 2011 template::
132132
Latent style behavior
133133
---------------------
134134

135-
* A style has two categories of attribute, *behavioral* and *formatting*.
135+
* A style has two categories of attribute, `behavioral` and `formatting`.
136136
Behavioral attributes specify where and when the style should appear in the
137137
user interface. Behavioral attributes can be specified for latent styles
138138
using the ``<w:latentStyles>`` element and its ``<w:lsdException>`` child
@@ -157,14 +157,14 @@ Latent style behavior
157157
value is 0 if not specified.
158158

159159
* **semiHidden**. The `semiHidden` attribute causes the style to be excluded
160-
from the recommended list. The notion of *semi* in this context is that
160+
from the recommended list. The notion of `semi` in this context is that
161161
while the style is hidden from the recommended list, it still appears in
162162
the "All Styles" list. This attribute is removed on first application of
163163
the style if an `unhideWhenUsed` attribute set |True| is also present.
164164

165165
* **unhideWhenUsed**. The `unhideWhenUsed` attribute causes any `semiHidden`
166166
attribute to be removed when the style is first applied to content. Word
167-
does *not* remove the `semiHidden` attribute just because there exists an
167+
does `not` remove the `semiHidden` attribute just because there exists an
168168
object in the document having that style. The `unhideWhenUsed` attribute is
169169
not removed along with the `semiHidden` attribute when the style is
170170
applied.

‎docs/dev/analysis/features/styles/style.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ There are six behavior properties:
1616

1717
hidden
1818
Style operates to assign formatting properties, but does not appear in
19-
the UI under any circumstances. Used for *internal* styles assigned by an
19+
the UI under any circumstances. Used for `internal` styles assigned by an
2020
application that should not be under the control of an end-user.
2121

2222
priority
@@ -98,10 +98,10 @@ semi-hidden
9898
-----------
9999

100100
The `w:semiHidden` element specifies visibility of the style in the so-called
101-
*main* user interface. For Word, this means the style gallery and the
101+
`main` user interface. For Word, this means the style gallery and the
102102
recommended, styles-in-use, and in-current-document lists. The all-styles
103103
list and current-style dropdown in the styles pane would then be considered
104-
part of an *advanced* user interface.
104+
part of an `advanced` user interface.
105105

106106
Behavior
107107
~~~~~~~~

‎docs/dev/analysis/features/table/table-props.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ a table::
2323
Autofit
2424
-------
2525

26-
Word has two algorithms for laying out a table, *fixed-width* or *autofit*.
26+
Word has two algorithms for laying out a table, *fixed-width* or `autofit`.
2727
The default is autofit. Word will adjust column widths in an autofit table
2828
based on cell contents. A fixed-width table retains its column widths
2929
regardless of the contents. Either algorithm will adjust column widths

‎docs/dev/analysis/features/text/font.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -138,24 +138,24 @@ The semantics of the three values are as follows:
138138
+-------+---------------------------------------------------------------+
139139
| value | meaning |
140140
+=======+===============================================================+
141-
| True | The effective value of the property is unconditionally *on*. |
141+
| True | The effective value of the property is unconditionally `on`. |
142142
| | Contrary settings in the style hierarchy have no effect. |
143143
+-------+---------------------------------------------------------------+
144-
| False | The effective value of the property is unconditionally *off*. |
144+
| False | The effective value of the property is unconditionally `off`. |
145145
| | Contrary settings in the style hierarchy have no effect. |
146146
+-------+---------------------------------------------------------------+
147147
| None | The element is not present. The effective value is |
148148
| | inherited from the style hierarchy. If no value for this |
149149
| | property is present in the style hierarchy, the effective |
150-
| | value is *off*. |
150+
| | value is `off`. |
151151
+-------+---------------------------------------------------------------+
152152

153153

154154
Toggle properties
155155
-----------------
156156

157157
Certain of the boolean run properties are *toggle properties*. A toggle
158-
property is one that behaves like a *toggle* at certain places in the style
158+
property is one that behaves like a `toggle` at certain places in the style
159159
hierarchy. Toggle here means that setting the property on has the effect of
160160
reversing the prior setting rather than unconditionally setting the property
161161
on.

‎docs/dev/analysis/features/text/paragraph-format.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ spacing, space before and after, and widow/orphan control.
1010
Alignment (justification)
1111
-------------------------
1212

13-
In Word, each paragraph has an *alignment* attribute that specifies how to
13+
In Word, each paragraph has an `alignment` attribute that specifies how to
1414
justify the lines of the paragraph when the paragraph is laid out on the
1515
page. Common values are left, right, centered, and justified.
1616

@@ -45,7 +45,7 @@ Paragraph spacing
4545

4646
Spacing between subsequent paragraphs is controlled by the paragraph spacing
4747
attributes. Spacing can be applied either before the paragraph, after it, or
48-
both. The concept is similar to that of *padding* or *margin* in CSS.
48+
both. The concept is similar to that of `padding` or `margin` in CSS.
4949
WordprocessingML supports paragraph spacing specified as either a length
5050
value or as a multiple of the line height; however only a length value is
5151
supported via the Word UI. Inter-paragraph spacing "overlaps", such that the

‎docs/user/hdrftr.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,15 @@ header is also known as a *running head*.
1212

1313
A *page footer* is analogous in every way to a page header except that it appears at the
1414
bottom of a page. It should not be confused with a footnote, which is not uniform
15-
between pages. For brevity's sake, the term *header* is often used here to refer to what
15+
between pages. For brevity's sake, the term `header` is often used here to refer to what
1616
may be either a header or footer object, trusting the reader to understand its
1717
applicability to both object types.
1818

1919

2020
Accessing the header for a section
2121
----------------------------------
2222

23-
Headers and footers are linked to a *section*; this allows each section to have
23+
Headers and footers are linked to a `section`; this allows each section to have
2424
a distinct header and/or footer. For example, a landscape section might have a wider
2525
header than a portrait section.
2626

@@ -33,7 +33,7 @@ for that section::
3333
>>> header
3434
<docx.section._Header object at 0x...>
3535

36-
A |_Header| object is *always* present on ``Section.header``, even when no header is
36+
A |_Header| object is `always` present on ``Section.header``, even when no header is
3737
defined for that section. The presence of an actual header definition is indicated by
3838
``_Header.is_linked_to_previous``::
3939

@@ -129,7 +129,7 @@ Here they are in a nutshell:
129129
``True`` in both those cases.
130130

131131
4. The content of a ``_Header`` object is its own content if it has a header definition.
132-
If not, its content is that of the first prior section that *does* have a header
132+
If not, its content is that of the first prior section that `does` have a header
133133
definition. If no sections have a header definition, a new one is added on the first
134134
section and all other sections inherit that one. This adding of a header definition
135135
happens the first time header content is accessed, perhaps by referencing
@@ -159,7 +159,7 @@ definition does nothing.
159159
Inherited content is automatically located
160160
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
161161

162-
Editing the content of a header edits the content of the *source* header, taking into
162+
Editing the content of a header edits the content of the `source` header, taking into
163163
account any "inheritance". So for example, if the section 2 header inherits from section
164164
1 and you edit the section 2 header, you actually change the contents of the section
165165
1 header. A new header definition is not added for section 2 unless you first explicitly

‎docs/user/quickstart.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -189,7 +189,7 @@ or over a network and don't want to get the filesystem involved.
189189
Image size
190190
~~~~~~~~~~
191191

192-
By default, the added image appears at *native* size. This is often bigger than
192+
By default, the added image appears at `native` size. This is often bigger than
193193
you want. Native size is calculated as ``pixels / dpi``. So a 300x300 pixel
194194
image having 300 dpi resolution appears in a one inch square. The problem is
195195
most images don't contain a dpi property and it defaults to 72 dpi. This would
@@ -250,7 +250,7 @@ a little about what goes on inside a paragraph. The short version is this:
250250
height, tabs, and so forth.
251251

252252
#. Character-level formatting, such as bold and italic, are applied at the
253-
*run* level. All content within a paragraph must be within a run, but there
253+
`run` level. All content within a paragraph must be within a run, but there
254254
can be more than one. So a paragraph with a bold word in the middle would
255255
need three runs, a normal one, a bold one containing the word, and another
256256
normal one for the text after.
@@ -310,7 +310,7 @@ settings. In general you can think of a character style as specifying a font,
310310
including its typeface, size, color, bold, italic, etc.
311311

312312
Like paragraph styles, a character style must already be defined in the
313-
document you open with the ``Document()`` call (*see*
313+
document you open with the ``Document()`` call (`see`
314314
:ref:`understanding_styles`).
315315

316316
A character style can be specified when adding a new run::

‎docs/user/sections.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,14 @@
33
Working with Sections
44
=====================
55

6-
Word supports the notion of a *section*, a division of a document having the
6+
Word supports the notion of a `section`, a division of a document having the
77
same page layout settings, such as margins and page orientation. This is how,
88
for example, a document can contain some pages in portrait layout and others in
99
landscape.
1010

1111
Most Word documents have only the single section that comes by default and
1212
further, most of those have no reason to change the default margins or other
13-
page layout. But when you *do* need to change the page layout, you'll need
13+
page layout. But when you `do` need to change the page layout, you'll need
1414
to understand sections to get it done.
1515

1616

‎docs/user/shapes.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,11 @@
22
Understanding pictures and other shapes
33
=======================================
44

5-
Conceptually, Word documents have two *layers*, a *text layer* and a *drawing
5+
Conceptually, Word documents have two `layers`, a *text layer* and a *drawing
66
layer*. In the text layer, text objects are flowed from left to right and from
77
top to bottom, starting a new page when the prior one is filled. In the drawing
8-
layer, drawing objects, called *shapes*, are placed at arbitrary positions.
9-
These are sometimes referred to as *floating* shapes.
8+
layer, drawing objects, called `shapes`, are placed at arbitrary positions.
9+
These are sometimes referred to as `floating` shapes.
1010

1111
A picture is a shape that can appear in either the text or drawing layer. When
1212
it appears in the text layer it is called an *inline shape*, or more

‎docs/user/styles-understanding.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,7 @@ access purposes.
125125
A style's :attr:`style_id` is used internally to key a content object such as
126126
a paragraph to its style. However this value is generated automatically by
127127
Word and is not guaranteed to be stable across saves. In general, the style
128-
id is formed simply by removing spaces from the *localized* style name,
128+
id is formed simply by removing spaces from the `localized` style name,
129129
however there are exceptions. Users of |docx| should generally avoid using
130130
the style id unless they are confident with the internals involved.
131131

@@ -155,13 +155,13 @@ Style Behavior
155155
--------------
156156

157157
In addition to collecting a set of formatting properties, a style has five
158-
properties that specify its *behavior*. This behavior is relatively simple,
158+
properties that specify its `behavior`. This behavior is relatively simple,
159159
basically amounting to when and where the style appears in the Word or
160160
LibreOffice UI.
161161

162162
The key notion to understanding style behavior is the recommended list. In
163163
the style pane in Word, the user can select which list of styles they want to
164-
see. One of these is named *Recommended* and is known as the *recommended
164+
see. One of these is named `Recommended` and is known as the *recommended
165165
list*. All five behavior properties affect some aspect of the style’s
166166
appearance in this list and in the style gallery.
167167

0 commit comments

Comments
 (0)
0