Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[9276] trunk/docutils
|
From: <mi...@us...> - 2022-11-25 23:03:44
|
Revision: 9276
http://sourceforge.net/p/docutils/code/9276
Author: milde
Date: 2022-11-25 23:03:41 +0000 (Fri, 25 Nov 2022)
Log Message:
-----------
Update FAQ, add TODO-list example.
Modified Paths:
--------------
trunk/docutils/FAQ.txt
Added Paths:
-----------
trunk/docutils/docs/user/todo-lists.txt
Modified: trunk/docutils/FAQ.txt
===================================================================
--- trunk/docutils/FAQ.txt 2022-11-25 23:03:32 UTC (rev 9275)
+++ trunk/docutils/FAQ.txt 2022-11-25 23:03:41 UTC (rev 9276)
@@ -1,10 +1,6 @@
-.. -*- coding: utf-8 -*-
-
-
.. NOTE TO MAINTAINERS: Please add new questions to the end of their
sections, so section/question numbers remain stable.
-
===========================================
Docutils FAQ (Frequently Asked Questions)
===========================================
@@ -19,8 +15,8 @@
This is a work in progress. If you are reading a local copy, the
-`master copy`_ might be newer. This document uses are relative links;
-if they don't work, please use the `master copy`_.
+`master copy`_ might be newer. This document uses relative links;
+if they don't work, please use the master copy.
Please feel free to ask questions and/or provide answers; send email
to the `Docutils-users`_ mailing list. Project members should feel
@@ -215,13 +211,13 @@
What's the standard filename extension for a reStructuredText file?
-------------------------------------------------------------------
-It's ".txt". Some people would like to use ".rest" or ".rst" or
-".restx", but why bother? ReStructuredText source files are meant to
-be readable as plaintext, and most operating systems already associate
-".txt" with text files. Using a specialized filename extension would
-require that users alter their OS settings, which is something that
-many users will not be willing or able to do.
+It's ".txt". ReStructuredText source files are meant to be readable as
+plaintext, and most operating systems already associate ".txt" with text
+files.
+That said, we see an increasing number of projects settling on
+the extension ".rst".
+
Also see `What's the official MIME type for reStructuredText data?`_
@@ -275,10 +271,10 @@
For example, say you want an em-dash (XML character entity —,
Unicode character U+2014) in your document: use a real em-dash.
-Insert concrete characters (e.g. type a *real* em-dash) into your
+Insert literal characters (e.g. type a *real* em-dash) into your
input file, using whatever encoding suits your application, and tell
Docutils the input encoding. Docutils uses Unicode internally, so the
-em-dash character is a real em-dash internally.
+em-dash character is U+2014 internally.
Emacs users should refer to the `Emacs Support for reStructuredText`__
document. Tips for other editors are welcome.
@@ -286,7 +282,8 @@
__ tools/editors/emacs/README.html
ReStructuredText has no character entity subsystem; it doesn't know
-anything about XML charents. To Docutils, "—" in input text is
+anything about XML character entities.
+To Docutils, "—" in input text is
7 discrete characters; no interpretation happens. When writing HTML,
the "&" is converted to "&", so in the raw output you'd see
"&mdash;". There's no difference in interpretation for text
@@ -294,27 +291,20 @@
character entity interpretation in either case.
If you can't use a Unicode-compatible encoding and must rely on 7-bit
-ASCII, there is a workaround. New in Docutils 0.3.10 is a set of
-`Standard Substitution Definition Sets`_, which provide equivalents of
-XML & HTML character entity sets as substitution definitions. For
-example, the Japanese yen currency symbol can be used as follows::
+ASCII, there is a workaround:
+`Standard Substitution Definition Sets`_ provide equivalents of
+XML & HTML character entity sets as substitution definitions. [#]_
+For example, the Japanese yen currency symbol can be used as follows::
.. include:: <xhtml1-lat1.txt>
|yen| 600 for a complete meal? That's cheap!
-Thanks to David Priest for the original idea.
+.. [#] Thanks to David Priest for the original idea.
-If you insist on using XML-style charents, you'll have to implement a
-pre-processing system to convert to UTF-8 or something. That
-introduces complications though; you can no longer *write* about
-charents naturally; instead of writing "—" you'd have to write
-"&mdash;".
+You can create custom `substitution definitions`_ in your document
+using the "unicode_" directive, e.g.::
-For the common case of long dashes, you might also want to insert the
-following substitution definitions into your document (both of them are
-using the "unicode_" directive)::
-
.. |--| unicode:: U+2013 .. en dash
.. |---| unicode:: U+2014 .. em dash, trimming surrounding whitespace
:trim:
@@ -331,12 +321,9 @@
reStructuredText parser to trim the spaces.
.. _Standard Substitution Definition Sets: docs/ref/rst/definitions.html
+.. _substitution definitions: docs/ref/rst/restructuredtext.html
+ #substitution-definitions
.. _unicode: docs/ref/rst/directives.html#unicode-character-codes
-.. _are available: https://docutils.sourceforge.io/tmp/charents/
-.. _tarball: https://docutils.sourceforge.io/tmp/charents.tgz
-.. _description and instructions:
- https://docutils.sourceforge.io/tmp/charents/README.html
-.. _to-do list: docs/dev/todo.html
How can I generate backticks using a Scandinavian keyboard?
@@ -541,8 +528,9 @@
How can I include mathematical equations in documents?
------------------------------------------------------
-Use the `math directive`_ and `math role`_, available since Docutils 0.8.
+Use `LaTeX math syntax`_ in a `math directive`_ or `math role`_.
+.. _LaTeX math syntax: docs/ref/rst/mathematics.html
.. _math directive: docs/ref/rst/directives.html#math
.. _math role: docs/ref/rst/roles.html#math
@@ -877,6 +865,46 @@
.. [#] The "x-" prefix means it's an unregistered MIME type.
+How can I mark up a TODO list?
+------------------------------
+
+You may use a field list with class argument and some CSS styling.
+For an example see `Docutils TODO lists`_ and its source todo-lists.txt_.
+
+.. _Docutils TODO lists: docs/user/todo-lists.html
+.. _todo-lists.txt: docs/user/todo-lists.txt
+
+
+How can I specify an image grid?
+--------------------------------
+
+In order to arrange images (or other content) in a grid,
+a borderless `list table`_ can be used. For example::
+
+ .. list-table::
+ :class: borderless
+
+ * - .. image:: rst/images/title-scaling.svg
+ - .. image:: rst/images/biohazard.svg
+ * - .. image:: rst/images/biohazard.svg
+ - .. image:: rst/images/biohazard.svg
+
+Use figures, if you want also captions::
+
+ .. list-table::
+ :class: borderless
+
+ * - .. figure:: rst/images/title-scaling.svg
+
+ Figure 1/1
+
+ - .. figure:: rst/images/biohazard.svg
+
+ Figure 1/2
+
+.. _list table: docs/ref/rst/directives.html#list-table
+
+
HTML Writer
===========
@@ -883,16 +911,20 @@
What is the status of the HTML Writer?
--------------------------------------
-The default HTML Writer module, ``docutils/writers/html4css1.py``, is
+The default HTML Writer module, `html4css1`_, is
a proof-of-concept reference implementation. While it is a complete
implementation, some aspects of the HTML it produces may be outdated or
incompatible with older browsers or specialized applications (such as
web templating).
+The `html5 writer`_ generates semantic HTML output compatible with HTML5.
For the full selection see `Docutils HTML writers`_
+.. _html4css1: docs/user/html.html#html4css1
+.. _HTML5 writer: docs/user/html.html#html5
.. _Docutils HTML writers: docs/user/html.html
+
What browsers are supported?
----------------------------
@@ -907,113 +939,119 @@
Unexpected results from tools/rst2html.py: H1, H1 instead of H1, H2. Why?
--------------------------------------------------------------------------
-Here's the question in full:
+This only regards output from the `html4css1`_ writer.
+The `html5 writer`_ uses H1, H2, ...
- I have this text::
+.. class:: details
- Heading 1
- =========
+details
+ Here's the question in full:
- All my life, I wanted to be H1.
+ I have this text::
- Heading 1.1
- -----------
+ Heading 1
+ =========
- But along came H1, and so shouldn't I be H2?
- No! I'm H1!
+ All my life, I wanted to be H1.
- Heading 1.1.1
- *************
+ Heading 1.1
+ -----------
- Yeah, imagine me, I'm stuck at H3! No?!?
+ But along came H1, and so shouldn't I be H2?
+ No! I'm H1!
- When I run it through tools/rst2html.py, I get unexpected results
- (below). I was expecting H1, H2, then H3; instead, I get H1, H1,
- H2::
+ Heading 1.1.1
+ *************
- ...
- <html lang="en">
- <head>
- ...
- <title>Heading 1</title>
- </head>
- <body>
- <div class="document" id="heading-1">
- <h1 class="title">Heading 1</h1> <-- first H1
- <p>All my life, I wanted to be H1.</p>
- <div class="section" id="heading-1-1">
- <h1><a name="heading-1-1">Heading 1.1</a></h1> <-- H1
- <p>But along came H1, and so now I must be H2.</p>
- <div class="section" id="heading-1-1-1">
- <h2><a name="heading-1-1-1">Heading 1.1.1</a></h2>
- <p>Yeah, imagine me, I'm stuck at H3!</p>
- ...
+ Yeah, imagine me, I'm stuck at H3! No?!?
- What gives?
+ When I run it through tools/rst2html.py, I get unexpected results
+ (below). I was expecting H1, H2, then H3; instead, I get H1, H1,
+ H2::
-Check the "class" attribute on the H1 tags, and you will see a
-difference. The first H1 is actually ``<h1 class="title">``; this is
-the document title, and the default stylesheet renders it centered.
-There can also be an ``<h2 class="subtitle">`` for the document
-subtitle.
+ ...
+ <html lang="en">
+ <head>
+ ...
+ <title>Heading 1</title>
+ </head>
+ <body>
+ <div class="document" id="heading-1">
+ <h1 class="title">Heading 1</h1> <-- first H1
+ <p>All my life, I wanted to be H1.</p>
+ <div class="section" id="heading-1-1">
+ <h1><a name="heading-1-1">Heading 1.1</a></h1> <-- H1
+ <p>But along came H1, and so now I must be H2.</p>
+ <div class="section" id="heading-1-1-1">
+ <h2><a name="heading-1-1-1">Heading 1.1.1</a></h2>
+ <p>Yeah, imagine me, I'm stuck at H3!</p>
+ ...
-If there's only one highest-level section title at the beginning of a
-document, it is treated specially, as the document title. (Similarly, a
-lone second-highest-level section title may become the document
-subtitle.) See `How can I indicate the document title? Subtitle?`_ for
-details. Rather than use a plain H1 for the document title, we use ``<h1
-class="title">`` so that we can use H1 again within the document. Why
-do we do this? HTML only has H1-H6, so by making H1 do double duty, we
-effectively reserve these tags to provide 6 levels of heading beyond the
-single document title.
+ What gives?
-With "html4css1", HTML is being used for dumb formatting for nothing
-but final display. A stylesheet *is required*, and one is provided;
-see `Docutils HTML writers`_. Of course, you're
-welcome to roll your own. The default stylesheet provides rules to
-format ``<h1 class="title">`` and ``<h2 class="subtitle">``
-differently from ordinary ``<h1>`` and ``<h2>``::
+ Check the "class" attribute on the H1 tags, and you will see a
+ difference. The first H1 is actually ``<h1 class="title">``; this is
+ the document title, and the default stylesheet renders it centered.
+ There can also be an ``<h2 class="subtitle">`` for the document
+ subtitle.
- h1.title {
- text-align: center }
+ If there's only one highest-level section title at the beginning of a
+ document, it is treated specially, as the document title. (Similarly, a
+ lone second-highest-level section title may become the document
+ subtitle.) See `How can I indicate the document title? Subtitle?`_ for
+ details. Rather than use a plain H1 for the document title, we use ``<h1
+ class="title">`` so that we can use H1 again within the document. Why
+ do we do this? HTML only has H1-H6, so by making H1 do double duty, we
+ effectively reserve these tags to provide 6 levels of heading beyond the
+ single document title.
- h2.subtitle {
- text-align: center }
+ With "html4css1", HTML is being used for dumb formatting for nothing
+ but final display. A stylesheet *is required*, and one is provided;
+ see `Docutils HTML writers`_. Of course, you're
+ welcome to roll your own. The default stylesheet provides rules to
+ format ``<h1 class="title">`` and ``<h2 class="subtitle">``
+ differently from ordinary ``<h1>`` and ``<h2>``::
-If you don't want the top section heading to be interpreted as a
-title at all, disable the `doctitle_xform`_ setting
-(``--no-doc-title`` option). This will interpret your document
-differently from the standard settings, which might not be a good
-idea. If you don't like the reuse of the H1 in the HTML output, you
-can tweak the `initial_header_level`_ setting
-(``--initial-header-level`` option) -- but unless you match its value
-to your specific document, you might end up with bad HTML (e.g. H3
-without H2).
+ h1.title {
+ text-align: center }
-.. _doctitle_xform: docs/user/config.html#doctitle-xform
-.. _initial_header_level: docs/user/config.html#initial-header-level
+ h2.subtitle {
+ text-align: center }
-(Thanks to Mark McEahern for the question and much of the answer.)
+ If you don't want the top section heading to be interpreted as a
+ title at all, disable the `doctitle_xform`_ setting
+ (``--no-doc-title`` option). This will interpret your document
+ differently from the standard settings, which might not be a good
+ idea. If you don't like the reuse of the H1 in the HTML output, you
+ can tweak the `initial_header_level`_ setting
+ (``--initial-header-level`` option) -- but unless you match its value
+ to your specific document, you might end up with bad HTML (e.g. H3
+ without H2).
-.. note:: For the html5 writer, `initial_header_level`_ defaults to
- ``2`` because this is what the `HTML5 standard`__ expects as
- start value for headings nested in <section> elements.
+ .. _doctitle_xform: docs/user/config.html#doctitle-xform
+ .. _initial_header_level: docs/user/config.html#initial-header-level
- .. Sectioning content elements are always considered subsections of
- their nearest ancestor *sectioning root* [#]_ or their nearest
- ancestor element of *sectioning content* [#]_, whichever is nearest,
- [...]
+ (Thanks to Mark McEahern for the question and much of the answer.)
- .. [#] <blockquote>, <body>, <details>, <dialog>, <fieldset>,
- <figure>, <td>
- .. [#] <article>, <aside>, <nav>, <section>
+ .. note:: For the `html5 writer`_, `initial_header_level`_ defaults to
+ ``2`` because this is what the `HTML5 standard`__ expects as
+ start value for headings nested in <section> elements.
- I.e., a top-level <section> is a subsection of <body>.
+ .. Sectioning content elements are always considered subsections of
+ their nearest ancestor *sectioning root* [#]_ or their nearest
+ ancestor element of *sectioning content* [#]_, whichever is nearest,
+ [...]
- __ https://www.w3.org/TR/html53/sections.html#headings-and-sections
+ .. [#] <blockquote>, <body>, <details>, <dialog>, <fieldset>,
+ <figure>, <td>
+ .. [#] <article>, <aside>, <nav>, <section>
+ I.e., a top-level <section> is a subsection of <body>.
+ __ https://www.w3.org/TR/html53/sections.html#headings-and-sections
+
+
How are lists formatted in HTML?
--------------------------------
@@ -1190,27 +1228,30 @@
Version 2.0 of Ed Loper's `Epydoc <http://epydoc.sourceforge.net/>`_
supports reStructuredText-format docstrings for HTML output. Docutils
-0.3 or newer is required. Development of a Docutils-specific
-auto-documentation tool will continue. Epydoc works by importing
-Python modules to be documented, whereas the Docutils-specific tool,
-described above, will parse modules without importing them (as with
-`HappyDoc <http://happydoc.sourceforge.net/>`_, which doesn't support
-reStructuredText).
+0.3 or newer is required.
-The advantages of parsing over importing are security and flexibility;
-the disadvantage is complexity/difficulty.
+Development of a Docutils-specific auto-documentation tool is suspended.
-* Security: untrusted code that shouldn't be executed can be parsed;
- importing a module executes its top-level code.
-* Flexibility: comments and unofficial docstrings (those not supported
- by Python syntax) can only be processed by parsing.
-* Complexity/difficulty: it's a lot harder to parse and analyze a
- module than it is to ``import`` and analyze one.
+.. Epydoc works by importing
+ Python modules to be documented, whereas the Docutils-specific tool,
+ described above, will parse modules without importing them (as with
+ `HappyDoc <http://happydoc.sourceforge.net/>`_, which doesn't support
+ reStructuredText).
-For more details, please see "Docstring Extraction Rules"
-in :PEP:`258`, item 3 ("How").
+ The advantages of parsing over importing are security and flexibility;
+ the disadvantage is complexity/difficulty.
+ * Security: untrusted code that shouldn't be executed can be parsed;
+ importing a module executes its top-level code.
+ * Flexibility: comments and unofficial docstrings (those not supported
+ by Python syntax) can only be processed by parsing.
+ * Complexity/difficulty: it's a lot harder to parse and analyze a
+ module than it is to ``import`` and analyze one.
+ For more details, please see "Docstring Extraction Rules"
+ in :PEP:`258`, item 3 ("How").
+
+
Miscellaneous
=============
Added: trunk/docutils/docs/user/todo-lists.txt
===================================================================
--- trunk/docutils/docs/user/todo-lists.txt (rev 0)
+++ trunk/docutils/docs/user/todo-lists.txt 2022-11-25 23:03:41 UTC (rev 9276)
@@ -0,0 +1,154 @@
+.. include:: ../header.txt
+
+===================
+Docutils TODO lists
+===================
+
+TODO lists allow you to create a list of items with checkboxes.
+In `extended Markdown`_, they are called `task lists`.
+
+Checkbox variants
+=================
+
+[x] ASCII-art checkbox.
+
+[ ] ASCII space character and NBSP are smaller than the x.
+
+[ ] The "figure space" has the correct width but is not easy to type.
+
+You may define substitutions for ballot box and checked ballot box or
+other suitable Unicode characters:
+
+.. |-| unicode:: U+2610
+.. |x| unicode:: U+2611
+.. |y| unicode:: U+1F5F9
+
+|-| U+2610 BALLOT BOX
+
+|x| U+2611 BALLOT BOX WITH CHECK
+
+|y| U+1F5F9 BALLOT BOX WITH BOLD CHECK
+
+List Markup
+===========
+
+Paragraphs
+----------
+
+|x| Simple *paragraphs* are easy for small lists with short values
+
+|-| but not well suited for complex TODO items.
+
+Line Blocks
+-----------
+
+| |x| Line blocks are rendered as "unstyled" lists.
+| |y| They don't need additional styling.
+| |-| However, you cannot nest block elements.
+
+
+Description Lists
+-----------------
+
+.. class:: description
+
+|x|
+ A *description list* works out of the box in HTML5 and XeTeX.
+
+|-|
+ It looks suboptimal in the rST source (definition list with class
+ value "description").
+
+[x]
+ Lists may use ASCII-art or substitutions.
+
+[ ]
+ All list markup variants require special styling based on a
+ preceding class__ directive.
+
+__ https://docutils.sourceforge.io/docs/ref/rst/directives.html#class
+
+Bullet Lists
+------------
+
+.. class:: todo
+
+- |x| bullet lists (similar to the Markdown_ for `task
+ lists`) can be styled accordingly.
+- |-| They don't look good in the rST source.
+- [x] Lists may use ASCII-art or substitutions.
+- [ ] The "figure space" has the correct width.
+
+- |x| Another idea: use bullet lists with ``+`` and ``-`` markers.
+
+ + Clean and simple markup in the source.
+
+ - A new marker character starts a new list :-(
+
+ - Requires change to the writer: Pass the "bullet" attribute to
+ the output document (use `HTML5 "data-" attriibutes`__?).
+
+__ https://html.spec.whatwg.org/#embedding-custom-non-visible-data-with-the-data-*-attributes
+
+Field Lists
+-----------
+
+.. class:: todo
+
+:|x|: Compile this example with ``rst2html5.py``,
+:|y|: compare markup variants,
+:|-|: select the best.
+
+.. class:: todo monospace
+
+:[x]: ASCII-art checkbox.
+:[ ]: The "figure space" has the correct width.
+:[ ]: CSS styling can switch to monospace fonts for the ASCII-art boxes,
+ so an ASCII space character can be used.
+
+.. class:: todo monospace brackets
+
+:x: ASCII-art checkbox - brackets added by CSS.
+: : Simple rST source, easy typing.
+
+.. class:: todo monospace framed
+
+:x: checkbox border added by CSS.
+: : Simple rST source, easy typing.
+
+I recommend a field list with class argument and some CSS styling.
+
+
+.. _Markdown: https://www.markdownguide.org
+.. _extended Markdown: https://www.markdownguide.org/extended-syntax/
+
+
+.. ! The follwing CSS rules are included here as raw HTML to keep the
+ example compact. They compromise the HTML validity, as styling is not
+ allowed in the document body.
+ For production use, place CSS styling rules in a custom style sheet.
+
+.. raw:: html
+
+ <style type="text/css"><!--
+ ul.todo {list-style-type: none;
+ padding-left: 0;}
+ ul.todo > li > p {padding-left: 1.2em;
+ text-indent: -1.2em;}
+
+ dl.todo > dt > .colon {display: none}
+ dl.todo > dd {margin-left: 2.5em;}
+
+ dl.monospace > dt {font-family: monospace;}
+
+ dl.brackets > dt:before {content: '[';}
+ dl.brackets > dt:after {content: ']';}
+
+ dl.framed > dt {border: solid;
+ border-width: thin;
+ padding: 0 0.2em;
+ margin-top: 0.2em;
+ line-height: 0.9;
+ }
+
+ --></style>
Property changes on: trunk/docutils/docs/user/todo-lists.txt
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: svn:keywords
## -0,0 +1 ##
+Author Date Id Revision
\ No newline at end of property
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
