Difference between revisions of "SMILA/Style Guide"
Revision as of 04:51, 29 September 2008
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.
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:
Guidelines for headings:
- Do not omit a heading level.
- 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.
Use the spelling and capitalization of SMILA terms as shown on the SMILA glossary. If you 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.
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.
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.
|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
|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>