Skip to main content
Jump to: navigation, search

Difference between revisions of "Jetty/Contributor/Editing the Wiki"

Line 52: Line 52:
 
* If you wish to define additional page-specific CSS, put it in between <css></css> tags.
 
* 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 <nowiki>{{Jetty}}</nowiki> 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 <nowiki>[[Category:...]]</nowiki> in the "category" argument to the template call. To add an additional category (but keeping the Jetty template's default category), add a <nowiki>[[Category:...]]</nowiki> 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 =  
 
| examples =  
Line 63: Line 75:
 
   * <nowiki>[[Link 1|Text of link 1]]</nowiki>
 
   * <nowiki>[[Link 1|Text of link 1]]</nowiki>
 
   * <nowiki>[[Link 2|Text of link 1]]</nowiki>
 
   * <nowiki>[[Link 2|Text of link 1]]</nowiki>
 +
  | category = [[Category: Jetty How To|{{{SUBPAGENAME}}}]] [[[Category: Some other overriding Category|{{{SUBPAGENAME}}}
 
   }}
 
   }}
  
   [[Category: How To]]
+
   [[Category: Additional Category|{{{SUBPAGENAME}}}]]
  [[Category: Meta]]
+
 
</pre>
 
</pre>
  
 
+
| category = [[Category:Jetty Project|{{{SUBPAGENAME}}}]]
 
}}
 
}}
  
<!-- any additional categories that should apply to this page: (all pages using a Jetty template or the <nowiki>{{Jetty}}</nowiki> template have the Jetty category.
+
<!-- any additional categories that should apply to this page
 
[[Category: Jetty]]
 
[[Category: Jetty]]
 
-->
 
-->

Revision as of 01:33, 23 June 2009



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
Entries should use the How To template. This list should be kept very short, and reference only the important getting started subjects: downloading, installing, running, upgrading.
Features
Use the 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
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 How To template. 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
These are detailed single subject pages, e.g., configuration formats, session configuration. etc.

A reference will always be one reference per page.
FAQ
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
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.

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]]

Tips, Hints, and Warnings

Other templates

There are a few additional templates that are worth taking note of:

{{note}} 
a panel that can be used to highlight a section to the reader
{{warn}} 
a panel that can be used to warn the reader of something important
{{BlueBox}} 
a blue box (actually, maybe only use this on the index pages?)

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:

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 1]]
  | category = [[Category: Jetty How To|{{{SUBPAGENAME}}}]] [[[Category: Some other overriding Category|{{{SUBPAGENAME}}}
  }}

  [[Category: Additional Category|{{{SUBPAGENAME}}}]]

Back to the top