From: <go...@us...> - 2011-12-14 19:14:39
|
Revision: 7255 http://docutils.svn.sourceforge.net/docutils/?rev=7255&view=rev Author: goodger Date: 2011-12-14 19:14:33 +0000 (Wed, 14 Dec 2011) Log Message: ----------- corrected title & link Modified Paths: -------------- trunk/docutils/docs/ref/rst/directives.txt Modified: trunk/docutils/docs/ref/rst/directives.txt =================================================================== --- trunk/docutils/docs/ref/rst/directives.txt 2011-12-12 21:32:04 UTC (rev 7254) +++ trunk/docutils/docs/ref/rst/directives.txt 2011-12-14 19:14:33 UTC (rev 7255) @@ -1393,10 +1393,10 @@ .. include:: <isonum.txt> The current set of standard "include" data files consists of sets of -substitution definitions. See `reStructuredText Standard Substitution -Definition Sets`__ for details of the available standard data files. +substitution definitions. See `reStructuredText Standard Definition +Files`__ for details. -__ substitutions.html +__ definitions.html The following options are recognized: This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <mi...@us...> - 2012-10-25 12:01:18
|
Revision: 7535 http://docutils.svn.sourceforge.net/docutils/?rev=7535&view=rev Author: milde Date: 2012-10-25 12:01:12 +0000 (Thu, 25 Oct 2012) Log Message: ----------- Add link to substitution definitions for inline images. Modified Paths: -------------- trunk/docutils/docs/ref/rst/directives.txt Modified: trunk/docutils/docs/ref/rst/directives.txt =================================================================== --- trunk/docutils/docs/ref/rst/directives.txt 2012-10-25 11:48:32 UTC (rev 7534) +++ trunk/docutils/docs/ref/rst/directives.txt 2012-10-25 12:01:12 UTC (rev 7535) @@ -171,6 +171,9 @@ .. image:: picture.png +Inline images can be defined with an "image" directive in a `substitution +definition`_ + The URI for the image source file is specified in the directive argument. As with hyperlink targets, the image URI may begin on the same line as the explicit markup start and target name, or it may @@ -235,7 +238,9 @@ and the common options `:class:`_ and `:name:`_. +.. _substitution definition: restructuredtext.html#substitution-definitions + Figure ====== This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <mi...@us...> - 2013-01-17 13:08:50
|
Revision: 7587 http://docutils.svn.sourceforge.net/docutils/?rev=7587&view=rev Author: milde Date: 2013-01-17 13:08:43 +0000 (Thu, 17 Jan 2013) Log Message: ----------- Add cross link to "code" role. Modified Paths: -------------- trunk/docutils/docs/ref/rst/directives.txt Modified: trunk/docutils/docs/ref/rst/directives.txt =================================================================== --- trunk/docutils/docs/ref/rst/directives.txt 2013-01-05 17:00:50 UTC (rev 7586) +++ trunk/docutils/docs/ref/rst/directives.txt 2013-01-17 13:08:43 UTC (rev 7587) @@ -493,10 +493,13 @@ when Pygments_ is not installed or the language is not in the `supported languages and markup formats`_. +For inline code, use the `"code" role`_. + __ http://pygments.org/docs/cmdline/#generating-styles .. _Pygments: http://pygments.org/ .. _syntax_highlight: ../../user/config.html#syntax-highlight .. _supported languages and markup formats: http://pygments.org/languages/ +.. _"code" role: roles.html#code The following options are recognized: This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <mi...@us...> - 2013-03-27 16:54:07
|
Revision: 7643 http://sourceforge.net/p/docutils/code/7643 Author: milde Date: 2013-03-27 16:54:05 +0000 (Wed, 27 Mar 2013) Log Message: ----------- Syntax highlight requires a stylesheet. Modified Paths: -------------- trunk/docutils/docs/ref/rst/directives.txt Modified: trunk/docutils/docs/ref/rst/directives.txt =================================================================== --- trunk/docutils/docs/ref/rst/directives.txt 2013-03-27 16:48:25 UTC (rev 7642) +++ trunk/docutils/docs/ref/rst/directives.txt 2013-03-27 16:54:05 UTC (rev 7643) @@ -484,8 +484,9 @@ The "code" directive constructs a literal block. If the code language is specified, the content is parsed by the Pygments_ syntax highlighter and tokens are stored in nested `inline elements`_ with class arguments -according to their syntactic category. The actual highlighting can be -customized with a style-sheet (e.g. one `generated by Pygments`__). +according to their syntactic category. The actual highlighting requires +a style-sheet (e.g. one `generated by Pygments`__, see the +`sandbox/stylesheets`_ for examples). The parsing can be turned off with the syntax_highlight_ configuration setting and command line option or by specifying the language as `:class:`_ @@ -495,7 +496,8 @@ For inline code, use the `"code" role`_. -__ http://pygments.org/docs/cmdline/#generating-styles +__ http://pygments.org/docs/cmdline/#generating-styles +__ http://docutils.sourceforge.net/sandbox/stylesheets/ .. _Pygments: http://pygments.org/ .. _syntax_highlight: ../../user/config.html#syntax-highlight .. _supported languages and markup formats: http://pygments.org/languages/ This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <mi...@us...> - 2014-12-17 22:13:56
|
Revision: 7780 http://sourceforge.net/p/docutils/code/7780 Author: milde Date: 2014-12-17 22:13:49 +0000 (Wed, 17 Dec 2014) Log Message: ----------- Fix #268 wrong synonym for sectnum directive in docs. Modified Paths: -------------- trunk/docutils/docs/ref/rst/directives.txt Modified: trunk/docutils/docs/ref/rst/directives.txt =================================================================== --- trunk/docutils/docs/ref/rst/directives.txt 2014-12-17 22:02:00 UTC (rev 7779) +++ trunk/docutils/docs/ref/rst/directives.txt 2014-12-17 22:13:49 UTC (rev 7780) @@ -1005,19 +1005,19 @@ .. _sectnum: -.. _section-autonumbering: +.. _section-numbering: Automatic Section Numbering =========================== -:Directive Type: "sectnum" or "section-autonumbering" (synonyms) +:Directive Type: "sectnum" or "section-numbering" (synonyms) :Doctree Elements: pending_, generated_ :Directive Arguments: None. :Directive Options: Possible. :Directive Content: None. :Configuration Setting: sectnum_xform_ -The "sectnum" (or "section-autonumbering") directive automatically numbers +The "sectnum" (or "section-numbering") directive automatically numbers sections and subsections in a document (if not disabled by the ``--no-section-numbering`` command line option or the `sectnum_xform`_ configuration setting). This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <mi...@us...> - 2016-07-28 22:01:47
|
Revision: 7960 http://sourceforge.net/p/docutils/code/7960 Author: milde Date: 2016-07-28 22:01:45 +0000 (Thu, 28 Jul 2016) Log Message: ----------- Really add documentation for [ 120 ] Modified Paths: -------------- trunk/docutils/docs/ref/rst/directives.txt Modified: trunk/docutils/docs/ref/rst/directives.txt =================================================================== --- trunk/docutils/docs/ref/rst/directives.txt 2016-07-28 21:56:00 UTC (rev 7959) +++ trunk/docutils/docs/ref/rst/directives.txt 2016-07-28 22:01:45 UTC (rev 7960) @@ -756,8 +756,8 @@ (New in Docutils 0.3.1) -The "table" directive is used to create a titled table, to associate a -title with a table:: +The "table" directive is used to associate a +title with a table or specify options:: .. table:: Truth table for "not" @@ -774,6 +774,16 @@ The horizontal alignment of the table. (New in Docutils 0.13) +``widths`` : "auto", "grid" or a list of integers + + A comma- or space-separated list of relative column widths. + The default is the width of the corresponding input columns + (in characters). + + The special values "auto" or "grid" may be used by writers to decide + whether to delegate the determination of column widths to the backend + (LaTeX, the HTML browser, ...). + and the common options `:class:`_ and `:name:`_. .. _csv-table: @@ -835,10 +845,14 @@ The following options are recognized: -``widths`` : integer [, integer...] +``widths`` : integer [, integer...] or "auto" A comma- or space-separated list of relative column widths. The default is equal-width columns (100%/#columns). + The special value "auto" may be used by writers to decide + whether to delegate the determination of column widths to the backend + (LaTeX, the HTML browser, ...). + ``header-rows`` : integer The number of rows of CSV data to use in the table header. Defaults to 0. @@ -936,10 +950,14 @@ The following options are recognized: -``widths`` : integer [integer...] +``widths`` : integer [integer...] or "auto" A comma- or space-separated list of relative column widths. The default is equal-width columns (100%/#columns). + The special value "auto" may be used by writers to decide + whether to delegate the determination of column widths to the backend + (LaTeX, the HTML browser, ...). + ``header-rows`` : integer The number of rows of list data to use in the table header. Defaults to 0. This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <mi...@us...> - 2017-03-12 15:59:40
|
Revision: 8047 http://sourceforge.net/p/docutils/code/8047 Author: milde Date: 2017-03-12 15:59:37 +0000 (Sun, 12 Mar 2017) Log Message: ----------- Fix typo. (Thanks to Benjamin Peng for spotting it.) Modified Paths: -------------- trunk/docutils/docs/ref/rst/directives.txt Modified: trunk/docutils/docs/ref/rst/directives.txt =================================================================== --- trunk/docutils/docs/ref/rst/directives.txt 2017-03-11 12:09:36 UTC (rev 8046) +++ trunk/docutils/docs/ref/rst/directives.txt 2017-03-12 15:59:37 UTC (rev 8047) @@ -48,6 +48,17 @@ Admonitions ------------- +.. From Webster's Revised Unabridged Dictionary (1913) [web1913]: + Admonition + Gentle or friendly reproof; counseling against a fault or + error; expression of authoritative advice; friendly caution + or warning. + + Syn: {Admonition}, {Reprehension}, {Reproof}. + + Usage: Admonition is prospective, and relates to moral delinquencies; + its object is to prevent further transgression. + .. _attention: .. _caution: .. _danger: @@ -760,7 +771,6 @@ title with a table or specify options, e.g.:: .. table:: Truth table for "not" - :widths: auto ===== ===== This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <mi...@us...> - 2017-10-17 13:32:27
|
Revision: 8186 http://sourceforge.net/p/docutils/code/8186 Author: milde Date: 2017-10-17 13:32:24 +0000 (Tue, 17 Oct 2017) Log Message: ----------- Hamonise and fix directive documentation. Modified Paths: -------------- trunk/docutils/docs/ref/rst/directives.txt Modified: trunk/docutils/docs/ref/rst/directives.txt =================================================================== --- trunk/docutils/docs/ref/rst/directives.txt 2017-10-17 12:55:45 UTC (rev 8185) +++ trunk/docutils/docs/ref/rst/directives.txt 2017-10-17 13:32:24 UTC (rev 8186) @@ -346,7 +346,7 @@ :Directive Type: "topic" :Doctree Element: topic_ -:Directive Arguments: 1, required (topic title). +:Directive Arguments: One, required (topic title). :Directive Options: `:class:`_, `:name:`_ :Directive Content: Interpreted as the topic body. @@ -539,7 +539,7 @@ :Directive Type: "math" :Doctree Element: math_block_ -:Directive Arguments: One, optional: prepended to content. +:Directive Arguments: None. :Directive Options: `:class:`_, `:name:`_ :Directive Content: Becomes the body of the math block. (Content blocks separated by a blank line are put in @@ -579,7 +579,7 @@ :Directive Type: "rubric" :Doctree Element: rubric_ -:Directive Arguments: 1, required (rubric text). +:Directive Arguments: One, required (rubric text). :Directive Options: `:class:`_, `:name:`_ :Directive Content: None. @@ -758,7 +758,7 @@ :Directive Type: "table" :Doctree Element: table_ -:Directive Arguments: 1, optional (table title). +:Directive Arguments: One, optional (table title). :Directive Options: Possible (see below). :Directive Content: A normal reStructuredText table. @@ -808,7 +808,7 @@ :Directive Type: "csv-table" :Doctree Element: table_ -:Directive Arguments: 1, optional (table title). +:Directive Arguments: One, optional (table title). :Directive Options: Possible (see below). :Directive Content: A CSV (comma-separated values) table. @@ -935,7 +935,7 @@ :Directive Type: "list-table" :Doctree Element: table_ -:Directive Arguments: 1, optional (table title). +:Directive Arguments: One, optional (table title). :Directive Options: Possible (see below). :Directive Content: A uniform two-level bullet list. @@ -1893,7 +1893,7 @@ :Directive Type: "title" :Doctree Element: None. -:Directive Arguments: 1, required (the title text). +:Directive Arguments: One, required (the title text). :Directive Options: None. :Directive Content: None. This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <mi...@us...> - 2019-10-30 12:10:27
|
Revision: 8408 http://sourceforge.net/p/docutils/code/8408 Author: milde Date: 2019-10-30 12:10:25 +0000 (Wed, 30 Oct 2019) Log Message: ----------- Update/clarify rationale for "identifier normalization". Modified Paths: -------------- trunk/docutils/docs/ref/rst/directives.txt Modified: trunk/docutils/docs/ref/rst/directives.txt =================================================================== --- trunk/docutils/docs/ref/rst/directives.txt 2019-10-29 22:48:34 UTC (rev 8407) +++ trunk/docutils/docs/ref/rst/directives.txt 2019-10-30 12:10:25 UTC (rev 8408) @@ -1724,6 +1724,8 @@ .. topic:: Rationale: + Identifier keys must be valid in all supported output formats. + For HTML 4.1 + CSS1 compatibility, identifiers should have no underscores, colons, or periods. Hyphens may be used. @@ -1736,7 +1738,7 @@ -- http://www.w3.org/TR/html401/types.html#type-name - - The `CSS1 spec`_ [#]_ defines identifiers based on the "name" token + - The `CSS1 spec`_ defines identifiers based on the "name" token ("flex" tokenizer notation below; "latin1" and "escape" 8-bit characters have been replaced with XML entities):: @@ -1746,25 +1748,26 @@ nmchar [-A-Za-z0-9]|{latin1}|{escape} name {nmchar}+ - The CSS rule does not include underscores ("_"), colons (":"), or - periods ("."), therefore `"classes"`_ and `"ids"`_ attributes should not - contain these characters. Combined with HTML's requirements (the + The CSS1 rule requires underscores ("_"), colons (":"), and + periods (".") to be escaped [#]_, + therefore `"classes"`_ and `"ids"`_ attributes should not + contain these characters. Combined with HTML4.1 requirements (the first character must be a letter; no "unicode", "latin1", or "escape" characters), this results in the regular expression ``[A-Za-z][-A-Za-z0-9]*``. Docutils adds a normalization by downcasing and merge of consecutive hyphens. - .. [#] The CSS Working Group considers the CSS1 specification to be - obsolete__. `CSS2.1 identifiers`__ may also use underscores (_) - and any backslash escaped character. + .. [#] CSS identifiers may use underscores ("_") directly in + `CSS Level 1`__, `CSS2.1`__, CSS2.2__, and CSS3__. + __ https://www.w3.org/TR/CSS21/syndata.html#value-def-identifier __ https://www.w3.org/TR/CSS/#css-level-1 - __ https://www.w3.org/TR/CSS21/syndata.html#value-def-identifier + __ https://www.w3.org/TR/CSS22/syndata.html + __ https://www.w3.org/TR/css-syntax-3/#typedef-ident-token .. _HTML 4.01 spec: http://www.w3.org/TR/html401/ .. _CSS1 spec: http://www.w3.org/TR/REC-CSS1 - .. _role: Custom Interpreted Text Roles This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <mi...@us...> - 2020-09-08 10:00:06
|
Revision: 8560 http://sourceforge.net/p/docutils/code/8560 Author: milde Date: 2020-09-08 10:00:02 +0000 (Tue, 08 Sep 2020) Log Message: ----------- Fix broken link. Thanks to Kevin Cole for reporting. Modified Paths: -------------- trunk/docutils/docs/ref/rst/directives.txt Modified: trunk/docutils/docs/ref/rst/directives.txt =================================================================== --- trunk/docutils/docs/ref/rst/directives.txt 2020-09-08 09:59:17 UTC (rev 8559) +++ trunk/docutils/docs/ref/rst/directives.txt 2020-09-08 10:00:02 UTC (rev 8560) @@ -569,7 +569,7 @@ For inline formulas, use the `"math" role`_. -.. _Short Math Guide: ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf +.. _Short Math Guide: http://tug.ctan.org/info/short-math-guide/short-math-guide.pdf .. _"math" role: roles.html#math .. _math_output: ../../user/config.html#math-output This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <mi...@us...> - 2022-02-11 14:47:53
|
Revision: 9008 http://sourceforge.net/p/docutils/code/9008 Author: milde Date: 2022-02-11 14:47:51 +0000 (Fri, 11 Feb 2022) Log Message: ----------- Update documentation of the "table" directive's "widths" option. The default behaviour of the "html5" writer resembles ``:widths: auto`` since Docutils 0.18. Modified Paths: -------------- trunk/docutils/docs/ref/rst/directives.txt Modified: trunk/docutils/docs/ref/rst/directives.txt =================================================================== --- trunk/docutils/docs/ref/rst/directives.txt 2022-02-10 09:10:34 UTC (rev 9007) +++ trunk/docutils/docs/ref/rst/directives.txt 2022-02-11 14:47:51 UTC (rev 9008) @@ -804,21 +804,28 @@ .. _column-widths: ``widths`` : "auto", "grid", or a list of integers - A list of relative column widths. - The default is the width of the input columns (in characters). + Explicitly set column widths. + Specifies relative widths if used with the ``width`` option. + Overrides a `table_style`_ setting or class value "colwidths-auto". + The default depends on the `table_style`_ configuration setting. *"auto"* delegates the determination of column widths to the backend (LaTeX, the HTML browser, ...). + Default for the `html5 writer`_ - *"grid"* restores the default, overriding a `table_style`_ or class - value "colwidths-auto". + *"grid"* determines column widths from the widths of the input columns + (in characters). + Default for most writers. + A *list of integers* is used instead of the input column widths. + Implies *"grid"*. + Plus the common options class_ and name_. .. _reStructuredText table: restructuredtext.html#tables .. _table_style: ../../user/config.html#table-style +.. _html5 writer: ../../user/html.html#html5-polyglot - .. _csv-table: CSV Table This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <mi...@us...> - 2023-04-19 23:31:26
|
Revision: 9359 http://sourceforge.net/p/docutils/code/9359 Author: milde Date: 2023-04-19 23:31:23 +0000 (Wed, 19 Apr 2023) Log Message: ----------- Review rST "directives" documentation. Unify content type descriptions. Add cross-links. Reword for better clarity. Modified Paths: -------------- trunk/docutils/docs/ref/rst/directives.txt Modified: trunk/docutils/docs/ref/rst/directives.txt =================================================================== --- trunk/docutils/docs/ref/rst/directives.txt 2023-04-19 23:31:13 UTC (rev 9358) +++ trunk/docutils/docs/ref/rst/directives.txt 2023-04-19 23:31:23 UTC (rev 9359) @@ -272,7 +272,7 @@ text flow around it. The specific behavior depends upon the browser or rendering software used. -``target`` : text (URI or reference name) +``target`` : text (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`_``). @@ -544,7 +544,7 @@ The following options are recognized: -``number-lines`` : [integer] (start line number) +``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). @@ -765,13 +765,15 @@ Tables -------- -Formal tables need more structure than the reStructuredText syntax -supplies. Tables may be given titles with the table_ directive. +Formal tables need more structure than the reStructuredText `table syntax`_ +supplies. Tables may be given titles with the "table_" directive. Sometimes reStructuredText tables are inconvenient to write, or table -data in a standard format is readily available. The csv-table_ -directive supports CSV data. +data in a standard format is readily available. The "csv-table_" +directive supports CSV [#CSV]_ data. +.. _table syntax: restructuredtext.html#tables + Table ===== @@ -839,19 +841,17 @@ :Directive Arguments: One, optional (table title). :Directive Options: Possible (see below). :Directive Content: A CSV (comma-separated values) table - or (with the `:file:`_ or `:url:`_ options) None + or (with the `file`_ or `url`_ options) None .. WARNING:: - The "csv-table" directive's `:file:`_ and `:url:`_ options represent + The "csv-table" directive's `file`_ and `url`_ options represent potential security holes. They can be disabled with the "file_insertion_enabled_" runtime setting. The "csv-table" directive is used to create a table from CSV -(comma-separated values) data. CSV is a common data format generated -by spreadsheet applications and commercial databases. The data may be -internal (an integral part of the document) or external (a separate -file). +(comma-separated values) [#CSV]_ data. The data may be internal +(an integral part of the document) or external (a separate file). * Block markup and inline markup within cells is supported. Line ends are recognized within quoted cells. @@ -877,42 +877,44 @@ ``align`` : "left", "center", or "right" The horizontal alignment of the table. (New in Docutils 0.13) - -.. _delimiter: -``delim`` : char | "tab" | "space" - A one-character string [#char-or-uni]_ used to separate data fields. +.. _delimiter: + +``delim`` : char [#char]_, "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`` : string +``encoding`` : text (encoding name) The text encoding of the external CSV data (file or URL). Defaults to the document's `input_encoding`_. -``escape`` : char - A one-character string [#char-or-uni]_ used to escape the delimiter_ - or quote_ characters from the CSV parser. - The default is no CSV-escape character -- - quote data fields containing the delimiter and double-up the quote - character, e.g. ``"He said, ""Hi!"""``. - The reStructuredText `escaping mechanism`_ is applied - after CSV parsing as part of parsing the field content for - reStructuredText markup. +``escape`` : char [#char]_ + 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 + characters stand for a literal one, e.g., ``"He said, ""Hi!"""``. -.. _`:file:`: + .. Caution:: Setting ``escape`` to ``\`` (backslash) interferes with + the reStructuredText `escaping mechanism`_ (applied after CSV + parsing). You will need two backslashes to escape reStructuredText + markup and four backslashes for a literal one. -``file`` : string (newlines removed) +.. _`file`: + +``file`` : text (path, newlines are removed) The local filesystem path to a CSV data file. -``header`` : 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. - .. note:: Currently, the header option uses a hard-coded - CSV dialect variant with the backslash as escape character. - This will change to the documented behaviour in Docutils 0.21. + .. Important:: Currently, the header option uses a hard-coded CSV + dialect with the backslash as escape character (interfering with + the reStructuredText `escaping mechanism`_). This will change to + the documented behaviour in Docutils 0.21. ``header-rows`` : integer The number of rows of CSV data to use in the table header. @@ -924,10 +926,9 @@ .. _quote: -``quote`` : char - A one-character string [#char-or-uni]_ used to quote fields - containing special characters, such as the delimiter, quote, - or new-line characters. +``quote`` : char [#char]_ + The character used to quote fields containing special characters, + such as the delimiter_, quote, or new-line characters. Defaults to ``"`` (quote). ``stub-columns`` : integer @@ -934,12 +935,12 @@ The number of table columns to use as stubs (row titles, on the left). Defaults to 0. -.. _`:url:`: +.. _`url`: -``url`` : string (whitespace removed) - An Internet URL reference to a CSV data file. +``url`` : text (URI, whitespace is removed) + An Internet URI reference to a CSV data file. -``widths`` : integer [integer...] or "auto" +``widths`` : a list of integers or "auto" A list of relative column widths. The default is equal-width columns (100%/#columns). @@ -953,12 +954,16 @@ and the common options class_ and name_. -.. [#char-or-uni] May be specified as a *Unicode character code*; - see the unicode_ directive for syntax details. +.. [#CSV] CSV (comma separated values) is a common data format generated + 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 all hard `tabs in rST sources are converted to - spaces`__. + external files because hard tabs the directive content are + `converted to spaces`__ before it reaches the CVS reader. __ restructuredtext.html#whitespace @@ -1027,7 +1032,7 @@ .. _column widths: -``widths`` : integer [integer...] or "auto" +``widths`` : a list of integers or "auto" A list of relative column widths. The default is equal-width columns (100%/#columns). @@ -1139,7 +1144,7 @@ The number of section levels that are numbered by this directive. The default is unlimited depth. -``prefix`` : string +``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 @@ -1146,7 +1151,7 @@ any separating punctuation (in the example, a period, ".") must be explicitly provided. The default is no prefix. -``suffix`` : string +``suffix`` : text An arbitrary string that is appended to the automatically generated section numbers. The default is no suffix. @@ -1329,6 +1334,8 @@ The arguments, separated by spaces, can be: +.. _character code: + * **character codes** as - decimal numbers or @@ -1484,7 +1491,7 @@ Only the content before the first occurrence of the specified text (but after any ``after`` text) will be included. -``parser`` : parser name +``parser`` : text (parser name) Parse the included content with the specified parser. (New in Docutils 0.17) @@ -1492,16 +1499,16 @@ The entire included text is inserted into the document as a single literal block. -``code`` : [string] (formal language) +``code`` : text (formal language, optional) The argument and the included content are passed to the code_ directive (useful for program listings). -``number-lines`` : [integer] (start line number) +``number-lines`` : integer (optional start line number) Precede every code line with a line number. The optional argument is the number of the first line (default 1). Works only with ``code`` or ``literal``. -``encoding`` : string +``encoding`` : text (encoding name) The text encoding of the external file. Defaults to the document's input_encoding_. @@ -1591,13 +1598,13 @@ The following options are recognized: -``file`` : string (newlines removed) +``file`` : text (path, newlines are removed) The local filesystem path of a raw data file to be included. -``url`` : string (whitespace removed) - An Internet URL reference to a raw data file to be included. +``url`` : text (URI, whitespace is removed) + An Internet URI reference to a raw data file to be included. -``encoding`` : string +``encoding`` : text (encoding name) The text encoding of the external raw data (file or URL). Defaults to the document's `input_encoding`_ (if specified). @@ -1840,7 +1847,7 @@ The following option is recognized by the "role" directive for most base roles: -``class`` : text +``class`` : text (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 This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <mi...@us...> - 2023-04-20 23:04:45
|
Revision: 9361 http://sourceforge.net/p/docutils/code/9361 Author: milde Date: 2023-04-20 23:04:43 +0000 (Thu, 20 Apr 2023) Log Message: ----------- Next iteration of "directives" documentation refactoring. Modified Paths: -------------- trunk/docutils/docs/ref/rst/directives.txt Modified: trunk/docutils/docs/ref/rst/directives.txt =================================================================== --- trunk/docutils/docs/ref/rst/directives.txt 2023-04-19 23:31:31 UTC (rev 9360) +++ trunk/docutils/docs/ref/rst/directives.txt 2023-04-20 23:04:43 UTC (rev 9361) @@ -205,7 +205,7 @@ :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 @@ 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 @@ 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 @@ :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 @@ |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 @@ The following options are recognized: -``subtitle`` : text +``subtitle`` : text_ The sidebar's subtitle. and the common options class_ and name_. @@ -544,7 +544,7 @@ 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,7 +801,7 @@ ``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``. @@ -808,7 +808,7 @@ .. _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 @@ ``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 @@ 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,31 +916,31 @@ 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). @@ -947,7 +947,7 @@ "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,9 +958,6 @@ 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. @@ -967,9 +964,7 @@ __ restructuredtext.html#whitespace -.. _escaping mechanism: restructuredtext.html#escaping-mechanism - List Table ========== @@ -1015,17 +1010,17 @@ 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``. @@ -1032,7 +1027,7 @@ .. _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 @@ 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 @@ 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,11 +1135,11 @@ 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 @@ -1151,11 +1146,11 @@ 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 @@ 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 @@ :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 @@ 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 +``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_ + 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. -``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. - -``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 @@ 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 @@ 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 @@ .. _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 @@ .. 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 This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <mi...@us...> - 2023-06-29 13:49:44
|
Revision: 9419 http://sourceforge.net/p/docutils/code/9419 Author: milde Date: 2023-06-29 13:49:42 +0000 (Thu, 29 Jun 2023) Log Message: ----------- Fix links in `Docutils directives` documentation. Modified Paths: -------------- trunk/docutils/docs/ref/rst/directives.txt Modified: trunk/docutils/docs/ref/rst/directives.txt =================================================================== --- trunk/docutils/docs/ref/rst/directives.txt 2023-06-29 13:49:33 UTC (rev 9418) +++ trunk/docutils/docs/ref/rst/directives.txt 2023-06-29 13:49:42 UTC (rev 9419) @@ -284,7 +284,9 @@ ====== :Directive Type: "figure" -:Doctree Elements: figure_, image_, caption_, legend_ +:Doctree Elements: `figure <../doctree.html#figure>`__, + `image <../doctree.html#image>`__, + caption_, legend_ :Directive Arguments: One, required (image URI_). :Directive Options: Possible (see below). :Directive Content: Interpreted as the figure caption and an optional @@ -2116,7 +2118,6 @@ .. _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 This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <mi...@us...> - 2024-05-02 15:55:34
|
Revision: 9669 http://sourceforge.net/p/docutils/code/9669 Author: milde Date: 2024-05-02 15:55:31 +0000 (Thu, 02 May 2024) Log Message: ----------- More precise wording in directives documentation. Use "caption" instead of "title" for the short description of a table. While the XML Exchange Model employed in the Docutils Document Tree uses a <title> element for "historic reasons", the main output formats HTML and LaTeX both call it a "caption". Modified Paths: -------------- trunk/docutils/docs/ref/rst/directives.txt Modified: trunk/docutils/docs/ref/rst/directives.txt =================================================================== --- trunk/docutils/docs/ref/rst/directives.txt 2024-05-02 15:55:23 UTC (rev 9668) +++ trunk/docutils/docs/ref/rst/directives.txt 2024-05-02 15:55:31 UTC (rev 9669) @@ -805,7 +805,7 @@ :Directive Content: Interpreted as body elements. The "container" directive surrounds its contents (arbitrary body -elements) with a generic block-level "container" element. +elements) with a generic block-level "container" element. Combined with the optional argument, this is an extension mechanism for users & applications. For example:: @@ -844,13 +844,13 @@ :Directive Type: "table" :Doctree Element: `\<table>`_ -:Directive Arguments: one, optional (table title) +:Directive Arguments: one, optional (table caption) :Directive Options: `see below <table options_>`__ :Directive Content: A normal `reStructuredText table`_. :Configuration Setting: table_style_ -The "table" directive is used to associate a -title with a table or specify options, e.g.:: +The "table" directive is used to provide a table caption +or specify options, e.g.:: .. table:: Truth table for "not" :widths: auto @@ -907,7 +907,7 @@ :Directive Type: "csv-table" :Doctree Element: `\<table>`_ -:Directive Arguments: one, optional (table title) +:Directive Arguments: one, optional (table caption) :Directive Options: `see below <csv-table options_>`__ :Directive Content: A CSV (comma-separated values) table or (with the `file`_ or `url`_ options) none. @@ -1042,7 +1042,7 @@ :Directive Type: "list-table" :Doctree Element: `\<table>`_ -:Directive Arguments: one, optional (table title) +:Directive Arguments: one, optional (table caption) :Directive Options: `see below <list-table options_>`__ :Directive Content: A uniform two-level bullet list. :Configuration Setting: table_style_ This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |