THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
- Use as few words as possible. Instead of "but there are some quirks about it" try "but there are quirks".
- If a list of items includes both a term and an explanation, consider using a table instead of bullets.
- Avoid using "This" by itself. Instead of "This lets us" try "This strategy lets us".
- Ask yourself: "This what?"
- References to other wiki pages can be unqualified. Instead of "See Documentation Style Guide page", try For example: "See Documentation Style Guide."
...
FIXME | A page that mentions a problem in the distribution that we intend to fix. Review these pages before tagging a distribution to see if the issue has been resolved. |
|---|---|
TODO | A page that is incomplete. Try to complete these pages before tagging a distribution |
Shortcuts Links
The Shortcut Link feature should be used for any external reference that may be used elsewhere.
Shortcuts being used include
Shortcut | Purpose | Usage | Result |
|---|---|---|---|
primer | A bookmark in our Key Technologies Primer | s2jira[javabeans@primer] | |
jira | A ticket in our issue tracker | [WW-2111@jira] | |
s2plugins | S2 Plugin Repository | [tiles-plugin.html@s2plugins] | |
s2site | The Struts 2 website |
xwork/api | A class in the XWork Javadocs |
|---|---|
java/api | A class in the Java Javadocs |
wiki/help | A topic the Confluence help system |
Please add new shortcuts as needed.
About Headings
| Wiki Markup |
|---|
(i) This section refers to: \[Notation Guide >> Headings|section=headings@wiki\]. |
[docs/home.html@s2site] |
About Headings
This section refers to: Notation Guide >> Headings.
About About h1
Don't use h1. at the top of each page. The page title serves as the "top level header". This is not as obvious online, but it is very apparent when the documentation is exported to HTML or PDF.
...
More on Text Effects
This section refers to: Notation Guide >> Text Effects.
Text effects like strong, emphasis, and inserted can be used in the usual way to denote important parts of a sentence.
...
Text Breaks
This section refers to: Notation Guide >> Text Breaks.
Text breaks should not be used to format blocks on the screen. If there is an issue with the way paragraphs or headings are being rendered, we should customize the stylesheet.
Lists
This section refers to: Notation Guide >> Lists.
Unordered lists should be created only with the * (star) notation.
...
Images
This section refers to: Notation Guide >> Images and Notation Guide >> Misc.
Avoid using external images for bullets or icons. Prefer the equivalents provided with Confluence.
...
Always observe copyright issues. Do not annex images unless it an original or public domain work, or the author has donated the image to the foundation.
Example: 
Icons
Use , 
, 
, and 
to bullet important one-liners. Use 
to highlight cross references.
...
Tables
This section refers to: Notation Guide >> Tables.
Prefer lists for single-value entries. Prefer tables for lists with multiple columns.
...
Advanced Formatting
This section refers to: Notation Guide >> Advanced Formatting.
Panels should be used as needed. Try to select the right panel for the content.
...
The "holy grail" of technical documentation is single sourcing. One way we try to single-source documentation is to pull content directly from the Javadocs and source code into the documentation.
Using a snippet macro, we are able to tag portions of the Javadocs and source code any file for reuse. The macro fetches those snippets from the a repository and merges the content into the documentation.
| Tip | ||
|---|---|---|
| ||
Before writing any new content, ask yourself if we could place the content in the repository in either one of the example applications or the Javadocs. Rather than contrive an example, can you pull a snippet from one of the applications? Rather than reiterate Javadoc, could we update the Javadoc and make it a snippet? |
- Javadoc
- {snippet:id=javadoc|javadoc=true|url=org.apache.struts2.components.If}
- Tag Attributes
- {snippet:id=tagattributes|javadoc=false|url=struts2/docs/tags/If.html}
...
It is preferable to use snippets from the Struts example apps over Javadoc snippets for anything except plain text content as this ensures that the content's syntax has been validated. |
Example snippet usage
| Code Block | ||||
|---|---|---|---|---|
| ||||
{snippet:id=example|lang=xml|javadoc=true|url=struts2/core/src/main/java/org/apache/struts2/components/If.java} |
| Snippet Attributes | ||
|---|---|---|---|
id | The name of the snippet (required). optional - defaults to "all", meaning the entire file). | ||
url url | The URL where the snippet can be found (required). | ||
linenumbers | If true line numbers are displayed. Numbering always starts at 1. | ||
lang | lang=java would surround the snippet with {code:java}snippet{code} | lang | The language that the code block. If this snippet is simply text, don't include this parameter and the content will be printed outside of a code block. |
javadoc | If true, the content is within a Javadoc block. If this is set to true, then the preceeding "* " (asterisk-space) characters will be stripped before merging the content. Also, the content is assumed to be already HTML escaped and 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. |
About URLs
As you probably noticed in the examples, there are several formats for URL patterns. 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.
...
A URL must start with a valid prefix. There are two types of prefixes:
- com.opensymphony.xwork2. Notice the period. This syntax is better when you want to include content from a class because they allow you to use the fully qualified classname as the URL.
- struts2/ Notice the trailing slash. This syntax better when you want to include content content from non-class files such as xml or properties files. They may also be needed if a class based prefix for a sub-project has not be setup.
To include a snippet from http://svn.apache.org/repos/asf/struts/struts2/trunk/apps/showcase/src/main/java/org/apache/struts2/showcase/DateAction.java the two possible methods are:
| Code Block |
|---|
{snippet:lang=java|url=struts2/apps/showcase/src/main/java/org/apache/struts2/showcase/DateAction.java}
{snippet:lang=java|url=struts2/apps.showcase.src.main.java.org.apache.struts2.showcase.DateAction}
|
To include a snippet from https://svn.apache.org/repos/asf/struts/struts2/trunk/xwork-core/src/main/java/com/opensymphony/xwork2/validator/validators/StringLengthFieldValidator.java the two possible methods are:
| Code Block |
|---|
{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator.validators.StringLengthFieldValidator}
{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator/validators/StringLengthFieldValidator.java}
|
The list of available prefixes:
...
About snippet markers
When possible, all snippet markers should be in comment blocks. How they are commented depends on where the snippet is being embedded.
...
If the snippet is embedded in Javadocs, within Javadoc comments use HTML comments to declare the snippet as they won't render in the Javadocs. For XML examples in Javadocs can be tricky. (See Timer Interceptor for an example.). Javadocs want to use the <pre> tag, but you don't want that tag in the snipped content.in the Javadocs.
When using the <pre> tag within Javadoc comments One technique is to embed the snippet markers inside the <pre> tag.
| Code Block | ||||
|---|---|---|---|---|
| ||||
* <pre> * <!-- START SNIPPET: example --> * <!-- records only the action's execution time --> * <action name="someAction" class="com.examples.SomeAction"> * <interceptor-ref name="completeStack"/> * <interceptor-ref name="timer"/> * <result name="success">good_result.ftl</result> * </action> * <!-- END SNIPPET: example --> |
...
* </pre>
|
A <pre> tag within a Javadoc comment would be escaped and rendered as part of the snippet. See TimerInterceptor.java for an complete example.