From c48f12bb79b0ae5d7fedbcd74094dbd8bd03ba41 Mon Sep 17 00:00:00 2001 From: sfcben Date: Sun, 23 Apr 2006 03:49:46 +0000 Subject: Added answer about list markup (don't indent, blank lines). Added answer about lists in HTML writer (indented, compaction). Converted docs/ links to relative to allow offline reading. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4510 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- FAQ.txt | 206 +++++++++++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 144 insertions(+), 62 deletions(-) (limited to 'FAQ.txt') diff --git a/FAQ.txt b/FAQ.txt index f9889c63c..1d3a1e553 100644 --- a/FAQ.txt +++ b/FAQ.txt @@ -13,15 +13,20 @@ .. sectnum:: -This is a work in progress. Please feel free to ask questions and/or -provide answers; send email to the `Docutils-users`_ mailing list. -Project members should feel free to edit the source text file -directly. +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 also 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 free to edit the +source text file directly. + +.. _master copy: http://docutils.sourceforge.net/FAQ.html .. _let us know: .. _Docutils-users: docs/user/mailing-lists.html#docutils-users + Docutils ======== @@ -50,13 +55,11 @@ For an overview of the Docutils project implementation, see `PEP Docutils is implemented in Python_. .. _Docutils: http://docutils.sourceforge.net/ -.. _PEPs (Python Enhancement Proposals): - http://www.python.org/peps/pep-0012.html -.. _can be used by client code: - http://docutils.sourceforge.net/docs/api/publisher.html -.. _front-end tools: http://docutils.sourceforge.net/docs/user/tools.html -.. _test suite: http://docutils.sourceforge.net/docs/dev/testing.html -.. _documentation: http://docutils.sourceforge.net/docs/ +.. _PEPs (Python Enhancement Proposals): http://www.python.org/peps/pep-0012.html +.. _can be used by client code: docs/api/publisher.html +.. _front-end tools: docs/user/tools.html +.. _test suite: docs/dev/testing.html +.. _documentation: docs/index.html .. _PEP 258: http://www.python.org/peps/pep-0258.html .. _Python: http://www.python.org/ @@ -89,8 +92,7 @@ Please note that the name is "Docutils", not "DocUtils" or "Doc-Utils" or any other variation. It is pronounced as in "DOCumentation UTILitieS", with emphasis on the first syllable. -.. _An Introduction to reStructuredText: - http://docutils.sourceforge.net/docs/ref/rst/introduction.html +.. _An Introduction to reStructuredText: docs/ref/rst/introduction.html __ http://mail.python.org/pipermail/doc-sig/1999-December/000878.html __ http://mail.python.org/pipermail/doc-sig/2000-November/001252.html __ http://mail.python.org/pipermail/doc-sig/2000-November/001239.html @@ -151,12 +153,10 @@ it in another window and compare them side by side. reference are a good place to start. The `reStructuredText Markup Specification`_ is a detailed technical specification. -.. _A ReStructuredText Primer: - http://docutils.sourceforge.net/docs/user/rst/quickstart.html -.. _Quick reStructuredText: - http://docutils.sourceforge.net/docs/user/rst/quickref.html +.. _A ReStructuredText Primer: docs/user/rst/quickstart.html +.. _Quick reStructuredText: docs/user/rst/quickref.html .. _reStructuredText Markup Specification: - http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html + docs/ref/rst/restructuredtext.html .. _reStructuredText: http://docutils.sourceforge.net/rst.html .. _StructuredText: http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/ @@ -203,7 +203,7 @@ Are there any reStructuredText editor extensions? See `Editor Support for reStructuredText`__. -__ http://docutils.sf.net/tools/editors/README.html +__ tools/editors/README.html How can I indicate the document title? Subtitle? @@ -308,15 +308,13 @@ the em dash is necessary because you cannot write "``foo|---|bar``"; thus you need to add spaces ("``foo |---| bar``") and advise the reStructuredText parser to trim the spaces. -.. _Standard Substitution Definition Sets: - http://docutils.sf.net/docs/ref/rst/substitutions.html -.. _unicode: - http://docutils.sf.net/docs/ref/rst/directives.html#unicode-character-codes +.. _Standard Substitution Definition Sets: docs/ref/rst/substitutions.html +.. _unicode: docs/ref/rst/directives.html#unicode-character-codes .. _are available: http://docutils.sourceforge.net/tmp/charents/ .. _tarball: http://docutils.sourceforge.net/tmp/charents.tgz .. _description and instructions: http://docutils.sourceforge.net/tmp/charents/README.html -.. _to-do list: http://docutils.sourceforge.net/docs/dev/todo.html +.. _to-do list: docs/dev/todo.html How can I generate backticks using a Scandinavian keyboard? @@ -437,23 +435,59 @@ order: Please `let us know`_ of any other reStructuredText Blogs. -Can lists be indented without generating block quotes? ------------------------------------------------------- +How should I mark up lists? +--------------------------- + +Bullet_ / enumerated_ list markup is very intuitive but there are 2 points +that must be noticed: + +.. _bullet: docs/ref/rst/restructuredtext.html#bullet-lists +.. _enumerated: docs/ref/rst/restructuredtext.html#enumerated-lists + +1. Lists should **not** be indented. This is good:: + + paragraph + + * list item 1 -Some people like to write lists with indentation, without intending a -block quote context, like this:: + * nested item 1.1 + * nested item 1.2 - paragraph + * list item 2 - * list item 1 - * list item 2 + while this is bad:: -There has been a lot of discussion about this, but there are some -issues that would need to be resolved before it could be implemented. -There is a summary of the issues and pointers to the discussions in -`the to-do list`__. + paragraph + + * list item 1 + + * nested item 1.1 + * nested item 1.2 + + * list item 2 + + The extra indentation is recognized as a block quote containing a list. + This is usually not what you mean and it causes the list in the output to + be indented too much. + +2. There **must** be blank lines around list items, except between items of + the same level where they are optional. The example above shows this. + +Note that formatting of the *output* is a quite independent matter, decided by +the writer and the stylesheet. For instance, lists *are* indentated in HTML +output by default. See `How are lists formatted in HTML?`_ for details. + + +Could lists be indented without generating block quotes? +-------------------------------------------------------- -__ http://docutils.sourceforge.net/docs/dev/todo.html#indented-lists +Some people like to write lists with indentation but don't intend a blockquote +context. There has been a lot of discussion about allowing this in +reStructuredText, but there are some issues that would need to be resolved +before it could be implemented. There is a summary of the issues and pointers +to the discussions in `the to-do list`__. + +__ docs/dev/todo.html#indented-lists Could the requirement for blank lines around lists be relaxed? @@ -480,7 +514,7 @@ no obvious winner. This issue requires a champion to solve the technical and aesthetic issues and implement a generic solution. Here's the `to-do list entry`__. -__ http://docutils.sourceforge.net/docs/dev/todo.html#math-markup +__ docs/dev/todo.html#math-markup There are several quick & dirty ways to include equations in documents. They all presently use LaTeX syntax or dialects of it. @@ -503,9 +537,8 @@ They all presently use LaTeX syntax or dialects of it. the binomial expansion of :raw-latex:`$(x+a)^3$` is - .. _raw directive: http://docutils.sourceforge.net/docs/ref/rst/ - directives.html#raw-data-pass-through - .. _raw role: http://docutils.sourceforge.net/docs/ref/rst/roles.html#raw + .. _raw directive: docs/ref/rst/directives.html#raw-data-pass-through + .. _raw role: docs/ref/rst/roles.html#raw * Jens Jørgen Mortensen has implemented a "latex-math" role and directive, available from `his sandbox`__. @@ -559,8 +592,8 @@ time, markup like this will become possible:: Here is some *emphasized text containing a `hyperlink`_ and ``inline literals``*. -__ http://docutils.sf.net/docs/dev/todo.html#nested-inline-markup -__ http://docutils.sf.net/docs/dev/rst/alternatives.html#nested-inline-markup +__ docs/dev/todo.html#nested-inline-markup +__ docs/dev/rst/alternatives.html#nested-inline-markup There are workarounds, but they are either convoluted or ugly or both. They are not recommended. @@ -577,9 +610,9 @@ They are not recommended. It is not possible for just a portion of the replacement text to be a hyperlink; it's the entire replacement text or nothing. - __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html#substitution-definitions - __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html#substitution-references - __ http://docutils.sf.net/docs/ref/rst/directives.html#replace + __ docs/ref/rst/restructuredtext.html#substitution-definitions + __ docs/ref/rst/restructuredtext.html#substitution-references + __ docs/ref/rst/directives.html#replace * The `"raw" directive`__ can be used to insert raw HTML into HTML output:: @@ -594,7 +627,7 @@ They are not recommended. Raw LaTeX is supported for LaTeX output, etc. - __ http://docutils.sf.net/docs/ref/rst/directives.html#raw + __ docs/ref/rst/directives.html#raw How to indicate a line break or a significant newline? @@ -619,7 +652,7 @@ recognized. For example:: | | Singing... -__ http://docutils.sf.net/docs/ref/rst/restructuredtext.html#line-blocks +__ docs/ref/rst/restructuredtext.html#line-blocks Here's a workaround for manually inserting explicit line breaks in HTML output:: @@ -885,24 +918,76 @@ can tweak the `initial_header_level`_ setting to your specific document, you might end up with bad HTML (e.g. H3 without H2). -.. _doctitle_xform: - http://docutils.sourceforge.net/docs/user/config.html#doctitle-xform -.. _initial_header_level: - http://docutils.sourceforge.net/docs/user/config.html#initial-header-level +.. _doctitle_xform: docs/user/config.html#doctitle-xform +.. _initial_header_level: docs/user/config.html#initial-header-level (Thanks to Mark McEahern for the question and much of the answer.) +How are lists formatted in HTML? +-------------------------------- + +If list formatting looks strange, first check that you understand `list +markup`__. + +__ `How should I mark up lists?`_ + +* The default stylesheet indents lists relative to their context. This + follows a long tradition in browsers (but isn't so established in print). + If you don't like it, change the stylesheet. + + This is different from how lists look in reStructuredText source. Indenting + lists in the source too would create a blockquote, resulting in too much + indentation in the browser. + +* A list item can contain multiple paragraphs. So in complex cases list items + are separated vertical space. By default this spacing is omitted in + "simple" lists. A list is simple if every item is a simple paragraph and/or + a "simple" nested list. For example: + + * text + + * simple + + * simple + * simple + + * simple + + text after a nested list + + * multiple + + paragraphs + + In this example the nested lists are simple (and should appear compacted) + but the outer list is not. + + If you want all lists to have equal spacing, disable the `compact_lists`_ + setting (``--no-compact-lists`` option). The precise spacing can be + controlled by the stylesheet. + +.. _compact_lists: docs/user/config.html#compact-lists + + Note again that this is not exactly WISYWIG: it partially resembles the + rules about blank lines between list items in reStructuredText - but + adding/removing optional blank lines will not affect spacing in the output! + It's a feature, not a bug: you write it as you like but the output is styled + consistently. + + Why do enumerated lists only use numbers (no letters or roman numerals)? ------------------------------------------------------------------------ -The rendering of enumerators (the numbers or letters acting as list -markers) is completely governed by the stylesheet, so either the -browser can't find the stylesheet (try using the "--embed-stylesheet" -option), or the browser can't understand it (try a recent Firefox, -Mozilla, Konqueror, Opera, Safari, or even MSIE). +The rendering of enumerators (the numbers or letters acting as list markers) +is completely governed by the stylesheet, so either the browser can't find the +stylesheet (try enabling the `embed_stylesheet`_ setting (``--embed-stylesheet`` +option)), or the browser can't understand it (try a recent Firefox, Mozilla, +Konqueror, Opera, Safari, or even MSIE). +.. _embed_stylesheet: docs/user/config.html#embed-stylesheet + There appear to be garbage characters in the HTML. What's up? -------------------------------------------------------------- @@ -954,8 +1039,7 @@ of the output. It must also match the document encoding. For UTF-8:: -.. _sectnum: - http://docutils.sourceforge.net/docs/ref/rst/directives.html#sectnum +.. _sectnum: docs/ref/rst/directives.html#sectnum How can I retrieve the body of the HTML document? @@ -967,10 +1051,8 @@ templating system.) You can use the `docutils.core.publish_parts()`_ function, which returns a dictionary containing an 'html_body_' entry. -.. _docutils.core.publish_parts(): - docs/api/publisher.html#publish-parts -.. _html_body: - docs/api/publisher.html#html-body +.. _docutils.core.publish_parts(): docs/api/publisher.html#publish-parts +.. _html_body: docs/api/publisher.html#html-body Why is the Docutils XHTML served as "Content-type: text/html"? -- cgit v1.2.1