EUG:How to Contribute

Tracking 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 

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:

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.