Skip to main content
Jump to: navigation, search

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

 
(32 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
<!-- page template -->
 
<!-- page template -->
{{Jetty How To
+
{{Jetty Howto
 
| introduction = The Jetty Wiki structure is organized into sections, one tab for each section. The sections are described in [[Jetty|the Jetty wiki index]]. For adding pages to each tab, use the following guidelines:
 
| introduction = The Jetty Wiki structure is organized into sections, one tab for each section. The sections are described in [[Jetty|the Jetty wiki index]]. For adding pages to each tab, use the following guidelines:
 
; Getting Started
 
; Getting Started
: Entries should use the [[Template:Jetty How Tos|How To]] template. This list should be kept very short, and reference only the important getting started subjects: downloading, installing, running, upgrading.
+
: Use the [[Template:Jetty Starting|Jetty Starting]] template. This list should be kept very short, and reference only the important getting started subjects: downloading, installing, running, upgrading.
 
; Features
 
; Features
: Use the [[Template:Jetty Feature Guide|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 [[Jetty/How Tos|howtos]] and/or [[Jetty/References|references]]. <br /><br />A feature will always be one feature per page.
+
: Use the [[Template:Jetty Feature|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 [[Jetty/Howto|howtos]] and/or [[Jetty/Reference|references]]. <br /><br />A feature will always be one feature per page.
 
; Tutorials
 
; 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. <br /><br />A tutorial may be multiple pages.
+
: Use the [[Template: Jetty Tutorial| 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. <br /><br />A tutorial may be multiple pages.
 
; Howtos
 
; Howtos
: Use the [[Template:Jetty How Tos|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 [[Jetty/References|reference]] pages. <br /><br />A howto will always be one howto per page.
+
: Use the [[Template:Jetty Howto|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: <nowiki>[[Jetty/Howto/Configure Jetty|How to Configure Jetty]]</nowiki>: [[Jetty/Howto/Configure Jetty|How to Configure Jetty]]<br /><br />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 [[Jetty/References|reference]] pages. <br /><br />A howto will always be one howto per page.
 
; References
 
; References
: These are detailed single subject pages, e.g., configuration formats, session configuration. etc. <br /><br />A reference will always be one reference per page.
+
: Use the [[Template:Jetty Reference|Jetty Reference]] template. These are detailed single subject pages, e.g., configuration formats, session configuration. etc. <br /><br />A reference will always be one reference per page.
 
; FAQ
 
; FAQ
: These are like chatty indexes into [[Jetty/How Tos|howtos]] and [[Jetty/References|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. <br /><br />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?". <br /><br />FAQ page(s) should be broken up into sections, each section getting its own page with multiple questions/answers on each page.
+
: Use the [[Template:Jetty FAQ Section|Jetty FAQ Section]] and [[Template:Jetty FAQ|Jetty FAQ]] templates. These are like chatty indexes into [[Jetty/Howto|howtos]] and [[Jetty/Reference|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. <br /><br />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?". <br /><br />FAQ page(s) should be broken up into sections, each section getting its own page with multiple questions/answers on each page.
 
; Troubleshooting
 
; 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.
+
: Use the [[Template:Jetty FAQ Section|Jetty FAQ Section]] and [[Template:Jetty FAQ|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 [[Template:Jetty Contributor|Jetty Contributor]] template. The pages contained here won't have a standard format, but the template contains the appropriate categories, etc.
  
 
| prereqs = 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.
 
| prereqs = 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 =  
 
| steps =  
 
# Decide the title of the page, and the section it should be under.  
 
# Decide the title of the page, and the section it should be under.  
Line 23: Line 26:
 
# 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 <nowiki>{{Jetty}}</nowiki> template, which will add the navigation tabs, the infobox at the right, and the [[:Category:Jetty|Jetty category]]. The Jetty templates all already include the <nowiki>{{Jetty}}</nowiki> 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
 
# 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 <nowiki>{{Jetty}}</nowiki> template, which will add the navigation tabs, the infobox at the right, and the [[:Category:Jetty|Jetty category]]. The Jetty templates all already include the <nowiki>{{Jetty}}</nowiki> 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
 
# Add any additional categories, by doing <nowiki>[[Category: Category Name]]</nowiki>
 
# Add any additional categories, by doing <nowiki>[[Category: Category Name]]</nowiki>
 
+
# Now link to the page from the tab it belongs under.
 
| notes =
 
| notes =
 +
=== Page headers ===
 +
 +
The automatically generated title at the top of the page uses h1 (<nowiki>= header text =</nowiki>). You should never use h1 within page content.
 +
 +
Page content section headers should start with h2 (<nowiki>== header text ==</nowiki>), 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!
 +
 +
<pre>
 +
{{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
 +
}}
 +
</pre>
 +
 +
 +
=== 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:
 +
 +
# Decide the title of the page will be "How to Configure Jetty"; it's a howto, so put it under [[Jetty/Howto]]
 +
# Go to http://wiki.eclipse.org/Jetty/Howto/Configure_Jetty, click edit
 +
# Use the template as follows:
 +
<pre>
 +
{{Jetty Howto
 +
|introduction=
 +
introduction
 +
|steps=
 +
===Server Configuration===
 +
 +
===Connector Configuration===
 +
 +
===Web Application Configuration===
 +
|examples=
 +
 +
see examples in svn
 +
|more =
 +
link to syntax reference
 +
 +
}}
 +
</pre>
 +
 +
This gives the page the "Jetty Howto" category automatically, and the page now appears in both sections of the Howto tab.
 +
 +
# Edit the [[Jetty/Howto]] tab page and add the link
 +
 +
=== Wiki links ===
 +
* <nowiki>[[/Relative to Current Page]]</nowiki> : [[/Relative to Current Page]]
 +
* <nowiki>[[/Relative to Current Page noslash|Relative to Current Page noslash]]</nowiki> : [[/Relative to Current Page noslash|Relative to Current Page noslash]]
 +
* <nowiki>[[Jetty/Absolute Path]]</nowiki> : [[Jetty/Absolute Path]]
 +
* <nowiki>[[Jetty/Absolute Path|Any Text]]</nowiki> : [[Jetty/Absolute Path|Any Text]]
 +
* <nowiki>[http://www.eclipse.org/jetty Jetty@eclipse]</nowiki> : [http://www.eclipse.org/jetty Jetty@eclipse]
 +
 
=== Other templates ===
 
=== Other templates ===
There are a few additional templates that are worth taking note of:
+
There are a few additional templates that are worth taking note of: [[Template:Note|<nowiki>{{note}}</nowiki>]], [[Template:Tip|<nowiki>{{tip}}</nowiki>]], [[Template:Important|<nowiki>{{important}}</nowiki>]], [[Template:Caution|<nowiki>{{caution}}</nowiki>]], [[Template:Warning|<nowiki>{{warning}}</nowiki>]]. See them all under the [[:Category: Admonition Templates]]. Usage is:
; [[Template:Note|<nowiki>{{note}}</nowiki>]] : a panel that can be used to highlight a section to the reader
+
 
; [[Template:Warn|<nowiki>{{warn}}</nowiki>]] : a panel that can be used to warn the reader of something important
+
<nowiki>{{templatename|title|full contents}}</nowiki>
; [[Template:BlueBox|<nowiki>{{BlueBox}}</nowiki>]] : a blue box (actually, maybe only use this on the index pages?)
+
 
 +
=== Syntax coloring ===
 +
 
 +
For syntax coloring around blocks of code, use the <code>&lt;source&gt;</code> tag. It requires a <code>lang</code> attribute as well. You'll probably use lang="xml" or lang="java" the most, e.g.,
 +
 
 +
  &lt;source lang="xml">
 +
    <Configure id="Server" class="org.eclipse.jetty.server.Server">
 +
      ...
 +
    </Configure>
 +
  &lt;/source>
  
 
=== CSS ===
 
=== CSS ===
Line 52: Line 135:
 
* If you wish to define additional page-specific CSS, put it in between &lt;css&gt;&lt;/css&gt; tags.
 
* If you wish to define additional page-specific CSS, put it in between &lt;css&gt;&lt;/css&gt; 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:
 +
 +
<nowiki>[[Category:Jetty How To]]</nowiki>
 +
 +
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 61: Line 156:
 
   | ... (more template-specific sections)
 
   | ... (more template-specific sections)
 
   | more =
 
   | more =
   * <nowiki>[[Link 1|Text of link 1]]</nowiki>
+
   * [[Link 1|Text of link 1]]
   * <nowiki>[[Link 2|Text of link 1]]</nowiki>
+
   * [[Link 2|Text of link 2]]
 +
  | category = [[Category: Jetty Howto]] [[Category: Some Other Overriding Category]] (optional)
 
   }}
 
   }}
  
   [[Category: How To]]
+
   [[Category: Additional Category]] (optional)
  [[Category: Meta]]
+
 
</pre>
 
</pre>
  
 
+
| category = [[Category:Jetty Project]]
 +
| more =
 +
* [[:Category: Jetty Template|A full list of available Jetty templates]]
 
}}
 
}}
  
<!-- 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 Contributor]]
-->
+
 
+
[[Category: {{BASEPAGENAME}}]]
+

Latest revision as of 04:28, 12 August 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
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

Copyright © Eclipse Foundation, Inc. All Rights Reserved.