Sources for the Eclipse Project Handbook

Clone this repo:
  1. 4853fea Tweak the election section. by Wayne Beaton · 12 days ago master
  2. f1d9782 Update and generalize content related to the simultaneous release. by Wayne Beaton · 6 weeks ago
  3. 2fd5ee9 Consistency tweaks. by Wayne Beaton · 6 weeks ago
  4. a36c28f Initial content for a section on the role of PMCs by Wayne Beaton · 6 weeks ago
  5. 71e1e49 Add an FAQ entry about preserving headers when a file is split. by Wayne Beaton · 6 weeks ago

Eclipse Project Handbook

This repository contains the sources for the Eclipse Project Handbook. All content is represented in Asciidoc format and Asciidoctor is used to render the content into HTML, PDF, and EPUB formats. Note that the documents are all rendered complete (i.e. images and other resources are embedded).

The file contains information regarding how to contribute to this project.

General Formatting Rules

  • All content is written using Asciidoc; rendered using Asciidoctor (which has some functionality enhancements.
  • Don't wrap lines; use a single line for each paragraph.
  • Each chapter has a machine name (e.g. legaldoc); that machine name should be used as a prefix in heading anchors separated with a dash (e.g. legaldoc-license).
  • Preserve the machine names for headers, even when subsections move from one chapter to another.
  • Main text should be written in the third person. Notes and other callouts may be written in the second person.

Specific Formatting Guidelines

Use monospace backticks for file/repo paths, e.g. stuff/junk/, technical terms (e.g. class names), and for pass:[+1], pass:[-1].

Use[UI Macros] to describe menus, key bindings, etc. e.g. kbd:[Ctrl+Shift+N] and menu:View[Zoom > Reset]. Use menus to capture click paths, paths through a preferences dialog, etc.

Make sure that images that are not inline are specified as image blocks.


Where possible, we use Graphviz dot to describe images (use of text-based source for graphics makes it easier to track changes, and adds a level of consistency, allows contributors to get bogged down and frustrated trying to get an image to render “just right”). Render as SVG when possible.

[graphviz, images/overview, svg]
.An overview of the Project Creation Process
digraph {
	node [shape=box;style=filled;fillcolor=white;fontsize=12];
	proposal[label="Project Proposal", group=g1];
	community[label="Community Review", group=g1];
	review[label="Creation Review", group=g1];
	provision[label="Provision", group=g1]
	node [shape=plaintext;fillcolor=transparent;fontsize=10]
	approval [label="EMO\nApproval"]
	trademark [label="Trademark\nReview"]
	mentors [label="Mentors"]
	paperwork [label="Committer\nPaperwork"]

	proposal -> community -> review -> provision
	edge [color=grey]
	approval -> community
	mentors -> review
	trademark -> review
	paperwork -> provision
	// Force the trademark and mentors boxes to
	// be on either side of the main process points.
	// Do this by creating invisible lines that would
	// cross if they are on the same side.
	node[style=invis] ic
	edge [style=invis]
	trademark -> ic

Use callout blocks. NOTE, WARNING, and TIP are supported.

Use blocks to render NOTE/WARNING callouts.

We use pseudo legal capitalization form for defined terms. The first occurance of a defined term in every chapter should be italicised. We use quotes sparringly (generally only for actual quotes).

* _Eclipse Project_ is a defined term;
* _Top-Level Project_ is also a defined term; we always hyphenate "Top-Level";
* We prefer the use of _Third-party content_  rather than, e.g., "library"

Converting Existing Content

We've used Pandoc to convert existing content into Asciidoc for inclusion in the handbook.

 pandoc --atx-headers --wrap=none -f html -t asciidoc input.html > output.adoc

Content exported from Google Docs comes with some extra cruft around URLs. Filter that out using sed.

sed -E -e 's/https:\/\/www\.google\.com\/url\?q=([^%[&]+)(%23([^&]+))?\&[^[]+/\1#\3/g'