This page is included in an attempt to provide some standard guidelines for the naming and formatting used in the development of Geronimo's documentation. This will help us all to maintain a consistent look and feel throughout the entire documentation and Geronimo spaces.
First of all, get familiar with Confluence markup, see the Notation Help. You may also find this guide useful.
For comments and/or concern, please join our mailing list and post your inquires there.
This document is organized in the following sections:
Every time you create a new page add at the top the {scrollbar} macro unless that page is (and will remain that way) the only child page of it's parent.
For installation paths use something like this:
No Format |
---|
|
<geronimo_home>/
<sampleApp_home>/
<JBoss_home>/
<WAS_home>/
<WLS_home>/
...
|
For versions use:
No Format |
---|
|
Apache Geronimo v1.0
Apache Geronimo v1.1
Apache Geronimo v1.1.1
JBoss v4
Tomcat v5.5.9
|
Ultimately v1.0 or v1.1, the lower case "v" always precede the number.
For reference to file extensions use:
No Format |
---|
|
.zip
.tar
.gz
.gzip
.jar
.war
|
Make sure to include the "."
To display an image proceed this way:
- Attach the image file first.
- Avoid blank spaces in the file name.
- in a new line reference the image
!file_name.gif!
optionally for flow charts you can use center alignment !file_name.gif|align=center!
.
To create the diagram you could use any presentation software such as OpenOffice (http://www.openoffice.org) and export the slide as JPG and then attach it to the documentation page. THIS IS THE PREFERRED METHOD.
Alternatively you could use the "Add Diagram" option to build one chart online. This option depends on a plugin and uses a web based interface to create the various diagrams. For additional information on this plugin visit:
http://confluence.atlassian.com/display/CONFEXT/Gliffy+Plugin+for+Confluence+-+Diagram+and+draw+in+Confluence
For command samples, as in a command line window use:
No Format |
---|
|
*{{sample command}}*
|
The result will look like this:
sample command
Use a new line when possible.
Unformatted plain text
For unformatted, plain text samples use:
Panel |
---|
|
{noformat:borderStyle=solid|title=some_title} sample text {noformat} |
The result will look like this:
No Format |
---|
borderStyle | solid |
---|
title | some_title |
---|
|
sample text
|
The current version of Confluence supports color coding for XML, Java, JavaScript, HTML, SQL and ActionScript. Here are some examples for those formats likely to be used in Geronimo's doumentation.
Section |
---|
Column |
---|
| No Format |
---|
|
{code:XML|borderStyle=solid|title=some_title}
XML code
{code}
|
The result will look like this: Code Block |
---|
| XML |
---|
| XML |
---|
borderStyle | solid |
---|
title | some_title |
---|
|
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.2">
<environment>
<moduleId>
<groupId>sample.applications</groupId>
<artifactId>SampledApp</artifactId>
<version>2.0</version>
<type>war</type>
</moduleId>
</environment>
<context-root>/sample</context-root>
</web-app>
|
|
Column |
---|
| No Format |
---|
|
{code:JAVA|borderStyle=solid|title=file_name}
Java Code
{code}
|
The result will look like this: Code Block |
---|
| JAVA |
---|
| JAVA |
---|
borderStyle | solid |
---|
title | some_title |
---|
|
package org.apache.geronimo.samples.sampleapp;
import java.awt.Dimension;
import java.awt.Toolkit;
import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
import java.util.Hashtable;
// ...
|
|
Column |
---|
| No Format |
---|
|
{code:JavaScript|borderStyle=solid|title=file_name}
JavaScript code
{code}
|
The result will look like this: Code Block |
---|
| JavaScript |
---|
| JavaScript |
---|
borderStyle | solid |
---|
title | some_title |
---|
|
<script language="JavaScript">
function showBreadcrumbsEllipsis()
{
document.getElementById('breadcrumbsEllipsis').style.display = 'none';
document.getElementById('breadcrumbsExpansion').style.display = 'inline';
}
</script>
|
|
|
Section |
---|
Column |
---|
| No Format |
---|
|
{code:ActionScript|borderStyle=solid|title=file_name}
HTML Code
{code}
|
The result will look like this: Code Block |
---|
| HTML |
---|
| HTML |
---|
borderStyle | solid |
---|
title | some_title |
---|
|
<html>
<head>
<title>Page title</title>
</head>
<body text="#000000" link="#000000" vlink="#666666">
<h1> Some title </h1>
<p> Some text... </p>
....
</body>
</html>
|
|
Column |
---|
| No Format |
---|
|
{code:SQL|borderStyle=solid|title=file_name}
SQL Code
{code}
|
The result will look like this: Code Block |
---|
| SQL |
---|
| SQL |
---|
borderStyle | solid |
---|
title | some_title |
---|
|
CREATE TABLE customer(
CUST_ID VARCHAR(15) PRIMARY KEY,
CUST_NAME VARCHAR(40)
);
INSERT INTO customer(CUST_ID,CUST_NAME) VALUES('12345','Your_Name');
|
|
|
For command samples and results as a command line screen capture use:
Panel |
---|
|
{noformat:borderStyle=solid} sample text {noformat} |
The result will look like this:
No Format |
---|
|
d:\geronimo-jetty6-jee5-2.0-M2>ls -l
total 195
-rwx------+ 1 user None 4114 Jan 27 00:12 DISCLAIMER.txt
-rwx------+ 1 user None 144208 Jan 27 00:12 LICENSE.txt
-rwx------+ 1 user None 31741 Jan 27 00:12 NOTICE.txt
-rwx------+ 1 user None 17697 Jan 27 00:12 RELEASE-NOTES-2.0-M2.TXT
drwx------+ 3 user None 0 Feb 6 09:20 bin
drwx------+ 2 user None 0 Feb 5 14:34 deploy
drwx------+ 3 user None 0 Jan 27 00:12 lib
drwx------+ 48 user None 0 Feb 5 14:36 repository
drwx------+ 2 user None 0 Jan 27 00:12 schema
drwx------+ 10 user None 0 Feb 5 14:34 var
|
For commands or code within a paragraph use:
No Format |
---|
|
sample text in the paragraph {{command}} sample text in the paragraph {{some_java_code}}.
|
The result will look like this:
"sample text in the paragraph command
sample text in the paragraph some_java_code
."
For special notes to bring reader's attention use the already existing standard macros such as:
No Format |
---|
|
{note}Message goes here.{note}
{warning}Warning message goes here.{warning}
{info}Info message goes here.{info}
{tip}Tips goe here.{tip}
|
When necessary, you can also add a title to these boxes, for example:
No Format |
---|
|
{warning:title=Warning}Warning message goes here.{warning}
|
The result will look like these:
Section |
---|
Column |
---|
| Info |
---|
| Info message goes here. |
|
Column |
---|
| Warning |
---|
| Warning message goes here. |
|
|
Currently, Confluence does not provide spell check so you should use the method of your choice to perform spell checking.
Mac OS X users can simply right-click on text areas and select Spelling -> Check Spelling as You Type
.
Firefox 2.0 provides a built-in spell-checking, older versions of Firefox can get a plugin to fill in the gap.