Personal tools
Views
How to contribute to “Grid Made Easy”
“Grid Made Easy” is a collaborative effort to write a book using a Wiki system. That is, its content will be always on-line, immediately editable and browsable on the web, but, from time to time, hardcopy snapshots will be produced, to distribute the contents in paper form (for instance, as handouts at training sessions).
Please note:
Please bear this twofold nature in mind when reading the following guidelines: the requirement to produce printout copies imposes some restrictions on the freedom you usually get with a Wiki, and the Wiki nature of the system changes some conventions and practices that are commonly in use when producing printed material.
Distributed authoring of a book using a ZWiki? is an experiment, and very little experience is available about that. We will need to dig the best practices out. It is very likely that the guidelines suggested here will change in the future, and will probably change often at the very start. Please be patient.
If you think that something can be improved of if you have any suggestion, please speak up!
The rest of this document lists some convetions and guidelines that should be followed in order to give to the text a uniform appearance, and that the various pieces can be easily collated to form a printed book when needed.
- Use reStructuredText as markup language
- Strictly follow the Typographical conventions
- Subscribe to the pages of your concern
- Order of reST headings
- Use links, instead of citations
- How to link to a section/chapter
- Use “smart quotes” for quoting text
- Remeber to fill the “change note” line
- Useful software
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).
Where to learn reStructuredText
You will find all you need to know about reStructuredText (reST for short) at:
http://docutils.sf.net/rst.html
Read the reStructuredText Primer first; you will be able to start editing “Grid Made Easy” right away!
Why reStructuredText?
reStructuredText was chosen above other markup languages, because:
- It can be easily and instantly converted to HTML, PDF, LaTeX? and, of course, plain text.
- It is easy to read and almost WYSIWYG: the markup is lightweight and unobtrusive, and it will actually make the text source easier to read.
- Since it is based on plain text, it can be edited on any platform and any OS.
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!
Note
Please subscribe to the all edits of the Authoring and Typographical conventions pages, as we need to stay current on every change in those topics.
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].
Warning
Even though ZWiki? allows you to omit punctuation and spaces, and to use CamelCase? for links enclosed in square brackets, please type the chapter/page name reference in full (that is, write it as it is in the reST source), otherwise we cannot convert it back to a reST link when preparing the all-in-one printout.
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.
Smart quotes with the Vim editor
The following link will tell you how to setup Vim to support Unicode “smart quotes”:
http://www.oreillynet.com/xml/blog/2005/10/smart_quotes_and_more_in_vim_a.html
Smart quotes with the Emacs editor
Emacs input methods make it simple to enter any Unicode character; by default Emacs is configured to use the RFC 1345 input method, which allows easy entering of most glyphs used in Western language scripts as three-character key sequences.
Press Ctrl+\ to activate the RFC 1345 input method. A lower case m will appear as the second character in the mode line, to signal that RFC 1345 input method is active.
When RFC 1345 input method is on, you can insert any Unicode character by typing the two-character sequence assigned to it in RFC 1345, prefixed by &.
Use the following key sequences to produce smart quotes and other common typographical symbols:
Key sequence
Glyph
&"6
“
&"9
”
&<<
«
&>>
»
&-N
–
&-M
—
You can insert any Unicode character by typing the two-character sequence assigned to it in RFC 1345, prefixed by &.
3. Press Ctrl+\ again to de-activate RFC 1345 input method and return the & character to its normal behaviour.
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.