Child pages
  • Tips for writing and formatting documentation

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

...

Wiki Markup
{scrollbar}

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.

...

This document is organized in the following sections:

...



...

When making a reference to any document in the wiki you should point to this autoexported HTML content, avoid pointing directly to Confluence content. If the page you are browsing does not have the Geronimo banner on top then you are not looking at the HTML version.

(tick) Good: http://cwiki.apache.org/geronimo/geronimo-cwiki-documentation-architecture.html

(error) Bad: http://cwiki.apache.org/confluence/display/geronimo/Tips+for+writing+and+formatting+documentation

Tip:
One way to get back to the HTML version of the page you just edited is to navigate to that particular page from http://cwiki.apache.org/geronimo .

Refer to Geronimo cwiki documentation architecture for further details.

...

Use {scrollbar}

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:

...

...

Versions

For versions use:

...

Ultimately v1.0 or v1.1, the lower case "v" always precede the number.

...

For reference to file extensions use:

...

...

...


.zip
.tar
.gz
.gzip
.jar
.war

Make sure to include the "."

...

For command samples, as in a command line window use:

...

The result will look like this:

...

For unformatted, plain text samples use:

...

...

{noformat:borderStyle=solid|title=some_title}
sample text
{noformat}

...

The result will look like this:

...

...

...


sample text

Code formatting

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.

...

...

For XML samples use:

...

...

...


{code:XML|borderStyle=solid|title=some_title}
XML code
{code}

...

The result will look like this:

...

...


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

...

For Java samples use:

...

...


{code:JAVA|borderStyle=solid|title=file_name}
Java Code
{code}

...

The result will look like this:

...

...


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;

// ...

...

For JavaScript samples use:

...

...

The result will look like this:

...

...


    <script language="JavaScript">
        function showBreadcrumbsEllipsis()
        {
            document.getElementById('breadcrumbsEllipsis').style.display = 'none';
            document.getElementById('breadcrumbsExpansion').style.display = 'inline';
        }
    </script>

...

For HTML samples use:

...

...

...


{code:ActionScript|borderStyle=solid|title=file_name}
HTML Code
{code}

...

The result will look like this:

...

...

For SQL samples use:

...

...

The result will look like this:

...

Command samples and results

For command samples and results as a command line screen capture use:

...

...

{noformat:borderStyle=solid}
sample text
{noformat}

...

The result will look like this:

...

...


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

Commands in paragraph

For commands or code within a paragraph use:

...

...

The result will look like this:

...

For special notes to bring reader's attention use the already existing standard macros such as:

...

...

...


{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:

...

...

...


{warning:title=Warning}Warning message goes here.{warning}

The result will look like these:

...

...

Message goes here.

...

...

Info message goes here.

...

...

Tips goe here.

...

...

Warning message goes here.

Spell checking

Currently, Confluence does not provide spell check so you should use the method of your choice to perform spell checking.

...