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

DocumentationGuidelines/StyleGuidelines

Warning2.png
Draft Content
This page is currently under construction. Community members are encouraged to maintain the page, and make sure the information is accurate.


Admonitions

There are five types of admonitions:

  • caution
  • important
  • note
  • tip
  • warning

All of the admonitions have the same structure: an optional title followed by paragraph-level elements. To make a paragraph into an admonition, use the special admonition template. A short title and a longer descriptive paragraph are recommended!

What you type What you see
{{note|A title|Here is more information about this tip.}}
Note.png
A title
Here is more information about this tip.

Indent the initial and second paragraph by one space, to ensure that the box aligns correctly.

These are the standard types of admonition:

What you type What you see
{{note|This is a note|Informational paragraph
that tells more about what is going on.}}
Note.png
This is a note
Informational paragraph that tells more about what is going on.
{{tip|This is a tip|Informational paragraph
that tells more about what is going on.}}
Idea.png
This is a tip
Informational paragraph that tells more about what is going on.
{{important|This is important|Informational paragraph
that tells more about what is going on.}}
Important.png
This is important
Informational paragraph that tells more about what is going on.
{{caution|This is a caution|Informational paragraph
that tells more about what is going on.}}
Stop.png
This is a caution
Informational paragraph that tells more about what is going on.
{{warning|This is a warning|Informational paragraph
that tells more about what is going on.}}
Warning2.png
This is a warning
Informational paragraph that tells more about what is going on.

Source Code Examples

Eclipsepedia has an extension tag for allowing syntax highlighting of source code.

Java

<source lang="java">
// Get XML Schema Information for the Document
XSModel schema = getGrammar();

DynamicContext dc = setupDynamicContext(schema);

String xpath = extractXPathExpression(xqFile, inputFile);
String actual = null;

</source>

Renders as:

// Get XML Schema Information for the Document
XSModel schema = getGrammar();
 
DynamicContext dc = setupDynamicContext(schema);
 
String xpath = extractXPathExpression(xqFile, inputFile);
String actual = null;

XML: plugin.xml or other xml related

XML formatting should follow these particular guidelines:

  • Indent with 3 spaces for each element node
  • Make the format so that it is human readable at 80 columns

The output could be generated to muliple sources so what looks fine in a web page, may not render the same in a PDF or other media format.

Idea.png
Format to least common denominator
Since output could go to the web, eclipse help, wiki, pdf, or ebook. It is best to try and format to the least common denominator. Assume for XML formatting that 80 characters wide is the max available.


<source lang="xml">
<extension
       point="org.eclipse.ant.core.antTasks">
   <antTask
     class="org.eclipse.wst.xsl.core.internal.ant.XIncludeTask"
     headless="true"
     library="lib/xinclude.jar"
     name="xsl.xinclude">
   </antTask>
</extension>
</source>

Renders as:

<extension
       point="org.eclipse.ant.core.antTasks">
   <antTask
     class="org.eclipse.wst.xsl.core.internal.ant.XIncludeTask"
     headless="true"
     library="lib/xinclude.jar"
     name="xsl.xinclude">
   </antTask>
</extension>

Back to the top