Jump to: navigation, search

Difference between revisions of "EUG:How to Contribute"

(Levels)
 
(30 intermediate revisions by the same user not shown)
Line 1: Line 1:
= How to Contribute to the Eclipse Users Guide  =
+
__TOC__
  
[[Image:Ecf.how to contribute 1.png|right]] These wiki pages are the source of the ECF Users Guide. The text that will be created here will end up here, for everybody to read, in the Eclipse help that accompanies the ECF software and maybe even in the printed book, who knows.
+
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=329124 Tracking Bug 329124 [[Image:Bug.png|Bug 329124]]]<br>
  
The information in link (2) from the right side image is the central source of our document User Guide. It contains all information in the book. This is the place that will get parsed by our document builders to transform this documentation to other formats.  
+
= How to Contribute to the ECF Guide  =
 +
 
 +
These wiki pages are the source of the ECF Guides. This text will not only be visible here but also in the Eclipse help that accompanies the ECF software and maybe even in the printed book, who knows.
 +
 
 +
The information in link (2) from the right side image is the central source of our Guide. It contains all information in the book. This is the place that will get parsed by our document builders to transform this documentation to other formats.  
  
 
We have created some rules and guidelines for you to follow so that your contribution is as effective as possible. &nbsp;  
 
We have created some rules and guidelines for you to follow so that your contribution is as effective as possible. &nbsp;  
Line 11: Line 15:
 
== (1) Namespace for pages and images&nbsp;  ==
 
== (1) Namespace for pages and images&nbsp;  ==
  
If you create a new wiki page in this manual. You must precede it with the&nbsp;'''UEG: '''manual namespace. [http://www.mediawiki.org/wiki/Manual:Namespace Click here for more info on that].&nbsp;It groups related content.  
+
[[Image:Ecf.how to contribute 1.png|right]] If you create a new wiki page in this manual. You must precede it with the&nbsp;'''UEG: '''manual namespace. [http://www.mediawiki.org/wiki/Manual:Namespace Click here for more info on that].&nbsp;It groups related content. Look at the name of this page for an example.
 +
 
 +
All images used in this document must be prefixed with '''ecf.''' and, if the image is local, with the local name embedded. For example, the image on the right is called '''ecf.how_to_contribute_1.png'''. A global file, like a logo for example would be called something like '''ecf.logo.bmp'''.
 +
 
 +
As you can see at (1), the page title shows the namespace but it does not show it at (2). This is because the link is created like this
 +
<nowiki>[[EUG:ECF User Guide|ECF User Guide]]</nowiki>.
 +
The horizontal line in the middle separates the real name from the displayed name. You only have to type the horizontal line when inserting a link to a new page, the title will be automatically inserted without the namespace when the page is saved.
 +
 
 +
<br>
 +
 
 +
== (2) The Complete Manual  ==
 +
 
 +
This link lists the complete book on one single web page. This is done by a process called [http://www.mediawiki.org/wiki/Inclusion transclusion]&nbsp;which is a fancy word for inclusion. If you edit the page that (2) links to, you will see this:
 +
 
 +
[[Image:Ecf.how to contribute inclusion.png|400px]]
 +
 
 +
The special '''<nowiki>{{: name of page }}</nowiki>'''&nbsp;construct will include the contents of that page. Marvelous.
 +
 
 +
== (3) Chapters  ==
 +
 
 +
'''Foreword, Introduction, The Communications Perspective, ..''' are the chapters in the manual. They are level 1 headings (= title =).
 +
 
 +
== (4) Topics  ==
 +
 
 +
These are the flesh of the manual and they contain the actual content. we might can use level 2 headings (== title ==) in order to get them noted in the TOC. Subdivisions inside topics (paragraphs) should have a level 3 (=== paragraph ===). Use this sparsely.
 +
 
 +
Should we allow level 4 headings??
 +
 
 +
== Levels  ==
 +
 
 +
Chapter, Topic and Paragraph. Deeper we may not go.
 +
 
 +
== Special Directives and Templates ==
 +
 
 +
It would be great if we could use this text as helptext for Eclipse user interface elements like wizards and wizard pages. This is under investigation.
 +
 
 +
===Formatting Java code===
 +
 
 +
In order to format code as java code, use the following directive
 +
 
 +
<pre>
 +
<source lang="java">
 +
public interface MyService {
 +
   
 +
    public String hello(String name);
 +
 
 +
}
 +
</source>
 +
</pre>
 +
 
 +
This will yield the following text:
 +
 
 +
<source lang="java">
 +
public interface MyService {
 +
   
 +
    public String hello(String name);
 +
 
 +
}
 +
</source>
 +
 
 +
 
 +
===Using Tables===
 +
When using tables, try to use the following template as much as possible
 +
 
 +
<pre>
 +
{|{{BMTableStyle}}
 +
|-{{BMTHStyle}}
 +
! Bundle
 +
! Description
 +
|-
 +
| example.bundle
 +
| This is an example
 +
|-
 +
| another.example.bundle
 +
| This is another example
 +
|}
 +
</pre>
 +
 
 +
Which will yield:
 +
{|{{BMTableStyle}}
 +
|-{{BMTHStyle}}
 +
! Bundle
 +
! Description
 +
|-
 +
| example.bundle
 +
| This is an example
 +
|-
 +
| another.example.bundle
 +
| This is another example
 +
|}
  
All images used in this document must be prefixed with '''ecf. '''
+
== Versioning  ==
  
As you can see at (1), the page title shows the namespace but it does not show it at (2). This is because the link is created like this &lt;big&gt; [[EUG:ECF User Guide|ECF User Guide]] &lt;/big&gt;. It &nbsp;
+
For releases after this, we might need versioning of some kind. This is under investigation.

Latest revision as of 18:24, 13 February 2011

Tracking Bug 329124 Bug 329124

How to Contribute to the ECF Guide

These wiki pages are the source of the ECF Guides. This text will not only be visible here but also in the Eclipse help that accompanies the ECF software and maybe even in the printed book, who knows.

The information in link (2) from the right side image is the central source of our Guide. It contains all information in the book. This is the place that will get parsed by our document builders to transform this documentation to other formats.

We have created some rules and guidelines for you to follow so that your contribution is as effective as possible.  


(1) Namespace for pages and images 

Ecf.how to contribute 1.png
If you create a new wiki page in this manual. You must precede it with the UEG: manual namespace. Click here for more info on that. It groups related content. Look at the name of this page for an example.

All images used in this document must be prefixed with ecf. and, if the image is local, with the local name embedded. For example, the image on the right is called ecf.how_to_contribute_1.png. A global file, like a logo for example would be called something like ecf.logo.bmp.

As you can see at (1), the page title shows the namespace but it does not show it at (2). This is because the link is created like this

[[EUG:ECF User Guide|ECF User Guide]]. 

The horizontal line in the middle separates the real name from the displayed name. You only have to type the horizontal line when inserting a link to a new page, the title will be automatically inserted without the namespace when the page is saved.


(2) The Complete Manual

This link lists the complete book on one single web page. This is done by a process called transclusion which is a fancy word for inclusion. If you edit the page that (2) links to, you will see this:

Ecf.how to contribute inclusion.png

The special {{: name of page }} construct will include the contents of that page. Marvelous.

(3) Chapters

Foreword, Introduction, The Communications Perspective, .. are the chapters in the manual. They are level 1 headings (= title =).

(4) Topics

These are the flesh of the manual and they contain the actual content. we might can use level 2 headings (== title ==) in order to get them noted in the TOC. Subdivisions inside topics (paragraphs) should have a level 3 (=== paragraph ===). Use this sparsely.

Should we allow level 4 headings??

Levels

Chapter, Topic and Paragraph. Deeper we may not go.

Special Directives and Templates

It would be great if we could use this text as helptext for Eclipse user interface elements like wizards and wizard pages. This is under investigation.

Formatting Java code

In order to format code as java code, use the following directive

<source lang="java">
public interface MyService {
    
    public String hello(String name);

}
</source> 

This will yield the following text:

public interface MyService {
 
    public String hello(String name);
 
}


Using Tables

When using tables, try to use the following template as much as possible

{|{{BMTableStyle}}
|-{{BMTHStyle}}
! Bundle
! Description
|-
| example.bundle
| This is an example
|-
| another.example.bundle
| This is another example
|}

Which will yield:

Bundle Description
example.bundle This is an example
another.example.bundle This is another example

Versioning

For releases after this, we might need versioning of some kind. This is under investigation.