Jump to: navigation, search

Jetty/Contributor/Editing the Wiki



Introduction

The Jetty Wiki structure is organized into sections, one tab for each section. The sections are described in the Jetty wiki index. For adding pages to each tab, use the following guidelines:

Getting Started
Use the Jetty Starting template. This list should be kept very short, and reference only the important getting started subjects: downloading, installing, running, upgrading.
Features
Use the Jetty Feature template. These are also howto-like entries, but the section should contain only headline features like continuations, embedding etc. They should not contain too much detail, but instead link to howtos and/or references.

A feature will always be one feature per page.
Tutorials
Use the Jetty Tutorial template. These are longer entries with worked examples, often starting from something simple, and expanding to more complex examples. Tutorials are not exhaustive in their detail, but can link references for detail.

A tutorial may be multiple pages.
Howtos
Use the Jetty Howto template. The URL to the page should be readable as: "Jetty/Howto/Do Something". Note the tense of the verb, and that the "how to" is not in the page name; only in the URL. As much as possible, links to the page should use the words "how to". That is: [[Jetty/Howto/Configure Jetty|How to Configure Jetty]]: How to Configure Jetty

These are introductory pages to specific feature sets (e.g., clustering, comet, security). The are like short tutorials and probably lack worked examples. They will often cover multiple related subjects, but should not contain too much detail. Instead, link to reference pages.

A howto will always be one howto per page.
References
Use the Jetty Reference template. These are detailed single subject pages, e.g., configuration formats, session configuration. etc.

A reference will always be one reference per page.
FAQ
Use the Jetty FAQ Section and Jetty FAQ templates. These are like chatty indexes into howtos and references that use the question form to guide the reader. The answers should be short and to the point. Link to howtos and references for the details.

Questions like "Where do I download Jetty?" do not belong in an FAQ; this should be easily discoverable from the site navigation. A good question for the FAQ would be "How do I find out which version of Jetty I am running?".

FAQ page(s) should be broken up into sections, each section getting its own page with multiple questions/answers on each page.
Troubleshooting
Use the Jetty FAQ Section and Jetty FAQ templates. These are just like FAQs only about problems. Troubleshooting can be both a top level tab and a FAQ section pointing to the same content.
Contributors
Use the Jetty Contributor template. The pages contained here won't have a standard format, but the template contains the appropriate categories, etc.

Prerequisites

You must have sufficient edit privileges for the wiki. And make sure you're logged in! We assume that you are familiar with the Mediawiki syntax for formatting text, creating links, etc. If you need a reference, there's a link to "Editing help" at the bottom of each form.

Steps

  1. Decide the title of the page, and the section it should be under.
  2. Create the new page by going to http://wiki.eclipse.org/Jetty/Section/New_Page_Title, then use the Edit link at the left of that page.
  3. Look for an applicable template from the list above. If you can't find a suitable template and must write the page from scratch, use the {{Jetty}} template, which will add the navigation tabs, the infobox at the right, and the Jetty category. The Jetty templates all already include the {{Jetty}} template (and thus, navigation). Even better, though, if it looks like you'll be needing it for more than one document, is to create a new template based on the existing templates
  4. Add any additional categories, by doing [[Category: Category Name]]
  5. Now link to the page from the tab it belongs under.

Tips, Hints, and Warnings

Page headers

The automatically generated title at the top of the page uses h1 (= header text =). You should never use h1 within page content.

Page content section headers should start with h2 (== header text ==), with subsections within using more and more "="s. Sections defined in templates use the h2 header, so if you are using a template and need a subsection within an argument, start from h3. The one exception is the "body" argument, which is a free space which starts with no header; you'll need to start with h2, to keep the sections consistent.

So!

{{Jetty Some Template
|introduction = 
Here is introductory text. This section automatically begins with an <h1>Introduction</h1> header, put in by the template.

=== subheader as h3 ===
more text

|body =
This is the meat of the page, and does not start with a hedaer.

== subheader as h2 ==

== more subheaders ==

=== sub-subheader ===
etc
}}


Tab page organization

On each of the tabs, the top of the page should be a well-structured index of pages, perhaps with some supportive text. This will be manually authored for order and structure.

At the bottom of each tab page, there is a Related Pages section which contains the automatic generated list of pages for the tab, using the category mechanism. If you used a template, that would have added the appropriate categories automatically. Generally, you will not need to do anything special extra to make a page show up under the appropriate "Related Pages" section.

To structure our pages, we are using a combination of URL hierarchy, templates, and categories.

Example, creating the "How to Configure Jetty" page:

  1. Decide the title of the page will be "How to Configure Jetty"; it's a howto, so put it under Jetty/Howto
  2. Go to http://wiki.eclipse.org/Jetty/Howto/Configure_Jetty, click edit
  3. Use the template as follows:
{{Jetty Howto
|introduction=
introduction
|steps=
===Server Configuration===

===Connector Configuration===

===Web Application Configuration===
|examples=

see examples in svn
|more =
link to syntax reference

}}

This gives the page the "Jetty Howto" category automatically, and the page now appears in both sections of the Howto tab.

  1. Edit the Jetty/Howto tab page and add the link

Wiki links

Other templates

There are a few additional templates that are worth taking note of: {{note}}, {{tip}}, {{important}}, {{caution}}, {{warning}}. See them all under the Category: Admonition Templates. Usage is:

{{templatename|title|full contents}}

Syntax coloring

For syntax coloring around blocks of code, use the <source> tag. It requires a lang attribute as well. You'll probably use lang="xml" or lang="java" the most, e.g.,

 <source lang="xml">
   <Configure id="Server" class="org.eclipse.jetty.server.Server">
     ...
   </Configure>
 </source>

CSS

There are several ways you can prettify formatting:

  • To prettify tables, use the "jetty-table" class
  {| class="jetty-table"
   ! header
   |-
   | text
  |}
  • For non-tabular data, where you want a word to the left, and its definition to the right, such as above, use definition lists.
    • wrap it in a <div class="wide-list"> if you want it to stretch across the entire page (also the default)
    • wrap it in a <div class="narrow-list"> if you expect you will not have long content, and don't want it to sprawl across the entire page
    • wrap it in a <div class="unbounded-list"> if you want the alignment, but not the borders
 ; phrase : definition
<div class="wide-list">; phrase : definition</div>, etc
  • If you wish to define additional page-specific CSS, put it in between <css></css> tags.

Categories

All pages using a Jetty template or the {{Jetty}} template have the Jetty category. All pages using a Jetty template also have that template name as an additional default category.

To override the Jetty template's category, add a [[Category:...]] in the "category" argument to the template call. To add an additional category (but keeping the Jetty template's default category), add a [[Category:...]] to the bottom of the page, outside the template.

The category tag looks like this:

[[Category:Jetty How To]]

We add a "Jetty" in the category names so that we can automatically get a list of all pages in a category, and put it on that categories tab/index page. Unfortunately, it doesn't seem possible to show only those pages which have a category of Jetty and Other Category Name.

The category names match the template names which, in turn, have their corresponding tab/section.

Examples

This page is one big example. View the source code of the page (click the Edit button) to see how template usage in action. The Jetty templates also have #Usage sections, which show you the syntax you need to use the templates. But in general, what you should put on a page is:

  {{Jetty Template Name
  | introduction = Paragraphs of introduction. May contain whitespace, wiki formatting, etc, as long as they don't start with a "|"
  | (sectionname) = section text
  | ... (more template-specific sections)
  | more =
  * [[Link 1|Text of link 1]]
  * [[Link 2|Text of link 2]]
  | category = [[Category: Jetty Howto]] [[Category: Some Other Overriding Category]] (optional)
  }}

  [[Category: Additional Category]] (optional)


Additional Resources