You are here: Home Grid Made Easy Authoring
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

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 “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.

  1. 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 &.

  2. 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.


« October 2017 »
Su Mo Tu We Th Fr Sa
1234567
891011121314
15161718192021
22232425262728
293031
 

Powered by Plone This site conforms to the following standards: