From 3d9529bd2f71fadd9e6edf858cb161418cc62d8a Mon Sep 17 00:00:00 2001 From: milde Date: Thu, 20 Apr 2023 23:04:43 +0000 Subject: Next iteration of "directives" documentation refactoring. git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk@9361 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docutils/docs/ref/rst/directives.txt | 224 ++++++++++++++++++++++------------- 1 file changed, 141 insertions(+), 83 deletions(-) diff --git a/docutils/docs/ref/rst/directives.txt b/docutils/docs/ref/rst/directives.txt index 12c839320..3cf29e3b7 100644 --- a/docutils/docs/ref/rst/directives.txt +++ b/docutils/docs/ref/rst/directives.txt @@ -205,7 +205,7 @@ Image :Directive Type: "image" :Doctree Element: `image <../doctree.html#image>`__ -:Directive Arguments: One, required (image URI). +:Directive Arguments: One, required (image URI_). :Directive Options: Possible (see below). :Directive Content: None. @@ -236,18 +236,18 @@ _`image options`. For example:: The following options are recognized: -``alt`` : text +``alt`` : text_ Alternate text: a short description of the image, displayed by applications that cannot display images, or spoken by applications for visually impaired users. -``height`` : `length`_ +``height`` : length_ The desired height of the image. Used to reserve space or scale the image vertically. When the "scale" option is also specified, they are combined. For example, a height of 200px and a scale of 50 is equivalent to a height of 100px with no scale. -``width`` : `length`_ or `percentage`_ of the current line width +``width`` : length_ or percentage_ of the current line width The width of the image. Used to reserve space or scale the image horizontally. As with "height" above, when the "scale" option is also specified, they are combined. @@ -272,7 +272,7 @@ The following options are recognized: text flow around it. The specific behavior depends upon the browser or rendering software used. -``target`` : text (URI or `reference name`_) +``target`` : URI_ or `reference name`_ Makes the image into a hyperlink reference ("clickable"). The option argument may be a URI (relative or absolute), or a `reference name`_ with underscore suffix (e.g. ```a name`_``). @@ -285,7 +285,7 @@ Figure :Directive Type: "figure" :Doctree Elements: figure_, image_, caption_, legend_ -:Directive Arguments: One, required (image URI). +:Directive Arguments: One, required (image URI_). :Directive Options: Possible (see below). :Directive Content: Interpreted as the figure caption and an optional legend. @@ -359,7 +359,7 @@ In addition, the following options are recognized: |wrap at this width. | +---------------------------+ -``figclass`` : text +``figclass`` : space separated list of `class names`_ Set a `"classes"`_ attribute value on the figure element. See the class_ directive below. @@ -430,7 +430,7 @@ interpreted as body elements. For example:: The following options are recognized: -``subtitle`` : text +``subtitle`` : text_ The sidebar's subtitle. and the common options class_ and name_. @@ -544,7 +544,7 @@ __ https://docutils.sourceforge.io/sandbox/stylesheets/ The following options are recognized: -``number-lines`` : integer (start line number, optional) +``number-lines`` : integer_ (start line number, optional) Precede every line with a line number. The optional argument is the number of the first line (default 1). @@ -801,14 +801,14 @@ The following options are recognized: ``align`` : "left", "center", or "right" The horizontal alignment of the table (new in Docutils 0.13). -``width`` : `length`_ or `percentage`_ +``width`` : length_ or percentage_ Sets the width of the table to the specified length or percentage of the line width. If omitted, the renderer determines the width of the table based on its contents or the column ``widths``. .. _column-widths: -``widths`` : "auto", "grid", or a list of integers +``widths`` : "auto", "grid", or a `list of integers`_ Explicitly set column widths. Specifies relative widths if used with the ``width`` option. Overrides a `table_style`_ setting or class value "colwidths-auto". @@ -878,19 +878,19 @@ The following options are recognized: ``align`` : "left", "center", or "right" The horizontal alignment of the table. (New in Docutils 0.13) -.. _delimiter: + .. _delimiter: -``delim`` : char [#char]_, "tab", or "space" +``delim`` : character_, "tab", or "space" The character used to separate data fields. The special values "tab" and "space" are converted to the respective whitespace characters. [#tab-expansion]_ Defaults to ``,`` (comma). -``encoding`` : text (encoding name) +``encoding`` : encoding_ The text encoding of the external CSV data (file or URL). Defaults to the document's `input_encoding`_. -``escape`` : char [#char]_ +``escape`` : character_ A character used to escape the delimiter_ or quote_ characters from the CSV parser. The default is no escape character -- fields may contain delimiter or newline characers if they are quoted, two quote @@ -901,12 +901,12 @@ The following options are recognized: parsing). You will need two backslashes to escape reStructuredText markup and four backslashes for a literal one. -.. _`file`: + .. _`file`: -``file`` : text (path, newlines are removed) +``file`` : path_ The local filesystem path to a CSV data file. -``header`` : text (CSV data) +``header`` : text_ (CSV data) Supplemental data for the table header, added independently of and before any ``header-rows`` from the main CSV data. Must use the same CSV format as the main CSV data. @@ -916,38 +916,38 @@ The following options are recognized: the reStructuredText `escaping mechanism`_). This will change to the documented behaviour in Docutils 0.21. -``header-rows`` : integer +``header-rows`` : integer_ The number of rows of CSV data to use in the table header. Defaults to 0. -``keepspace`` : flag (empty) +``keepspace`` : flag_ Treat whitespace immediately following the delimiter as significant. The default is to ignore such whitespace. -.. _quote: + .. _quote: -``quote`` : char [#char]_ +``quote`` : character_ The character used to quote fields containing special characters, such as the delimiter_, quote, or new-line characters. Defaults to ``"`` (quote). -``stub-columns`` : integer +``stub-columns`` : integer_ The number of table columns to use as stubs (row titles, on the left). Defaults to 0. -.. _`url`: + .. _`url`: -``url`` : text (URI, whitespace is removed) +``url`` : URI_ An Internet URI reference to a CSV data file. -``widths`` : a list of integers or "auto" +``widths`` : `list of integers`_ or "auto" A list of relative column widths. The default is equal-width columns (100%/#columns). "auto" delegates the determination of column widths to the backend (LaTeX, the HTML browser, ...). -``width`` : `length`_ or `percentage`_ +``width`` : length_ or percentage_ Sets the width of the table to the specified length or percentage of the line width. If omitted, the renderer determines the width of the table based on its contents or the column ``widths``. @@ -958,17 +958,12 @@ and the common options class_ and name_. by spreadsheet applications and commercial databases. Despite the "comma" in its name, the field delimiter_ may be any Unicode character. -.. [#char] Single character. May be specified as literal character or as - Unicode `character code`_ (cf. the unicode_ directive). - .. [#tab-expansion] Note, that tabs can be used as separator only in external files because hard tabs the directive content are `converted to spaces`__ before it reaches the CVS reader. __ restructuredtext.html#whitespace -.. _escaping mechanism: restructuredtext.html#escaping-mechanism - List Table ========== @@ -1015,24 +1010,24 @@ The following options are recognized: The horizontal alignment of the table. (New in Docutils 0.13) -``header-rows`` : integer +``header-rows`` : integer_ The number of rows of list data to use in the table header. Defaults to 0. -``stub-columns`` : integer +``stub-columns`` : integer_ The number of table columns to use as stubs (row titles, on the left). Defaults to 0. .. _table width: -``width`` : `length`_ or `percentage`_ +``width`` : length_ or percentage_ Sets the width of the table to the specified length or percentage of the line width. If omitted, the renderer determines the width of the table based on its contents or the column ``widths``. .. _column widths: -``widths`` : a list of integers or "auto" +``widths`` : `list of integers`_ or "auto" A list of relative column widths. The default is equal-width columns (100%/#columns). @@ -1090,11 +1085,11 @@ on the same line as the directive marker:: The following options are recognized: -``depth`` : integer +``depth`` : integer_ The number of section levels that are collected in the table of contents. The default is unlimited depth. -``local`` : flag (empty) +``local`` : flag_ Generate a local table of contents. Entries will only include subsections of the section in which the directive is given. If no explicit title is given, the table of contents will not be titled. @@ -1103,7 +1098,7 @@ The following options are recognized: Generate links from section headers back to the table of contents entries, the table of contents itself, or generate no back-links. -``class`` : text +``class`` : text_ (list of `class names`_) Set a `"classes"`_ attribute value on the topic element. See the class_ directive below. @@ -1140,22 +1135,22 @@ attribute set to "1". The following options are recognized: -``depth`` : integer +``depth`` : integer_ The number of section levels that are numbered by this directive. The default is unlimited depth. -``prefix`` : text +``prefix`` : text_ An arbitrary string that is prefixed to the automatically generated section numbers. It may be something like "3.2.", which will produce "3.2.1", "3.2.2", "3.2.2.1", and so on. Note that any separating punctuation (in the example, a period, ".") must be explicitly provided. The default is no prefix. -``suffix`` : text +``suffix`` : text_ An arbitrary string that is appended to the automatically generated section numbers. The default is no suffix. -``start`` : integer +``start`` : integer_ The value that will be used for the first section number. Combined with ``prefix``, this may be used to force the right numbering for a document split over several source files. The @@ -1374,13 +1369,13 @@ results in: The following options are recognized: -``ltrim`` : flag (empty) +``ltrim`` : flag_ Whitespace to the left of the substitution reference is removed. -``rtrim`` : flag (empty) +``rtrim`` : flag_ Whitespace to the right of the substitution reference is removed. -``trim`` : flag (empty) +``trim`` : flag_ Equivalent to ``ltrim`` plus ``rtrim``; whitespace on both sides of the substitution reference is removed. @@ -1425,7 +1420,7 @@ Including an External Document Fragment :Directive Type: "include" :Doctree Elements: Depend on data being included (literal_block_ with ``code`` or ``literal`` option). -:Directive Arguments: One, required (path to the file to include). +:Directive Arguments: One, required (path_ to the file to include). :Directive Options: Possible (see below). :Directive Content: None. :Configuration Setting: file_insertion_enabled_ @@ -1475,46 +1470,47 @@ __ definitions.html The following options are recognized: -``start-line`` : integer +``start-line`` : integer_ Only the content starting from this line will be included. (As usual in Python, the first line has index 0 and negative values count from the end.) -``end-line`` : integer +``end-line`` : integer_ Only the content up to (but excluding) this line will be included. -``start-after`` : text to find in the external data file - Only the content after the first occurrence of the specified text - will be included. +``start-after`` : text_ + Only the content after the first occurrence of the specified *text* + in the external data file will be included. -``end-before`` : text to find in the external data file - Only the content before the first occurrence of the specified text - (but after any ``after`` text) will be included. +``end-before`` : text_ + Only the content before the first occurrence of the specified *text* + in the external data file (but after any ``start-after`` text) + will be included. -``parser`` : text (parser name) +``parser`` : text_ (parser name) Parse the included content with the specified parser. (New in Docutils 0.17) -``literal`` : flag (empty) +``literal`` : flag_ The entire included text is inserted into the document as a single literal block. -``code`` : text (formal language, optional) +``code`` : text_ (formal language, optional) The argument and the included content are passed to the code_ directive (useful for program listings). -``number-lines`` : integer (optional start line number) - Precede every code line with a line number. +``number-lines`` : integer_ (start line number, optional) + Precede every included line with a line number. The optional argument is the number of the first line (default 1). Works only with ``code`` or ``literal``. -``encoding`` : text (encoding name) +``encoding`` : encoding_ The text encoding of the external file. Defaults to the document's input_encoding_. .. _input_encoding: ../../user/config.html#input-encoding -``tab-width`` : integer +``tab-width`` : integer_ Number of spaces for hard tab expansion. A negative value prevents expansion of hard tabs. Defaults to the tab_width_ configuration setting. @@ -1598,23 +1594,21 @@ Inline equivalents of the "raw" directive can be defined via The following options are recognized: -``file`` : text (path, newlines are removed) +``file`` : path_ The local filesystem path of a raw data file to be included. -``url`` : text (URI, whitespace is removed) +``url`` : URI_ An Internet URI reference to a raw data file to be included. -``encoding`` : text (encoding name) - The text encoding of the external raw data (file or URL). - Defaults to the document's `input_encoding`_ (if specified). +``encoding`` : encoding_ + The text encoding of the external raw data (with ``file`` or ``url``). + Defaults to the main document's `input_encoding`_ (if specified). and the common option class_. - .. _"raw" role: roles.html#raw - Class ===== @@ -1847,7 +1841,7 @@ This is the parsed result:: The following option is recognized by the "role" directive for most base roles: -``class`` : text (space separated list of `class names`_) +``class`` : space separated list of `class names`_ Set the `"classes"`_ attribute value on the element produced (``inline``, or element associated with a base class) when the custom interpreted text role is used. If no directive options are @@ -2027,13 +2021,13 @@ options: .. _class-option: .. _class: -``class`` : text (space separated list of `class names`_) +``class`` : space separated list of `class names`_ Set a `"classes"`_ attribute value on the doctree element generated by the directive. See also the class_ directive. .. _name: -``name`` : text +``name`` : text_ Add `text` to the `"names"`_ attribute of the doctree element generated by the directive. This allows `hyperlink references`_ to the element using `text` as `reference name`_. @@ -2051,33 +2045,97 @@ options: .. image:: bild.png -.. _reference name: -.. _reference names: restructuredtext.html#reference-names -.. _hyperlink target: restructuredtext.html#hyperlink-targets -.. _hyperlink references: restructuredtext.html#hyperlink-references -.. _class names: ../doctree.html#classnames-type -.. _"classes": ../doctree.html#classes -.. _identifier keys: ../doctree.html#ids-type -.. _"ids": ../doctree.html#ids -.. _"names": ../doctree.html#names +------------------------- +Common Option Value Types +------------------------- + +*"keyword"* + recognized keywords. + Used without quotes in the reStructuredText source. + + .. _character: + +*character* + single character. + May be specified as literal character or as Unicode `character code`_ + (cf. the unicode_ directive). + + .. _encoding: + +*encoding* + text encoding name. + Docutils looks it up in the list of registered codecs_ + (see also `Standard Encodings`_). + + .. _flag: + +*flag* + no value. + + .. _integer: + +*integer* + integer number. + A _`list of integers` may be comma- or whitespace-separated. + + .. _length: + +*length* + number followed by one of the supported `length units`_. + + .. _path: + +*path* + local filesystem path. Newlines are removed. + + .. _text: + +*text* + free text (with possible restrictions in parentheses). + + .. _URI: + +*URI* + `Uniform Resource Identifier`_. + Whitespace is removed, cf. `External hyperlink targets`_. + + +.. _codecs: https://docs.python.org/3/library/codecs.html +.. _Standard Encodings: + https://docs.python.org/3/library/codecs.html#standard-encodings +.. _Uniform Resource Identifier: + https://en.wikipedia.org/wiki/Uniform_Resource_Identifier + .. _block_quote: ../doctree.html#block-quote .. _caption: ../doctree.html#caption +.. _class names: ../doctree.html#classname +.. _"classes": .. _classes: ../doctree.html#classes .. _container element: ../doctree.html#container .. _decoration: ../doctree.html#decoration +.. _escaping mechanism: restructuredtext.html#escaping-mechanism +.. _external hyperlink targets: + restructuredtext.html#external-hyperlink-targets .. _figure: ../doctree.html#figure .. _footnote: ../doctree.html#footnote .. _footnote_reference: ../doctree.html#footnote-reference .. _generated: ../doctree.html#generated +.. _hyperlink references: restructuredtext.html#hyperlink-references +.. _hyperlink target: restructuredtext.html#hyperlink-targets +.. _identifier keys: ../doctree.html#ids-type +.. _"ids": ../doctree.html#ids .. _inline elements: ../doctree.html#inline-elements .. _interpreted text role: roles.html -.. _literal_block: ../doctree.html#literal-block .. _legend: ../doctree.html#legend -.. _length: restructuredtext.html#length-units +.. _length units: restructuredtext.html#length-units .. _line_block: ../doctree.html#line-block +.. _literal_block: ../doctree.html#literal-block .. _math_block: ../doctree.html#math-block +.. _"names": ../doctree.html#names .. _pending: ../doctree.html#pending .. _percentage: restructuredtext.html#percentage-units +.. _reference name: +.. _reference names: restructuredtext.html#reference-names .. _rubric: ../doctree.html#rubric .. _sidebar: ../doctree.html#sidebar .. _title attribute: ../doctree.html#title-attribute -- cgit v1.2.1