diff options
Diffstat (limited to 'docutils/docs')
| -rw-r--r-- | docutils/docs/dev/rst/alternatives.txt | 27 | ||||
| -rw-r--r-- | docutils/docs/dev/todo.txt | 182 | ||||
| -rw-r--r-- | docutils/docs/ref/rst/directives.txt | 90 |
3 files changed, 186 insertions, 113 deletions
diff --git a/docutils/docs/dev/rst/alternatives.txt b/docutils/docs/dev/rst/alternatives.txt index ba5c7f448..726b536fb 100644 --- a/docutils/docs/dev/rst/alternatives.txt +++ b/docutils/docs/dev/rst/alternatives.txt @@ -3134,6 +3134,33 @@ idea, and there is no "tool tip" in formats other than HTML. Add a "term" role for unfamiliar or specialized terminology? Probably not; there is no real use case, and emphasis is enough for most cases. + +Object references +================= + +We need syntax for `object references`_. + + - Parameterized substitutions? For example:: + + See |figure (figure name)| on |page (figure name)|. + + .. |figure (name)| figure-ref:: (name) + .. |page (name)| page-ref:: (name) + + The result would be:: + + See figure 3.11 on page 157. + + But this would require substitution directives to be processed at + reference-time, not at definition-time as they are now. Or, + perhaps the directives could just leave ``pending`` elements + behind, and the transforms do the work? How to pass the data + through? Too complicated. Use interpreted text roles. + +.. _object references: + ../todo.html#object-numbering-and-object-references + + .. Local Variables: diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt index 2c636bc47..8a2c05b6f 100644 --- a/docutils/docs/dev/todo.txt +++ b/docutils/docs/dev/todo.txt @@ -42,6 +42,8 @@ Below are action items that must be added and issues that must be addressed before Docutils can be considered suitable to be proposed for inclusion in the Python standard library. +Many of these are now handled by Sphinx_ + * Support for `document splitting`_. May require some major code rework. @@ -61,13 +63,10 @@ for inclusion in the Python standard library. * Plugin support. -* A LaTeX writer making use of (La)TeX's power, so that the rendering - of the resulting documents is more easily customizable. (Similar to - what you wrote about a new HTML Writer.) - * Suitability for `Python module documentation <http://docutils.sf.net/sandbox/README.html#documenting-python>`_. +.. _Sphinx: http://sphinx.pocoo.org/ General ======= @@ -212,103 +211,6 @@ General * Perhaps the ``Component.supports`` method should deal with individual features ("meta" etc.) instead of formats ("html" etc.)? -* Add _`object numbering and object references` (tables & figures). - These would be the equivalent of DocBook's "formal" elements. - - We may need _`persistent sequences`, such as chapter numbers. See - `OpenOffice.org XML`_ "fields". Should the sequences be automatic - or manual (user-specifyable)? - - We need to name the objects: - - - "name" option for the "figure" directive? :: - - .. figure:: image.png - :name: image's name - - Same for the "table" directive:: - - .. table:: optional title here - :name: table's name - - ===== ===== - x not x - ===== ===== - True False - False True - ===== ===== - - This would also allow other options to be set, like border - styles. The same technique could be used for other objects. - - A preliminary "table" directive has been implemented, supporting - table titles. Perhaps the name should derive from the title. - - - The object could also be done this way:: - - .. _figure name: - - .. figure:: image.png - - This may be a more general solution, equally applicable to tables. - However, explicit naming using an option seems simpler to users. - - - Perhaps the figure name could be incorporated into the figure - definition, as an optional inline target part of the directive - argument:: - - .. figure:: _`figure name` image.png - - Maybe with a delimiter:: - - .. figure:: _`figure name`: image.png - - Or some other, simpler syntax. - - We'll also need syntax for object references. See `OpenOffice.org - XML`_ "reference fields": - - - Parameterized substitutions? For example:: - - See |figure (figure name)| on |page (figure name)|. - - .. |figure (name)| figure-ref:: (name) - .. |page (name)| page-ref:: (name) - - The result would be:: - - See figure 3.11 on page 157. - - But this would require substitution directives to be processed at - reference-time, not at definition-time as they are now. Or, - perhaps the directives could just leave ``pending`` elements - behind, and the transforms do the work? How to pass the data - through? Too complicated. - - - An interpreted text approach is simpler and better:: - - See :figure:`figure name` on :page:`figure name`. - - The "figure" and "page" roles could generate appropriate - boilerplate text. The position of the role (prefix or suffix) - could also be utilized. - - See `Interpreted Text`_ below. - - - We could leave the boilerplate text up to the document:: - - See Figure :fig:`figure name` on page :pg:`figure name`. - - - Reference boilerplate could be specified in the document - (defaulting to nothing):: - - .. fignum:: - :prefix-ref: "Figure " - :prefix-caption: "Fig. " - :suffix-caption: : - - .. _OpenOffice.org XML: http://xml.openoffice.org/ - * Think about _`large documents` made up of multiple subdocument files. Issues: continuity (`persistent sequences`_ above), cross-references (`name-to-id mapping file`_ above and `targets in @@ -581,6 +483,75 @@ General latex writer to switch to a LaTeX generated ToC (currently, the latex writer calls it "use_latex_toc"). +object numbering and object references +-------------------------------------- + +For equations, tables & figures. + +These would be the equivalent of DocBook's "formal" elements. + +In LaTeX, automatic counters are implemented for sections, equations and +floats (figures, tables) (configurable via stylesheets or in the +latex-preamble). Objects can be given `reference names`_ with the +``\label{<refname}`` command, ``\ref{<refname>}`` inserts the +corresponding number. + +No such mechanism exists in HTML. + +* We need _`persistent sequences`, similar to chapter and footnote + numbers. See `OpenOffice.org XML`_ "fields". + + - Should the sequences be automatic or manual (user-specifyable)? + +* It is already possible to give `reference names`_ to objects via + internal hyperlink targets or the "name" directive option:: + + .. _figure name: + + .. figure:: image.png + + or :: + + .. figure:: image.png + :name: figure name + + A "table" directive has been implemented, supporting table titles. + + Perhaps the name could derive from the title/caption? + + .. _reference names: ../ref/rst/restructuredtext.html#reference-names + +* We need syntax for object references. Cf. `OpenOffice.org XML`_ + "reference fields": + + - Parameterized substitutions are too complicated + (cf. `or not to do`: `object references`_) + + - An interpreted text approach is simpler and better:: + + See Figure :ref:`figure name` and Equation :ref:`eq:identity`. + + - "equation", "figure", and "page" roles could generate appropriate + boilerplate text:: + + See :figure:`figure name` on :page:`figure name`. + + See `Interpreted Text`_ below. + + Reference boilerplate could be specified in the document + (defaulting to nothing):: + + .. fignum:: + :prefix-ref: "Figure " + :prefix-caption: "Fig. " + :suffix-caption: : + + The position of the role (prefix or suffix) could also be utilized + + .. _OpenOffice.org XML: http://xml.openoffice.org/ + .. _object references: rst/alternatives.html#object-references + + Documentation ============= @@ -1333,12 +1304,17 @@ images OpenOffice output ````````````````` -* MathML_ can be imported by the Math module. +* The `OpenDocument standard`_ version 1.1 says: + + Mathematical content is represented by MathML 2.0 - However, putting MathML into an ODP file seems tricky: + However, putting MathML into an ODP file seems tricky as these + (maybe outdated) links suppose: http://idippedut.dk/post/2008/01/25/Do-your-math-ODF-and-MathML.aspx http://idippedut.dk/post/2008/03/03/Now-I-get-it-ODF-and-MathML.aspx + .. _OpenDocument standard: + http://www.oasis-open.org/standards#opendocumentv1.1 * OOoLaTeX__: "a set of macros designed to bring the power of LaTeX into OpenOffice." diff --git a/docutils/docs/ref/rst/directives.txt b/docutils/docs/ref/rst/directives.txt index e46f22628..cba118406 100644 --- a/docutils/docs/ref/rst/directives.txt +++ b/docutils/docs/ref/rst/directives.txt @@ -231,12 +231,15 @@ The following options are recognized: ``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. ``name_``). + `reference name`_ with underscore suffix (e.g. ```a name`_``). ``class`` : text Set a "classes" attribute value on the image element. See the class_ directive below. +``name`` : text + Attach text as a `reference name`_ to the image element. [#name-option]_ + Figure ====== @@ -353,12 +356,15 @@ interpreted as body elements. For example:: the body of the topic, and are interpreted as body elements. -The following option is recognized: +The following options are recognized: ``class`` : text Set a "classes" attribute value on the topic element. See the class_ directive below. +``name`` : text + Attach text as a `reference name`_ to the topic element. [#name-option]_ + Sidebar ======= @@ -400,6 +406,10 @@ The following options are recognized: Set a "classes" attribute value on the sidebar element. See the class_ directive below. +``name`` : text + Attach text as a `reference name`_ to the sidebar element. + [#name-option]_ + Line Block ========== @@ -438,12 +448,16 @@ example, here's a classic:: as soon as it comes. Love, Ewan. -The following option is recognized: +The following options are recognized: ``class`` : text Set a "classes" attribute value on the line_block element. See the class_ directive below. +``name`` : text + Attach text as a `reference name`_ to the line_block element. + [#name-option]_ + .. _parsed-literal: @@ -479,12 +493,16 @@ For example, all the element names in this content model are links:: (docinfo_, transition_?)?, `%structure.model;`_ ) -The following option is recognized: +The following options are recognized: ``class`` : text Set a "classes" attribute value on the literal_block element. See the class_ directive below. +``name`` : text + Attach text as a `reference name`_ to the literal_block element. + [#name-option]_ + Math ==== @@ -493,8 +511,8 @@ Math :Doctree Element: math-block :Directive Arguments: One, optional: prepended to content. :Directive Options: Possible. -:Directive Content: Interpreted as math block(s). - Content blocks separated by a blank line are put in +:Directive Content: Interpreted as math block(s). + Content blocks separated by a blank line are put in separate math-block doctree elements. The "math" directive inserts block(s) with mathematical content @@ -520,6 +538,10 @@ The following options are recognized: Set a "classes" attribute value on the block element. See the class_ directive. +``name`` : text + Attach text as a `reference name`_ to the math_block element. + [#name-option]_ + New in Docutils 0.8. .. _Short Math Guide: ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf @@ -547,12 +569,15 @@ The "rubric" directive inserts a "rubric" element into the document tree. A rubric is like an informal heading that doesn't correspond to the document's structure. -The following option is recognized: +The following options are recognized: ``class`` : text Set a "classes" attribute value on the rubric element. See the class_ directive below. +``name`` : text + Attach text as a `reference name`_ to the rubric element. [#name-option]_ + Epigraph ======== @@ -669,12 +694,16 @@ unity: * vertical spacing between physical elements may be reduced; * and so on. -The following option is recognized: +The following options are recognized: ``class`` : text Set a "classes" attribute value on the compound element. See the class_ directive below. +``name`` : text + Attach text as a `reference name`_ to the compound element. + [#name-option]_ + Container ========= @@ -706,6 +735,12 @@ The "container" directive is the equivalent of HTML's ``<div>`` element. It may be used to group a sequence of elements for user- or application-specific purposes. +The following option is recognized: + +``name`` : text + Attach text as a `reference name`_ to the container element. + [#name-option]_ + -------- Tables @@ -741,12 +776,15 @@ title with a table:: True False ===== ===== -The following option is recognized: +The following options are recognized: ``class`` : text Set a "classes" attribute value on the table element. See the class_ directive below. +``name`` : text + Attach text as a `reference name`_ to the table element. [#name-option]_ + .. _csv-table: @@ -804,6 +842,9 @@ The following options are recognized: Set a "classes" attribute value on the table element. See the class_ directive below. +``name`` : text + Attach text as a `reference name`_ to the table element. [#name-option]_ + ``widths`` : integer [, integer...] A comma- or space-separated list of relative column widths. The default is equal-width columns (100%/#columns). @@ -902,6 +943,9 @@ The following options are recognized: Set a "classes" attribute value on the table element. See the class_ directive below. +``name`` : text + Attach text as a `reference name`_ to the table element. [#name-option]_ + ``widths`` : integer [integer...] A comma- or space-separated list of relative column widths. The default is equal-width columns (100%/#columns). @@ -1105,12 +1149,16 @@ reference. For every explicit target (of the form, ``.. _target name: URL``) in the text, a footnote will be generated containing the visible URL as content. -The following option is recognized: +The following options are recognized: ``class`` : text Set a "classes" attribute value on all footnote_reference elements. See the class_ directive below. +``name`` : text + Attach text as a `reference name`_ to the first footnote_reference + element. [#name-option]_ + Footnotes ========= @@ -1794,6 +1842,28 @@ level-1 (info) system message showing the directive data, possibly followed by a literal block containing the rest of the directive block. +.. _reference name: restructuredtext.html#reference-names +.. _hyperlink target: restructuredtext.html#hyperlink-targets +.. _hyperlink references: restructuredtext.html#hyperlink-references + +.. [#name-option] The `name` option adds its value to the "names" + attribute of the doctree element generated by the directive. This + allows `hyperlink references`_ to the element. + + Specifying the `name` option of a directive like :: + + .. image:: bild.png + :name: my picture + + is a concise syntax alternative to preceding it with a `hyperlink + target`_ :: + + .. _my picture: + + .. image:: bild.png + + New in Docutils 0.8. + .. Local Variables: |