diff options
| author | goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2003-12-20 18:48:23 +0000 |
|---|---|---|
| committer | goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2003-12-20 18:48:23 +0000 |
| commit | f74494c19b8a9de8a1bb4d6c2acce694b24d802b (patch) | |
| tree | c150d372545cc78be4a572902cb0a1eff1d9797f /docs | |
| parent | 19c14c68f9ae90da3cc2595df2eb74a9f56a9115 (diff) | |
| download | docutils-f74494c19b8a9de8a1bb4d6c2acce694b24d802b.tar.gz | |
Added support for quoted (and unindented) literal blocks. Driven in part by a bribe from Frank Siebenlist (thanks!).
git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1773 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/dev/todo.txt | 84 | ||||
| -rw-r--r-- | docs/ref/rst/restructuredtext.txt | 77 | ||||
| -rw-r--r-- | docs/user/rst/quickref.html | 26 |
3 files changed, 82 insertions, 105 deletions
diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 6caef7c52..3784fa46c 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -651,90 +651,6 @@ __ rst/alternatives.html#or-not-to-do Tony Ibbs spoke out against this idea (2002-06-14 Doc-SIG thread "docutils feedback"). -* Generalize the "literal block" construct to allow blocks with a - per-line quoting to avoid indentation? For example, in this email - reply quoting the original, the block quoted with "``>``" (and - prefaced by "``::``") would be treated as a literal block:: - - John Doe wrote:: - - >> Great idea! - > - > Why didn't I think of that? - - You just did! ;-) - - The literal block would have to be a continuous text block (the - first blank line ends it) where every line begins with the same - non-alphanumeric non-whitespace character. - - On 2003-06-17 Peter Simons requested a similar feature in the - "Literal Haskell Support" thread on docutils-develop. Regarding - this to-do item, he wrote - - I think that the '::' solution is not optimal. IMHO the leading - '>' should be enough for "docutils-hs2whatever" to know this is - a code block. In a perfect world, additional mark-up should not - be required. - - My reply was - - Who said it's a perfect world? ;-) - - The "::" reduces ambiguity, especially in the case of - single-line quoted blocks with certain quote characters. - - Do we limit the characters that can be used for quoting? If so, - what characters? Or would all non-alphanumeric non-whitespace 7-bit - ASCII characters be OK? This would include all of these:: - - ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ - - There are many situations where some kind of left border is used for - quoting. I've often seen vertical bars used:: - - | Quoted text - | here. - - I've seen legal documents that have something like this:: - - ) Quoted text - ) here. - - Or was it the other way around? :: - - ( Quoted text - ( here. - - A problem: if whitespace wasn't required, this could occur - accidentally in ordinary text:: - - (Quoted text here?) - - I think we'd have to require whitespace (perhaps allowing for - multiple quote characters before the whitespace, which would allow - for email). - - What about asterisks? :: - - * Quoted text - * here. - - Big problem! That's a bullet list. So we can't allow "*", "-", or - "+", unless we disambiguate with "::". - - Other conceivable quote characters include: # $ % : ; = [ ] { } - - If we required multiple lines, it would be easier to be sure the - text is unambiguous. I don't think we can require that though. - - Another issue: do the quoting characters stay in the literal block - (i.e., do they show up in the processed document)? - - Relax the "::" requirement somehow? Runtime setting & directive to - specify literal line prefix? Extend to doctest-like blocks (marker - on the first line sufficient)? - * Should the "doctest" element go away, and the construct simply be a front-end to generic literal blocks? diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index ff732af1b..b63979f70 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -124,8 +124,9 @@ Here are examples of `body elements`_: - `Literal blocks`_:: - Literal blocks are indented, and indicated with a double-colon - ("::") at the end of the preceding paragraph (right here -->):: + Literal blocks are either indented or line-prefix-quoted blocks, + and indicated with a double-colon ("::") at the end of the + preceding paragraph (right here -->):: if literal_block: text = 'is left as-is' @@ -1036,12 +1037,13 @@ Literal Blocks Doctree element: literal_block. -A paragraph consisting of two colons ("::") signifies that all -following **indented** text blocks comprise a literal block. No -markup processing is done within a literal block. It is left as-is, -and is typically rendered in a monospaced typeface:: +A paragraph consisting of two colons ("::") signifies that the +following text block(s) comprise a literal block. The literal block +must either be indented or quoted (see below). No markup processing +is done within a literal block. It is left as-is, and is typically +rendered in a monospaced typeface:: - This is a typical paragraph. A literal block follows. + This is a typical paragraph. An indented literal block follows. :: @@ -1087,11 +1089,21 @@ colons after "Paragraph"): Literal block -The minimum leading whitespace will be removed from each line of the -literal block. Other than that, all whitespace (including line -breaks) is preserved. Blank lines are required before and after a -literal block, but these blank lines are not included as part of the -literal block. +All whitespace (including line breaks, but excluding minimum +indentation for indented literal blocks) is preserved. Blank lines +are required before and after a literal block, but these blank lines +are not included as part of the literal block. + + +Indented Literal Blocks +``````````````````````` + +Indented literal blocks are indicated by indentation relative to the +surrounding text (leading whitespace on each line). The minimum +indentation will be removed from each line of an indented literal +block. The literal block need not be contiguous; blank lines are +allowed between sections of indented text. The literal block ends +with the end of the indentation. Syntax diagram:: @@ -1100,10 +1112,49 @@ Syntax diagram:: | (ends with "::") | +------------------------------+ +---------------------------+ - | literal block | + | indented literal block | +---------------------------+ +Quoted Literal Blocks +````````````````````` + +Quoted literal blocks are unindented contiguous blocks of text where +each line begins with the same non-alphanumeric printable 7-bit ASCII +character [#]_. A blank line ends a quoted literal block. The +quoting characters are preserved in the processed document. + +.. [#] + The following are all valid quoting characters:: + + ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ + + Note that these are the same characters as are valid for title + adornment of sections_. + +Possible uses include literate programming in Haskell and email +quoting:: + + John Doe wrote:: + + >> Great idea! + > + > Why didn't I think of that? + + You just did! ;-) + +Syntax diagram:: + + +------------------------------+ + | paragraph | + | (ends with "::") | + +------------------------------+ + +------------------------------+ + | ">" per-line-quoted | + | ">" contiguous literal block | + +------------------------------+ + + Block Quotes ------------ diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index b60cbf1b0..f89d89352 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -18,7 +18,7 @@ <p align="right"><em><a href="http://docutils.sourceforge.net/docs/rst/quickref.html" >http://docutils.sourceforge.net/docs/rst/quickref.html</a></em> <br align="right"><em>Being a cheat-sheet for reStructuredText</em> - <br align="right"><em>Updated 2003-06-10</em> + <br align="right"><em>Updated 2003-12-20</em> <blockquote> <p>Copyright: This document has been placed in the public domain. @@ -538,7 +538,7 @@ <td> <samp>A paragraph containing only two colons</samp> <br><samp>indicates that the following indented</samp> -<br><samp>text is a literal block.</samp> +<br><samp>or quoted text is a literal block.</samp> <br> <br><samp>::</samp> <br> @@ -559,17 +559,22 @@ <br> <br><samp>Literal blocks end when text returns to</samp> <br><samp>the preceding paragraph's indentation.</samp> -<br><samp>This means that something like::</samp> +<br><samp>This means that something like this</samp> +<br><samp>is possible::</samp> <br> <br><samp> We start here</samp> <br><samp> and continue here</samp> <br><samp> and end here.</samp> <br> -<br><samp>is possible.</samp> +<br><samp>Per-line quoting can also be used on</samp> +<br><samp>unindented literal blocks:</samp> +<br> +<br><samp>> Useful for quotes from email and</samp> +<br><samp>> for Haskell literate programming.<samp> <td> <p>A paragraph containing only two colons -indicates that the following indented +indicates that the following indented or quoted text is a literal block. <pre> @@ -591,14 +596,19 @@ colon if preceded by text, like this: <p>Literal blocks end when text returns to the preceding paragraph's indentation. -This means that something like: +This means that something like this is possible: <pre> We start here and continue here and end here.</pre> - <p>is possible. + <p>Per-line quoting can also be used on +unindented literal blocks: + + <pre> + > Useful for quotes from email and + > for Haskell literate programming.</pre> </table> <h2><a href="#contents" name="block-quotes" class="backref" @@ -1236,7 +1246,7 @@ dispose of medical waste.</samp> <a href="http://www.tibsnjoan.co.uk/">Tibs</a> (<a href="mailto:tibs@tibsnjoan.co.uk"><tt>tibs@tibsnjoan.co.uk</tt></a>) and David Goodger - (<a href="mailto:goodger@users.sourceforge.net">goodger@users.sourceforge.net</a>) + (<a href="mailto:goodger@python.org">goodger@python.org</a>) </address> <!-- Created: Fri Aug 03 09:11:57 GMT Daylight Time 2001 --> </body> |