diff options
| -rw-r--r-- | Git Wiki | 21 | ||||
| -rw-r--r-- | reStructured Text | 405 | ||||
| -rw-r--r-- | restructured text cheatsheet | 127 |
3 files changed, 156 insertions, 397 deletions
@@ -12,16 +12,29 @@ __ http://djangoproject.com/ __ http://git.cx __ /k/restructuredtext/ +Features +~~~~~~~~ +Full File History + Because all files are stored in a repository all changes are tracked + and can be reverted. It could be interesting to watch the evolution + of a larger or controvertial item. +PDF Output + Using a combination of `LaTeX`__ and rubber [#]_, portable document + files can be generated on the fly (with figures etc included) +LaTeX Math in (X)HTML + When rendering to (X)HTML LaTeX math sections are rendered to png + and inserted as images + +__ /k/latex/ +.. [#] A python wrapper around LaTeX and pdflatex which does a great job + handling bibliographies, weird image formats, etc. + Development ~~~~~~~~~~~ Git Wiki is under heavy development. The source tree can be browsed at `/code/bn-project </code/bn-project/>`__. To Do ----- -* implement equations feature to handle both latex and xhtml display of - latex-style math -* implement figures (have to handle image urls/items) -* implement latex and pdf generation * implement per-section commentary * possibly implement aafigure ascii->svg plugin for docutils * possibly implement auto linking for CamelCase text (probably not) diff --git a/reStructured Text b/reStructured Text index 1b26603..a8966fa 100644 --- a/reStructured Text +++ b/reStructured Text @@ -1,397 +1,16 @@ -========================= -A ReStructuredText Primer -========================= +================ +ReStructuredText +================ ---------------------------------- -(ed: taken from docutils package) ---------------------------------- +reStructured text is a markup language commonly used in wikis (including +`Git Wiki`_) and software documentation. It strives to be readable in +its raw text +form, extensible, easy to write, and flexible in output. Writers +exist to output HTML, XHTML, LaTeX, and several other formats -:Author: Richard Jones -:Version: $Revision: 4350 $ -:Copyright: This document has been placed in the public domain. +reStructured text is closely tied to the python community and is used +in the formating of PEPs. The most popular implementation is `docutils`_. -.. contents:: - - -The text below contains links that look like "(quickref__)". These -are relative links that point to the `Quick reStructuredText`_ user -reference. If these links don't work, please refer to the `master -quick reference`_ document. - -__ -.. _Quick reStructuredText: quickref.html -.. _master quick reference: - http://docutils.sourceforge.net/docs/user/rst/quickref.html - - -Structure ---------- - -From the outset, let me say that "Structured Text" is probably a bit -of a misnomer. It's more like "Relaxed Text" that uses certain -consistent patterns. These patterns are interpreted by a HTML -converter to produce "Very Structured Text" that can be used by a web -browser. - -The most basic pattern recognised is a **paragraph** (quickref__). -That's a chunk of text that is separated by blank lines (one is -enough). Paragraphs must have the same indentation -- that is, line -up at their left edge. Paragraphs that start indented will result in -indented quote paragraphs. For example:: - - This is a paragraph. It's quite - short. - - This paragraph will result in an indented block of - text, typically used for quoting other text. - - This is another one. - -Results in: - - This is a paragraph. It's quite - short. - - This paragraph will result in an indented block of - text, typically used for quoting other text. - - This is another one. - -__ quickref.html#paragraphs - - -Text styles ------------ - -(quickref__) - -__ quickref.html#inline-markup - -Inside paragraphs and other bodies of text, you may additionally mark -text for *italics* with "``*italics*``" or **bold** with -"``**bold**``". - -If you want something to appear as a fixed-space literal, use -"````double back-quotes````". Note that no further fiddling is done -inside the double back-quotes -- so asterisks "``*``" etc. are left -alone. - -If you find that you want to use one of the "special" characters in -text, it will generally be OK -- reStructuredText is pretty smart. -For example, this * asterisk is handled just fine. If you actually -want text \*surrounded by asterisks* to **not** be italicised, then -you need to indicate that the asterisk is not special. You do this by -placing a backslash just before it, like so "``\*``" (quickref__), or -by enclosing it in double back-quotes (inline literals), like this:: - - ``\*`` - -__ quickref.html#escaping - - -Lists ------ - -Lists of items come in three main flavours: **enumerated**, -**bulleted** and **definitions**. In all list cases, you may have as -many paragraphs, sublists, etc. as you want, as long as the left-hand -side of the paragraph or whatever aligns with the first line of text -in the list item. - -Lists must always start a new paragraph -- that is, they must appear -after a blank line. - -**enumerated** lists (numbers, letters or roman numerals; quickref__) - __ quickref.html#enumerated-lists - - Start a line off with a number or letter followed by a period ".", - right bracket ")" or surrounded by brackets "( )" -- whatever you're - comfortable with. All of the following forms are recognised:: - - 1. numbers - - A. upper-case letters - and it goes over many lines - - with two paragraphs and all! - - a. lower-case letters - - 3. with a sub-list starting at a different number - 4. make sure the numbers are in the correct sequence though! - - I. upper-case roman numerals - - i. lower-case roman numerals - - (1) numbers again - - 1) and again - - Results in (note: the different enumerated list styles are not - always supported by every web browser, so you may not get the full - effect here): - - 1. numbers - - A. upper-case letters - and it goes over many lines - - with two paragraphs and all! - - a. lower-case letters - - 3. with a sub-list starting at a different number - 4. make sure the numbers are in the correct sequence though! - - I. upper-case roman numerals - - i. lower-case roman numerals - - (1) numbers again - - 1) and again - -**bulleted** lists (quickref__) - __ quickref.html#bullet-lists - - Just like enumerated lists, start the line off with a bullet point - character - either "-", "+" or "*":: - - * a bullet point using "*" - - - a sub-list using "-" - - + yet another sub-list - - - another item - - Results in: - - * a bullet point using "*" - - - a sub-list using "-" - - + yet another sub-list - - - another item - -**definition** lists (quickref__) - __ quickref.html#definition-lists - - Unlike the other two, the definition lists consist of a term, and - the definition of that term. The format of a definition list is:: - - what - Definition lists associate a term with a definition. - - *how* - The term is a one-line phrase, and the definition is one or more - paragraphs or body elements, indented relative to the term. - Blank lines are not allowed between term and definition. - - Results in: - - what - Definition lists associate a term with a definition. - - *how* - The term is a one-line phrase, and the definition is one or more - paragraphs or body elements, indented relative to the term. - Blank lines are not allowed between term and definition. - - -Preformatting (code samples) ----------------------------- -(quickref__) - -__ quickref.html#literal-blocks - -To just include a chunk of preformatted, never-to-be-fiddled-with -text, finish the prior paragraph with "``::``". The preformatted -block is finished when the text falls back to the same indentation -level as a paragraph prior to the preformatted block. For example:: - - An example:: - - Whitespace, newlines, blank lines, and all kinds of markup - (like *this* or \this) is preserved by literal blocks. - Lookie here, I've dropped an indentation level - (but not far enough) - - no more example - -Results in: - - An example:: - - Whitespace, newlines, blank lines, and all kinds of markup - (like *this* or \this) is preserved by literal blocks. - Lookie here, I've dropped an indentation level - (but not far enough) - - no more example - -Note that if a paragraph consists only of "``::``", then it's removed -from the output:: - - :: - - This is preformatted text, and the - last "::" paragraph is removed - -Results in: - -:: - - This is preformatted text, and the - last "::" paragraph is removed - - -Sections --------- - -(quickref__) - -__ quickref.html#section-structure - -To break longer text up into sections, you use **section headers**. -These are a single line of text (one or more words) with adornment: an -underline alone, or an underline and an overline together, in dashes -"``-----``", equals "``======``", tildes "``~~~~~~``" or any of the -non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you -feel comfortable with. An underline-only adornment is distinct from -an overline-and-underline adornment using the same character. The -underline/overline must be at least as long as the title text. Be -consistent, since all sections marked with the same adornment style -are deemed to be at the same level:: - - Chapter 1 Title - =============== - - Section 1.1 Title - ----------------- - - Subsection 1.1.1 Title - ~~~~~~~~~~~~~~~~~~~~~~ - - Section 1.2 Title - ----------------- - - Chapter 2 Title - =============== - -This results in the following structure, illustrated by simplified -pseudo-XML:: - - <section> - <title> - Chapter 1 Title - <section> - <title> - Section 1.1 Title - <section> - <title> - Subsection 1.1.1 Title - <section> - <title> - Section 1.2 Title - <section> - <title> - Chapter 2 Title - -(Pseudo-XML uses indentation for nesting and has no end-tags. It's -not possible to show actual processed output, as in the other -examples, because sections cannot exist inside block quotes. For a -concrete example, compare the section structure of this document's -source text and processed output.) - -Note that section headers are available as link targets, just using -their name. To link to the Lists_ heading, I write "``Lists_``". If -the heading has a space in it like `text styles`_, we need to quote -the heading "```text styles`_``". - - -Document Title / Subtitle -````````````````````````` - -The title of the whole document is distinct from section titles and -may be formatted somewhat differently (e.g. the HTML writer by default -shows it as a centered heading). - -To indicate the document title in reStructuredText, use a unique adornment -style at the beginning of the document. To indicate the document subtitle, -use another unique adornment style immediately after the document title. For -example:: - - ================ - Document Title - ================ - ---------- - Subtitle - ---------- - - Section Title - ============= - - ... - -Note that "Document Title" and "Section Title" above both use equals -signs, but are distict and unrelated styles. The text of -overline-and-underlined titles (but not underlined-only) may be inset -for aesthetics. - - -Images ------- - -(quickref__) - -__ quickref.html#directives - -To include an image in your document, you use the the ``image`` directive__. -For example:: - - .. image:: images/biohazard.png - -results in: - -.. image:: images/biohazard.png - -The ``images/biohazard.png`` part indicates the filename of the image -you wish to appear in the document. There's no restriction placed on -the image (format, size etc). If the image is to appear in HTML and -you wish to supply additional information, you may:: - - .. image:: images/biohazard.png - :height: 100 - :width: 200 - :scale: 50 - :alt: alternate text - -See the full `image directive documentation`__ for more info. - -__ ../../ref/rst/directives.html -__ ../../ref/rst/directives.html#images - - -What Next? ----------- - -This primer introduces the most common features of reStructuredText, -but there are a lot more to explore. The `Quick reStructuredText`_ -user reference is a good place to go next. For complete details, the -`reStructuredText Markup Specification`_ is the place to go [#]_. - -Users who have questions or need assistance with Docutils or -reStructuredText should post a message to the Docutils-users_ mailing -list. - -.. [#] If that relative link doesn't work, try the master document: - http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html. - -.. _reStructuredText Markup Specification: - ../../ref/rst/restructuredtext.html -.. _Docutils-users: ../mailing-lists.html#docutils-users -.. _Docutils project web site: http://docutils.sourceforge.net/ +.. _docutils: http://docutils.sourceforge.net/ +.. _Git Wiki: /k/gitwiki/ diff --git a/restructured text cheatsheet b/restructured text cheatsheet new file mode 100644 index 0000000..ae6f8d0 --- /dev/null +++ b/restructured text cheatsheet @@ -0,0 +1,127 @@ +===================================================== + The reStructuredText_ Cheat Sheet: Syntax Reminders +===================================================== +:Info: See <http://docutils.sf.net/rst.html> for introductory docs. +:Author: David Goodger <goodger@python.org> +:Date: $Date: 2006-01-23 02:13:55 +0100 (Mon, 23 Jan 2006) $ +:Revision: $Revision: 4321 $ +:Description: This is a "docinfo block", or bibliographic field list + +Section Structure +================= +Section titles are underlined or overlined & underlined. + +Body Elements +============= +Grid table: + ++--------------------------------+-----------------------------------+ +| Paragraphs are flush-left, | Literal block, preceded by "::":: | +| separated by blank lines. | | +| | Indented | +| Block quotes are indented. | | ++--------------------------------+ or:: | +| >>> print 'Doctest block' | | +| Doctest block | > Quoted | ++--------------------------------+-----------------------------------+ +| | Line blocks preserve line breaks & indents. [new in 0.3.6] | +| | Useful for addresses, verse, and adornment-free lists; long | +| lines can be wrapped with continuation lines. | ++--------------------------------------------------------------------+ + +Simple tables: + +================ ============================================================ +List Type Examples +================ ============================================================ +Bullet list * items begin with "-", "+", or "*" +Enumerated list 1. items use any variation of "1.", "A)", and "(i)" + #. also auto-enumerated +Definition list Term is flush-left : optional classifier + Definition is indented, no blank line between +Field list :field name: field body +Option list -o at least 2 spaces between option & description +================ ============================================================ + +================ ============================================================ +Explicit Markup Examples (visible in the `text source <cheatsheet.txt>`_) +================ ============================================================ +Footnote .. [1] Manually numbered or [#] auto-numbered + (even [#labelled]) or [*] auto-symbol +Citation .. [CIT2002] A citation. +Hyperlink Target .. _reStructuredText: http://docutils.sf.net/rst.html + .. _indirect target: reStructuredText_ + .. _internal target: +Anonymous Target __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html +Directive ("::") .. image:: images/biohazard.png +Substitution Def .. |substitution| replace:: like an inline directive +Comment .. is anything else +Empty Comment (".." on a line by itself, with blank lines before & after, + used to separate indentation contexts) +================ ============================================================ + +Inline Markup +============= +*emphasis*; **strong emphasis**; `interpreted text`; `interpreted text +with role`:emphasis:; ``inline literal text``; standalone hyperlink, +http://docutils.sourceforge.net; named reference, reStructuredText_; +`anonymous reference`__; footnote reference, [1]_; citation reference, +[CIT2002]_; |substitution|; _`inline internal target`. + +Directive Quick Reference +========================= +See <http://docutils.sf.net/docs/ref/rst/directives.html> for full info. + +================ ============================================================ +Directive Name Description (Docutils version added to, in [brackets]) +================ ============================================================ +attention Specific admonition; also "caution", "danger", + "error", "hint", "important", "note", "tip", "warning" +admonition Generic titled admonition: ``.. admonition:: By The Way`` +image ``.. image:: picture.png``; many options possible +figure Like "image", but with optional caption and legend +topic ``.. topic:: Title``; like a mini section +sidebar ``.. sidebar:: Title``; like a mini parallel document +parsed-literal A literal block with parsed inline markup +rubric ``.. rubric:: Informal Heading`` +epigraph Block quote with class="epigraph" +highlights Block quote with class="highlights" +pull-quote Block quote with class="pull-quote" +compound Compound paragraphs [0.3.6] +container Generic block-level container element [0.3.10] +table Create a titled table [0.3.1] +list-table Create a table from a uniform two-level bullet list [0.3.8] +csv-table Create a table from CSV data (requires Python 2.3+) [0.3.4] +contents Generate a table of contents +sectnum Automatically number sections, subsections, etc. +header, footer Create document decorations [0.3.8] +target-notes Create an explicit footnote for each external target +meta HTML-specific metadata +include Read an external reST file as if it were inline +raw Non-reST data passed untouched to the Writer +replace Replacement text for substitution definitions +unicode Unicode character code conversion for substitution defs +date Generates today's date; for substitution defs +class Set a "class" attribute on the next element +role Create a custom interpreted text role [0.3.2] +default-role Set the default interpreted text role [0.3.10] +title Set the metadata document title [0.3.10] +================ ============================================================ + +Interpreted Text Role Quick Reference +===================================== +See <http://docutils.sf.net/docs/ref/rst/roles.html> for full info. + +================ ============================================================ +Role Name Description +================ ============================================================ +emphasis Equivalent to *emphasis* +literal Equivalent to ``literal`` but processes backslash escapes +PEP Reference to a numbered Python Enhancement Proposal +RFC Reference to a numbered Internet Request For Comments +raw For non-reST data; cannot be used directly (see docs) [0.3.6] +strong Equivalent to **strong** +sub Subscript +sup Superscript +title Title reference (book, etc.); standard default role +================ ============================================================ |