Use reStructuredText as markup language

Although ZWiki? allows pages written in many markup languages (HTML, reST, MoinMoin?, etc.), we shall make use of reStructuredText only. If you create HTML pages (or with a markup different from reST), please be sure to convert them to reST ASAP (it might be a good idea to add an item to the TO DO list).

Strictly follow the Typographical conventions

Write your text strictly following the layout and typographical conventions set up in the Typographical conventions page: users will read and refer to that page in order to know how to parse the text (e.g., to know what part of a command line is to be typed “as-is”, and what is a “metasyntactic variable” and needs to be substituted). If you don't follow typographical conventions, users will need to rely on the context to guess, which means that novice users (which are the primary intended audience of “Grid Made Easy”) will often be puzzled and need to guess.

See the source of the Typographical conventions page to know how to write reST markup for various parts of text.

If you need to write a text paragraph for which there is no applicable convention, define one in Typographical conventions before you start using it. Please, put a reST .. comment explaining the rationale behind your choice in the paragraph explaining the notation to users; the comment will not appear in the text, but will be visible to authors.

It might be a good idea to discuss the new convention in Discussion first, as others may suggest a different solution.

Subscribe to the pages of your concern

When you are subscribed to a page, you will receive an email when someone adds comments to that page, or (at your option) for every edit of the page.

Use the button “subscribe” (in the middle of the tabs just above the page contents frame) to track changes to the pages you are editing. Be sure to check the button all edits to be alerted of all edits on the pages of your concern!

For more information on the mail-out feature of ZWiki? see: http://zwiki.org/Mail

Order of reST headings

Although reST does not impose any particular order for headings decorations, one needs to be imposed in order to keep coherence among the various pages: when they parts are pulled together to make the book, sections need to be tagged in a coherent manner, or the document structure will be all messed up.

So, tag the chapter titles this way:

=========================
 This is a chapter title
=========================

There should be at most one title this big per page.

Sections (Level 1 section headings) should be tagged with a row of — below, this way:

Level 1 section heading
-----------------------

Subsections (Level 2 section headings) should be tagged with a row of ~ below, like this:

Level 2 section heading
~~~~~~~~~~~~~~~~~~~~~~~

Sub-subsections (level 3 section headings) should be tagged with a row of . below, like this:

Level 3 section heading
.......................

You should not use sections more deep than sub-subsections, as they will not be rendered properly on the web site. (Ask yourself: do you really need such a fine-grained distinction?)

Use links, instead of citations

While reST has support for citations of books and papers, this is also a Wiki site, so a link to an online resource is often better than a reference to a printed paper. Moreover, this is a manual about Grid software, which is rapidly changing and in constant evolution — even online references are often out-of-date!

So, use links to online resources whenever possible; but if a citation is more sensible, then define it in the proximity of the paragraph where you use it:

The standard reference on the whole computing Grid idea is
generally considered [GRID2].

.. [GRID2] “The Grid 2: Blueprint for a New Computing
   Infrastructure” (The Elsevier Series in Grid Computing) by Ian
   Foster (Editor), Carl Kesselman (Editor)

How to link to a section/chapter

If the chapter/section/subsection is part of the current page, then just follow normal reST link notation; for instance:

See the `Use reStructuredText as markup language`_ section.

If you wish to refer to a chapter that is in another ZWiki? page, then just put the title enclosed in square brackets, for example:

See the [Typographical conventions] section for reference.

If you need to link to a section/subsection of another chapter/page, spell out the chapter name as a ZWiki? link, and the section name as a reST link:

See section `Use reStructuredText as markup language`_ in chapter
[Authoring].

Use “smart quotes” for quoting text

According to Typographical conventions, ASCII quotes " are used to denote metasynctatic variables, so, for visual distinction and sheer typographic beauty, Unicode “smart quotes” should be used to actually quote text.

Remeber to fill the “change note” line

Please, remember to give a one-line account of your edits (unless it's a very minor one, like a typo fix) by filling the Optional change note field in the ZWiki? edit form.

This makes it easier for others to consult the ZWiki? history, and quickly locate changes they are interested in.

Useful software

Zope External Editor

The Zope External Editor is a “configurable helper application that allows you to drop into your favorite editor(s) [...]? to modify Zope objects.” That is, you just click on the little “pencil” icon (located on top left on the ZWiki? page) and the page contents will open in a text editor (configure with the ~/.zope-external-edit file); when you save changes and close the editor window, the new content is uploaded to the zope/plone server. There is a Debian package ready for installation

This page tells you how to set up the Zope External Editor for a ZWiki?:

http://zwiki.org/HowToEditPagesWithExternalEditor

Other useful links on Zope External Editor:

http://wiki.zope.org/zope2/ExternalEditor

http://www.linuxtrent.it/documentazione/wikiplone/ZopeExternalEditor

Mozex

Mozex is a Mozilla Firefox extension that lets you edit HTML textareas into an external editor of your choice. It is independent of Zope and Plone, and will work with any HTML form.

rst.el

rst.el is an Emacs major mode for editing reST documents. You can find instructions on how to setup and use it at http://docutils.sourceforge.net/docs/user/emacs.html ; download the code from http://furius.ca/pubcode/pub/conf/common/elisp/rst.el

table.el

table.el is a collection of Emacs functions for editing ASCII tables; it can create and edit tables with the format required and understood by reST.