Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "SMILA/Style Guide"

(New page: 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. == Pages ==...)
 
m (Terminology)
 
(8 intermediate revisions by one other user not shown)
Line 1: Line 1:
 
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.
 
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 ==
 
== Pages ==
Line 6: Line 10:
  
 
* Use a self-explanatory page name.
 
* Use a self-explanatory page name.
* Separate words in the page name by underscores, e.g. "Development_guidelines".
+
* 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.
+
* 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.
* Capitalize the first letter.
+
* Use title capitalization for page names.
* Do not capitalize second and subsequent words unless the term is almost always capitalized in English (for example, proper names).
+
 
  
 
Other guidelines referring to the page:
 
Other guidelines referring to the page:
Line 16: Line 20:
 
* Provide a table of contents where it is reasonable. This should be applied automatically to 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: <code><nowiki>[[Category:SMILA]]</nowiki></code>
 
* Tag your page with the SMILA category: <code><nowiki>[[Category:SMILA]]</nowiki></code>
 
  
 
== Headings ==
 
== Headings ==
Line 22: Line 25:
 
Guidelines for headings:
 
Guidelines for headings:
  
* Do not omit a heading level.
+
* 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 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.
 
* Do not repeat the page name as a heading.
 
  
 
== Terminology ==
 
== Terminology ==
  
Use the spelling and capitalization of SMILA terms as shown on the [[SMILA/Glossary|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.
+
Use the spelling and capitalization of SMILA terms as shown on the [[SMILA/Glossary|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 ==
 
== 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.
 
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 ==
 
== Images ==
Line 68: Line 69:
 
| <tt>org.eclipse.smila.processing.pipelets.aperture</tt>
 
| <tt>org.eclipse.smila.processing.pipelets.aperture</tt>
 
|-
 
|-
| Source Code
+
| Source code
 
| Use [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi syntax highlighting] where possible.
 
| Use [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi syntax highlighting] where possible.
 
| <source lang="xml">
 
| <source lang="xml">
Line 84: Line 85:
 
</source>
 
</source>
 
|-
 
|-
 +
| 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.
 
|}
 
|}
  
 
[[Category:SMILA]]
 
[[Category:SMILA]]

Latest revision as of 06:17, 17 October 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.

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.

Copyright © Eclipse Foundation, Inc. All Rights Reserved.