Page History

This page contains my suggestions on documentation style. I will try to demonstrate my suggestions by writing a document that justifies them. I'm an advocate of learning by example. As Mark Twain said, "Few things are harder to put up with than the annoyance of a good example" (Samuel Langhornne Clemens (1835-1910)).

Pulling content from CVS

A large part of the WebWork 2.2 documentation effort is to make documentation easier to handle in the future. At on the onset of this effort, everyone agreed that pulling as much source code, examples, and documentation from source control would help greatly. As such, we've installed a modified version of the snippet macro in the OpenSymphony wiki.

The standard way to use it is to do the following:

{snippet:id=description|javadoc=true|url=com.opensymphony.xwork.interceptor.LoggingInterceptor}

or

{snippet:id=example|javadoc=true|lang=xml|url=com.opensymphony.xwork.interceptor.LoggingInterceptor}

or

{snippet:id=sitegraph-usage|lang=none|url=webwork/src/java/com/opensymphony/webwork/sitegraph/sitegraph-usage.txt}

Where:

• id is the name of the snippet (*required).
• url is the URL where the snippet can be found (required).
• lang is the language that the code block should be required as. If this snippet is simply text, don't include this parameter and the content will be printed outside of a code block.
• javadoc indicates if the content is within a JavaDoc block. If this is set to true, then the preceeding "* " (asterisk-space) characters will be stripped before printing the content out. Also, the content is assumed to the HTML escaped already and therefore won't be escaped again.

All snippets are marked off by the pattern START SNIPPET: XXX and END SNIPPET: XXX where XXX is the name of the snippet that is assigned in the id attribute of the macro. The URL is typically a location that points to the project's source control contents.

A note about URLs

As you probably noticed in the examples, there are several formats that the URL patterns can be in. A fully-qualified URL is always allowed, though that is often not practical. We've customized the macro to be a bit more intelligent with the URL attribute:

• If the URL appears to be a class, we assume it lives in src/java, convert all the dots (.) to slashes , and then append .java to it.
• If the URL doesn't start with "http", then it is assumed to start with _https://opensymphony.dev.java.net/source/browse/*checkout*/_^{Image Added}, as you saw in the third example.

About Headings

This section refers to: Notation Guide >> Headings.

...