Index: jrst2/src/site/en/rst/user/index.rst diff -u /dev/null jrst2/src/site/en/rst/user/index.rst:1.1 --- /dev/null Tue Jun 5 15:52:19 2007 +++ jrst2/src/site/en/rst/user/index.rst Tue Jun 5 15:52:14 2007 @@ -0,0 +1,37 @@ +JRst +==== + +.. contents:: + + +Présentation +------------ + +JRst is Java ReStructuredText parser. + +Internaly Rst document is a dom4j tree that represent python docutils xml. +You can generate docbook, xhtml, xdoc or your own files with your own XSL +files. + +Usage +----- + +To generate python docutils xml just write:: + + JRST myfile.rst + +To generate html:: + + JRST -t html myfile.rst + +To generate in specified file:: + + JRST -t xdoc -o myfile.xml myfile.rst + + +Plugin maven +------------ + +Un plugin maven est disponnible à l'adresse suivante +http://jrst.labs.libre-entreprise.org/maven-jrst-plugin . Il permet l'utilisation +depuis maven de JRst. Index: jrst2/src/site/en/rst/user/RSTpresentation.rst diff -u /dev/null jrst2/src/site/en/rst/user/RSTpresentation.rst:1.1 --- /dev/null Tue Jun 5 15:52:19 2007 +++ jrst2/src/site/en/rst/user/RSTpresentation.rst Tue Jun 5 15:52:14 2007 @@ -0,0 +1,388 @@ +========================= +A ReStructuredText Primer +========================= + +Adapted from Richard Jones document : http://docutils.sourceforge.net/sandbox/wilk/french/quickstart-fr.html + +.. contents:: Sommary + + +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 +.. _master quick reference: http://docutils.sourceforge.net/docs/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__) + +__ http://docutils.sourceforge.net/docs/rst/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:: + + ``\*`` + +(``\*`` in JRST, only `` works) + + +__ http://docutils.sourceforge.net/docs/rst/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__) + +__ http://docutils.sourceforge.net/docs/rst/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__) + +__ http://docutils.sourceforge.net/docs/rst/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__) + +__ http://docutils.sourceforge.net/docs/rst/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__) + +__ http://docutils.sourceforge.net/docs/rst/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. + + 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. + + 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__) + +__ http://docutils.sourceforge.net/docs/rst/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:: + +
+ + 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__) + +__ http://docutils.sourceforge.net/docs/rst/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. + +__ http://docutils.sourceforge.net/spec/rst/directives.html +__ http://docutils.sourceforge.net/spec/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 [#]_. + + +.. [#] If that relative link doesn't work, try the master document: + http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html. + +.. _reStructuredText Markup Specification: http://docutils.sourceforge.net/spec/rst/reStructuredText.html +.. _Docutils-users: ../mailing-lists.html#docutils-users +.. _Docutils project web site: http://docutils.sourceforge.net/ Index: jrst2/src/site/en/rst/user/functionality.rst diff -u /dev/null jrst2/src/site/en/rst/user/functionality.rst:1.1 --- /dev/null Tue Jun 5 15:52:23 2007 +++ jrst2/src/site/en/rst/user/functionality.rst Tue Jun 5 15:52:14 2007 @@ -0,0 +1,249 @@ +========================= +Functionalities suggested +========================= + +Docutils DTD : http://docutils.sourceforge.net/docs/ref/doctree.html + +.. contents:: Summary + +Functionalities established +=========================== + +Root element +------------ + +- document_ + +Title elements +-------------- + +- subtitle_ +- title_ + +Bibliographic elements +---------------------- + +- docinfo_ +- author_ +- authors_ +- organization_ +- address_ +- contact_ +- version_ +- revision_ +- status_ +- date_ +- copyright_ + +Decoration elements +------------------- + +- decoration_ +- footer_ +- header_ + +Structural elements +------------------- + +- section_ +- topic_ +- sidebar_ +- transition_ + +Body elements +------------- + +- admonition_ +- attention_ +- block_quote_ +- bullet_list_ +- caution_ +- classifier_ +- danger_ +- definition_ +- definition_list_ +- definition_list_item_ +- description_ +- doctest_block_ +- enumerated_list_ +- error_ +- field_ +- field_body_ +- field_list_ +- field_name_ +- footnote_ +- hint_ +- image_ +- important_ +- line_ +- line_block_ +- list_item_ +- literal_block_ +- note_ +- option_ +- option_argument_ +- option_group_ +- option_list_ +- option_list_item_ +- option_string_ +- paragraph_ +- term_ +- tip_ +- warning_ + +Table elements +-------------- + +- table_ +- tbody_ +- entry_ +- row_ +- colspec_ +- thead_ +- tgroup_ + +Inline elements +--------------- + +- emphasis_ +- strong_ +- literal_ +- reference_ +- footnote_reference_ + + +Unimplemented functionalities +============================= + +- abbreviation_ +- acronym_ +- attribution_ +- caption_ +- citation_ +- citation_reference_ +- comment_ +- compound_ +- container_ +- figure_ +- generated_ +- inline_ +- label_ +- legend_ +- pending_ +- problematic_ +- raw_ +- rubric_ +- subscript_ +- substitution_definition_ +- substitution_reference_ +- superscript_ +- system_message_ +- target_ +- title_reference_ + +.. _abbreviation: http://docutils.sourceforge.net/docs/ref/doctree.html#abbreviation +.. _acronym: http://docutils.sourceforge.net/docs/ref/doctree.html#acronym +.. _address: http://docutils.sourceforge.net/docs/ref/doctree.html#address +.. _admonition: http://docutils.sourceforge.net/docs/ref/doctree.html#admonition +.. _attention: http://docutils.sourceforge.net/docs/ref/doctree.html#attention + +.. _attribution: http://docutils.sourceforge.net/docs/ref/doctree.html#attribution +.. _author: http://docutils.sourceforge.net/docs/ref/doctree.html#author +.. _authors: http://docutils.sourceforge.net/docs/ref/doctree.html#authors +.. _block_quote: http://docutils.sourceforge.net/docs/ref/doctree.html#block-quote +.. _bullet_list: http://docutils.sourceforge.net/docs/ref/doctree.html#bullet-list +.. _caption: http://docutils.sourceforge.net/docs/ref/doctree.html#caption +.. _caution: http://docutils.sourceforge.net/docs/ref/doctree.html#caution +.. _citation: http://docutils.sourceforge.net/docs/ref/doctree.html#citation +.. _citation_reference: http://docutils.sourceforge.net/docs/ref/doctree.html#citation-reference + +.. _classifier: http://docutils.sourceforge.net/docs/ref/doctree.html#classifier +.. _colspec: http://docutils.sourceforge.net/docs/ref/doctree.html#colspec +.. _comment: http://docutils.sourceforge.net/docs/ref/doctree.html#comment +.. _compound: http://docutils.sourceforge.net/docs/ref/doctree.html#compound +.. _contact: http://docutils.sourceforge.net/docs/ref/doctree.html#contact +.. _container: http://docutils.sourceforge.net/docs/ref/doctree.html#container +.. _copyright: http://docutils.sourceforge.net/docs/ref/doctree.html#copyright +.. _danger: http://docutils.sourceforge.net/docs/ref/doctree.html#danger +.. _date: http://docutils.sourceforge.net/docs/ref/doctree.html#date + +.. _decoration: http://docutils.sourceforge.net/docs/ref/doctree.html#decoration +.. _definition: http://docutils.sourceforge.net/docs/ref/doctree.html#definition +.. _definition_list: http://docutils.sourceforge.net/docs/ref/doctree.html#definition-list +.. _definition_list_item: http://docutils.sourceforge.net/docs/ref/doctree.html#definition-list-item +.. _description: http://docutils.sourceforge.net/docs/ref/doctree.html#description +.. _docinfo: http://docutils.sourceforge.net/docs/ref/doctree.html#docinfo +.. _doctest_block: http://docutils.sourceforge.net/docs/ref/doctree.html#doctest-block +.. _document: http://docutils.sourceforge.net/docs/ref/doctree.html#document +.. _emphasis: http://docutils.sourceforge.net/docs/ref/doctree.html#emphasis + +.. _entry: http://docutils.sourceforge.net/docs/ref/doctree.html#entry +.. _enumerated_list: http://docutils.sourceforge.net/docs/ref/doctree.html#enumerated-list +.. _error: http://docutils.sourceforge.net/docs/ref/doctree.html#error +.. _field: http://docutils.sourceforge.net/docs/ref/doctree.html#field +.. _field_body: http://docutils.sourceforge.net/docs/ref/doctree.html#field-body +.. _field_list: http://docutils.sourceforge.net/docs/ref/doctree.html#field-list +.. _field_name: http://docutils.sourceforge.net/docs/ref/doctree.html#field-name +.. _figure: http://docutils.sourceforge.net/docs/ref/doctree.html#figure +.. _footer: http://docutils.sourceforge.net/docs/ref/doctree.html#footer + +.. _footnote: http://docutils.sourceforge.net/docs/ref/doctree.html#footnote +.. _footnote_reference: http://docutils.sourceforge.net/docs/ref/doctree.html#footnote-reference +.. _generated: http://docutils.sourceforge.net/docs/ref/doctree.html#generated +.. _header: http://docutils.sourceforge.net/docs/ref/doctree.html#header +.. _hint: http://docutils.sourceforge.net/docs/ref/doctree.html#hint +.. _image: http://docutils.sourceforge.net/docs/ref/doctree.html#image +.. _important: http://docutils.sourceforge.net/docs/ref/doctree.html#important +.. _inline: http://docutils.sourceforge.net/docs/ref/doctree.html#inline +.. _label: http://docutils.sourceforge.net/docs/ref/doctree.html#label + +.. _legend: http://docutils.sourceforge.net/docs/ref/doctree.html#legend +.. _line: http://docutils.sourceforge.net/docs/ref/doctree.html#line +.. _line_block: http://docutils.sourceforge.net/docs/ref/doctree.html#line-block +.. _list_item: http://docutils.sourceforge.net/docs/ref/doctree.html#list-item +.. _literal: http://docutils.sourceforge.net/docs/ref/doctree.html#literal +.. _literal_block: http://docutils.sourceforge.net/docs/ref/doctree.html#literal-block +.. _note: http://docutils.sourceforge.net/docs/ref/doctree.html#note +.. _option: http://docutils.sourceforge.net/docs/ref/doctree.html#option +.. _option_argument: http://docutils.sourceforge.net/docs/ref/doctree.html#option-argument + +.. _option_group: http://docutils.sourceforge.net/docs/ref/doctree.html#option-group +.. _option_list: http://docutils.sourceforge.net/docs/ref/doctree.html#option-list +.. _option_list_item: http://docutils.sourceforge.net/docs/ref/doctree.html#option-list-item +.. _option_string: http://docutils.sourceforge.net/docs/ref/doctree.html#option-string +.. _organization: http://docutils.sourceforge.net/docs/ref/doctree.html#organization +.. _paragraph: http://docutils.sourceforge.net/docs/ref/doctree.html#paragraph +.. _pending: http://docutils.sourceforge.net/docs/ref/doctree.html#pending +.. _problematic: http://docutils.sourceforge.net/docs/ref/doctree.html#problematic +.. _raw: http://docutils.sourceforge.net/docs/ref/doctree.html#raw + +.. _reference: http://docutils.sourceforge.net/docs/ref/doctree.html#reference +.. _revision: http://docutils.sourceforge.net/docs/ref/doctree.html#revision +.. _row: http://docutils.sourceforge.net/docs/ref/doctree.html#row +.. _rubric: http://docutils.sourceforge.net/docs/ref/doctree.html#rubric +.. _section: http://docutils.sourceforge.net/docs/ref/doctree.html#section +.. _sidebar: http://docutils.sourceforge.net/docs/ref/doctree.html#sidebar +.. _status: http://docutils.sourceforge.net/docs/ref/doctree.html#status +.. _strong: http://docutils.sourceforge.net/docs/ref/doctree.html#strong +.. _subscript: http://docutils.sourceforge.net/docs/ref/doctree.html#subscript + +.. _substitution_definition: http://docutils.sourceforge.net/docs/ref/doctree.html#substitution-definition +.. _substitution_reference: http://docutils.sourceforge.net/docs/ref/doctree.html#substitution-reference +.. _subtitle: http://docutils.sourceforge.net/docs/ref/doctree.html#subtitle +.. _superscript: http://docutils.sourceforge.net/docs/ref/doctree.html#superscript +.. _system_message: http://docutils.sourceforge.net/docs/ref/doctree.html#system-message +.. _table: http://docutils.sourceforge.net/docs/ref/doctree.html#table +.. _target: http://docutils.sourceforge.net/docs/ref/doctree.html#target +.. _tbody: http://docutils.sourceforge.net/docs/ref/doctree.html#tbody +.. _term: http://docutils.sourceforge.net/docs/ref/doctree.html#term + +.. _tgroup: http://docutils.sourceforge.net/docs/ref/doctree.html#tgroup +.. _thead: http://docutils.sourceforge.net/docs/ref/doctree.html#thead +.. _tip: http://docutils.sourceforge.net/docs/ref/doctree.html#tip +.. _title: http://docutils.sourceforge.net/docs/ref/doctree.html#title +.. _title_reference: http://docutils.sourceforge.net/docs/ref/doctree.html#title-reference +.. _topic: http://docutils.sourceforge.net/docs/ref/doctree.html#topic +.. _transition: http://docutils.sourceforge.net/docs/ref/doctree.html#transition +.. _version: http://docutils.sourceforge.net/docs/ref/doctree.html#version +.. _warning: http://docutils.sourceforge.net/docs/ref/doctree.html#warning +