SMILA/Style Guide

This document gives the style conventions to be used in the SMILA Wiki. Please follow these guidelines on all SMILA Wiki pages to guarantee similar styles and conventions.

Language

Use American English.

Pages

Guidelines for the page name:

• Use a self-explanatory page name.
• Separate words in the page name by underscores, e.g. "Development_Guidelines".
• Do not use articles (the, a, an) or prepositions (to, for, from) in page names unless they are essential for understanding the context. Example: "Integrate_Components" is a better page name than "Integrate_a_Component_in_SMILA" in case your page is a general description of this topic but "How_to_Integrate_Components" is OK to indicate that your page contains a how-to tutorial.
• Use title capitalization for page names.

Other guidelines referring to the page:

• Provide a short description after the page heading that describes the contents of your page. Help the reader to quickly find out the main topic of your page.
• Provide a table of contents where it is reasonable. This should be applied automatically to your page.
• Tag your page with the SMILA category: [[Category:SMILA]]

Headings

Guidelines for headings:

• Do not omit a heading level. As the page header is already at first-level, always start with second-level headings. Only use third-level headings if you have used second-level headings before.
• Do not use title capitalization for headings, i.e. use uppercase letters for the first letter of the first word in a heading only. Subsequent words are only capitalized if they refer to a proper name.
• Do not repeat the page name as a heading.

Terminology

Use the spelling and capitalization of SMILA terms as shown on the SMILA glossary. If your term appears not on this page, add it to the glossary, and provide a description (if reasonable). Provide a link to the glossary entry on your page.

Examples

Always provide a short description of your code example. Depending on the example one or two sentences might already be enough. However, the code example alone without a description might not be very helpful.

Images

The same as with examples (see above). Make sure to provide a short description.

Conventions of formats

The following table describes how different text elements should be formatted. Please follow the conventions given.

Element	Description	Example
Properties	Use italics for properties, attributes, and parameters.	It converts the document's content defined by the AttachmentContent attribute and stores the plain text results in the AttachmentText attribute.
XML elements	Use monospace font for XML elements.	The Property element is used to define ...
Filenames	Use monospace font for filenames. If you refer to an environment variable use $varname as a reference to the variable. If you refer to the default installation directory, a user's home folder, or another typical folder use a notation in angle brackets to refer to this location in a file name. You will have to use the corresponding HTML entities to escape the angle brackets. Always use the "/" character in paths (not "\" as in Windows).	$SMILA_HOME/configuration/xyz <your-home-directory>/dev/src/xyz
Packages, classes, interfaces, ...	Use monospace font for packages, bundles, classes, interfaces and other code elements.	org.eclipse.smila.processing.pipelets.aperture
Source code	Use syntax highlighting where possible.	<PipeletConfiguration xmlns="http://www.eclipse.org/eilf/processor"> <Property name="AttachmentContent"> <Value>Content</Value> </Property> <Property name="AttachmentText"> <Value>Text</Value> </Property> <Property name="AttachmentMimeType"> <Value>MimeType</Value> </Property> </PipeletConfiguration>
Labels and UI names	Use italics for captions, labels, and the names of buttons, windows, options, and other UI elements.	Select the Checkstyle preference page and click the New button.