r31 - 2013-11-22 - 23:40:43 - StevenBeardYou are here: TWiki >  Deployment Web > DeploymentFormattingGuidance

Deployment wiki formatting guidance

Authors: StevenBeard
Build basis: None

The Deployment wiki must have a consistent look and feel across all its sections, subsections, and topics. Always use the standard topic formatting, particularly for the headers, footers, heading styles, and fonts. Some of the formatting relates to specific information that is required on all topic pages.

These guidelines focus on how to create wiki pages and how to complete and format the different sections of wiki pages. For writing guidelines about style issues that relate to clarity and consistency within a wiki page, such as capitalization and spelling, see Deployment wiki writing guidelines.

Deployment wiki topic page template

All new topic pages in the Deployment wiki are created by using the WebTopicEditTemplate. All pages must adhere to this template to maintain the overall look and feel of the wiki.

DO:

  • When you create a topic page, change the placeholder title:
     ---+!! Topic title (use a lowercase style, which is known as "sentence-style" capitalization) 

  • When you create a topic page, set the initial authors:
     %DKGRAY% Authors: Main.TWikiUser, Main.TWikiUser <br> 
    The list of authors should be a comma-separated list, where each author is represented by their TWiki name Main.TwikiUser; for example: Main.StevenBeard

    Note: The name that is displayed in the upper-right and the history of the page is not necessarily a person who made significant contributions to a topic page. A key aim of the wiki is to ensure that authors and additional contributors are recognized for their contribution, both internally to their organization and in the wider community. The authors who are listed in the title banner for a topic page should be the people who have made major contributions to developing the page, regardless of who edited the wiki page. The number of authors should be kept to a reasonable number (4- 10 maximum). If an entire section or sub-section team was instrumental in developing a page, use a link to the respective section or sub-section; for example:
     [[DeploymentPlanningAndDesign][Deployment planning and design team]] 

  • When you create a topic page, set the build basis:
     Build Basis: Products, Editions and Versions as applicable 
    The build basis should either reflect the most specific build basis that is appropriate for the page or be explicitly set to "None."

  • All topic pages must have an initial introduction paragraph or two before the first heading.

  • All topic pages must have a list of related topics, external links, and additional contributors at the bottom of the page, in accordance with the template format.

DO NOT:

  • Do not edit or remove the page contents or margin:
     <!-- Page contents top of page on right hand side in box -->
    <sticky><div style="float:right; border-width:1px; border-style:solid; border-color:#DFDFDF; background-color:#F6F6F6; margin:0 0 15px 15px; padding: 0 15px 0 15px;">
    %TOC{title="Page contents"}%
    </div></sticky>
    
    <sticky><div style="margin:15px;"></sticky> 

  • Do not alter the default heading styles and fonts or paragraph fonts.

  • Do not remove the final line of markup:
     <sticky></div></sticky> 

Topic page status icons

Use these status icons for all topic pages to indicate the page status:

  • todo.png To do: Indicates a new topic page that has not been started. By default, all pages created from the topic page template will include this icon.

  • uc.png Under construction: Indicates that a topic page is being edited or reviewed.

  • new.png New: Indicates that a topic page was recently created and reviewed. Use this icon only for significant new content within the wiki and not for external links. Typically, new icons will be removed after 1-2 months.

  • updated.png Updated: Indicates that a topic page was recently updated and reviewed. This icon can also be used to indicate external content that has been migrated into the wiki, such as Jazz.net articles. Use this status icon for Jazz.net articles or other already externally available content when it is initially migrated into the wiki. Typically, updated icons will be removed after 1-2 months.

  • constantchange.png Constant change: Indicates that a topic page is constantly under change by the wider wiki community.


  • None: If a status icon is not displayed, the topic page is deemed to be in a stable unchanging state.

Add icons before the title in the title box of a topic page:

todo.png Title of the topic page

Authors: StevenBeard
Build basis: None

Note: All topic pages that only technical leaders and senior editors (aka TWikiDeploymentAuthorsGroup) can edit must use the above status icon conventions. All topic pages that deployment practitioners (aka TWikiAuthorsGroup and TWikiExternalAuthorsGroup) can edit must use the above status icon convention where possible. Typically, open community pages will use the constant change icon to denote that they might be under constant change.

Smaller versions of the status icons [todo16.png uc16.png new16.png updated16.png constantchange16.png) can be used in front of navigation links, such as on section pages, to indicate the status of the linked topic page. Note: Avoid using the smaller constant change icon in front of navigation links. It is important that this icon and the one on the topic page are the same; for example:

Personal user profile pages

You can create a personal user profile page that will be linked to from your TWikiUsers name; for example: StevenBeard. Copy the formatting and layout of this example.

General formatting guidelines

Making a comment or a note

To make a comment or to mark something you want to return to, use three number signs: ###. The number signs do not affect the formatting and are easy to spot.

Adding a questions and comment box to a topic

You can add a questions and comments box to a page that has restrictive write access to allow additional TWikiGroups or all Jazz.net users to ask a question or comment. The following example is the best mechanism for adding a questions and comments box that has a writable subtopic to collect the comments. To view the markup of the example, view this topic in Raw View.

Questions and comments:

Note: On the subtopic questions and comments page, you must explicitly set the write access to the correct level. To allow everyone to comment or raise a question, set ALLOWTOPICCHANGE to a blank list:

<!--
   * Set ALLOWTOPICCHANGE = 
-->

To see the correct format and layout, view the DeploymentFormattingGuidanceComments subtopic in Raw View.

Note: In most cases, put the questions and comment box at the bottom of a topic page, below the list of additional authors.

TWiki editing shorthand

Note: Use Edit instead of the WYSIWYG edit because the WYSIWYG editor does not work correctly in all browsers.

Formatting Command What you type What you get
Paragraphs:
Blank lines create paragraphs.
1st paragraph

2nd paragraph

1st paragraph

2nd paragraph

Headings:
Three or more hyphens (-) at the beginning of a line, followed by plus signs (+) and the heading text. One plus sign creates a top level heading; two plus signs create a second level heading, etc. The maximum heading depth is 6.

TIP You can create a table of contents with the %TOC% variable.
TIP To exclude a heading from the TOC, put !! after the ---+.
ALERT! Empty headings are allowed and are not displayed in the table of contents.

---++ Sushi
---+++ Maguro
---+++!! Not in TOC

Sushi

Maguro

Not in TOC

Bold Text:
To make a word bold, enclose it in asterisks (*).
*Bold*

Bold

Italic Text:
To make a word italic, enclose it in underscores (_).
_Italic_

Italic

Bold Italic:
To make a word bold italic, enclose it in double-underscores (__).
__Bold italic__

Bold italic

Fixed Font:
To make a word fixed font, enclose it in equal signs (=).
=Fixed font=

Fixed font

Bold Fixed Font:
To make a word bold fixed font, enclose it in double equal signs ().
==Bold fixed==

Bold fixed

TIP You can follow the closing bold, italic, or other (* _ __ = ==) indicator with normal punctuation, such as commas and full stops.
ALERT! Make sure that no spaces are between the text and the indicators.
ALERT! All words that are enclosed by the indicators must be on the same line.
_This works_,
_this does not _
_this fails
too_

This works,
_this does not _
_this fails too_

Separator (Horizontal Rule):
Place three or more hyphens at the beginning of a line.
-------


Bulleted List:
Type a multiple of three spaces, an asterisk, and another space.
HELP For all list types, you can break a list item over several lines by indenting lines after the first one by at least 3 spaces.
   * level 1
      * level 2
   * back on 1
   * A bullet
     broken over
     three lines
   * last bullet

  • level 1
    • level 2
  • back on 1
  • A bullet broken over three lines
  • last bullet
Icon List:
Type a multiple of three spaces, an asterisk, text icon:name and another space.
HELP Use the name of any TWikiDocGraphics icon.
   * %ICON{tip}% Icon list
      * %ICON{led-red}% Full
      * %ICON{led-green}% OK
   * %ICON{unchecked}% Item 1
   * %ICON{checked}% Item 2
   * %ICON{empty}% No bullet

  • Tip Icon list
    • Led-red Full
    • Led-green OK
  • Unchecked Item 1
  • Checked Item 2
  • Empty No bullet
Numbered List:
Type a multiple of three spaces, a list type character, a period, and another space. Several list types are available besides a number:
Type Generated Style Sample Sequence
1. Arabic numerals 1, 2, 3, 4...
A. Uppercase letters A, B, C, D...
a. Lowercase letters a, b, c, d...
I. Uppercase Roman Numerals I, II, III, IV...
i. Lowercase Roman Numerals i, ii, iii, iv...
   1. Sushi
   1. Dim Sum
   1. Fondue

   A. Sushi
   A. Dim Sum
   A. Fondue

   i. Sushi
   i. Dim Sum
   i. Fondue

  1. Sushi
  2. Dim Sum
  3. Fondue

  1. Sushi
  2. Dim Sum
  3. Fondue

  1. Sushi
  2. Dim Sum
  3. Fondue
Definition List:
Type three spaces, a dollar sign, the term, a colon, and a space, followed by the definition.

Deprecated syntax: Type three spaces, the term with no spaces, a colon, and a space, followed by the definition.

   $ Sushi: Japan
   $ Dim Sum: S.F.

Sushi
Japan
Dim Sum
S.F.
Table:
Each row of the table is a line containing of one or more cells. Each cell starts and ends with a vertical bar (|). Any spaces at the beginning of a line are ignored.
  • | *bold* | header cell with text in asterisks
  • |   center-aligned   | cell with at least two, and an equal number of spaces on either side
  • |      right-aligned | cell with more spaces on the left
  • | 2 colspan || and multi-span columns with multiple |'s right next to each other
  • |^| cell with caret indicating follow-up row of multi-span rows
  • You can split rows over multiple lines by putting a backslash (\) at the end of each line
  • Contents of table cells wrap automatically as determined by the browser
  • To add | characters in tables, use %VBAR% or &#124; .
  • To add ^ characters in tables, use %CARET% or &#94; .
TIP The TablePlugin provides the |^| multiple-span row functionality and additional rendering features
| *L* | *C* | *R* |
| A2 |  B2  |  C2 |
| A3 |  B3  |  C3 |
| multi span |||
| A5-7 |  5  |  5 |
|^| six | six |
|^| seven | seven |
| split\
  | over\
  | 3 lines |
| A9 |  B9  |  C9 |

L C R
A2 B2 C2
A3 B3 C3
multi span
A5-7 5 5
six six
seven seven
split over 3 lines
A9 B9 C9
WikiWord Links:
CapitalizedWordsStuckTogether (or WikiWords) produce a link automatically if they are preceded by a space or parenthesis.
TIP To link to a topic in a different web, type Otherweb.TopicName.
TIP To link to a topic in a subweb, type Otherweb.Subweb.TopicName.
HELP The link label excludes the name of the web; for example, only the topic name is shown. As an exception, the name of the web is shown for the WebHome topic.
ALERT! Dots '.' are used to separate webs and subwebs from topic names and cannot be used in topic names.

Use the TWikiVariables %SYSTEMWEB% and %USERSWEB% instead of TWiki and Main.

WebStatistics

Sandbox.WebNotify

Sandbox.WebHome

Sandbox.Subweb.TopicName

WebStatistics

WebNotify

Sandbox

TopicName

Anchors:
You can define a reference inside a TWiki topic (called an anchor name) and link to that. To define an anchor, type #AnchorName at the beginning of a line. The anchor name must be a WikiWord of no more than 32 characters. To link to an anchor name, use the [[MyTopic#MyAnchor]] syntax. If you want to link within the same topic, you can comit the topic name
[[WikiWord#NotThere]]

[[#MyAnchor][Jump]]

#MyAnchor
To here

WikiWord#NotThere

Jump

To here

External Links:
URLs that start with file, ftp, gopher, http, https, irc, mailto, news, nntp and telnet are linked automatically if they are preceded by a space or parenthesis. External links are indicated by a trailing External-link icon, and open in a new browser tab or window. Link behavior can be set in configure. To prevent links, add an exclamation point (!) as a prefix.
http://twiki.org

https://google.com

!http://escaped-link

http://twiki.org

https://google.com

http://escaped-link

Forced Links:
Use double square brackets to create forced links: To force a link, type [[link]] or [[link][label]]. Use the former example for singleton words and if automatic linking is disabled. Use the latter example to specify a link label other than the link. For the link, you can use internal link references, such as WikiWords, and URLs; for example: http://TWiki.org/.
TIP Anchor names can be added to create a link to a specific place in a document.
TIP To "escape" double square brackets that would otherwise make a link, add an exclamation point as a prefix of the leading left square bracket.
TIP If the SHOWTOPICTITLELINK preferences setting is enabled, the topic title instead of the topic name is shown for [[WikiWord]] links.
[[WikiWord]]

[[WikiWord#TheSyntax]]

[[WikiSyntax][wiki syntax]]

[[http://gnu.org/][GNU]]

[[Singleton]]

escaped:
![[WikiSyntax]]

WikiWord

WikiWord#TheSyntax

wiki syntax

GNU

Singleton

escaped: [[WikiSyntax]]

Topic Title Links:
Use double square brackets and a plus sign to create links with topic title: To show the topic title instead of the topic name, type [[+TopicName]] or [[+Web.TopicName]]. The topic title is defined by the form field named "Title", the topic preferences setting named TITLE, or the topic name if neither exists.
TIP An alternative syntax is [[TopicName][$topictitle]] or [[Web.TopicName][$topictitle]].
[[+BugN1234]]

[[+Bugs.BugN1234]]

[[BugN1234][$topictitle]]

The sky is falling

The sky is falling

The sky is falling

Prevent a Link:
Prevent a WikiWord from being linked by prepending it with an exclamation point.
!SunOS
SunOS
Disable Links:
You can disable automatic linking of WikiWords by surrounding text with <noautolink> and </noautolink> tags.
HELP To turn off all auto-linking, use the NOAUTOLINK preferences setting.
 <noautolink>
 RedHat & SuSE
 </noautolink>

RedHat & SuSE

Mailto Links:
E-mail addresses are linked automatically. To create e-mail links that have more descriptive link text, specify subject lines or message bodies, or omit the e-mail address, you can write [[mailto:user@domain][descriptive text]].
a@b.com

[[mailto:a@b.com]\
[Mail]]

[[mailto:?subject=\
Hi][Hi]]

a@b.com

Mail

Hi

Twitter Links:
@twitter IDs are linked automatically. The link rule is defined by the {Links}{TwitterUrlPattern} configure setting.
@twiki

@twiki

Verbatim Text:
Surround code excerpts and other formatted text with <verbatim> and </verbatim> tags.
TIP The verbatim tag disables HTML code. If you want the HTML code within the tags to be interpreted, use <pre> and </pre> tags instead.
ALERT! Preferences variables (* Set NAME = value) are set within verbatim tags.
<verbatim>
class CatAnimal {
  void purr() {
    <code here>
  }
}
</verbatim>
class CatAnimal {
  void purr() {
    <code here>
  }
}
Literal Text:
TWiki generates HTML code from TWiki shorthand. Experts can surround anything that must be output literally in the HTML code, without the application of TWiki shorthand rules, with <literal>..</literal> tags.
ALERT! Any HTML within literal tags must be well formed; that is, all tags must be properly closed before the end of the literal block.
IDEA! TWiki Variables are expanded within literal blocks.
<literal>
| Not | A | Table |
<literal>
| Not | A | Table |
Protected Text:
Experts can protect text from mangling by WYSIWYG editors by using <sticky>..</sticky> tags. Sticky tags do not affect normal topic display; they are relevant only when content must be protected from a WYSIWYG editor (usually because content is not well-formed HTML, or because it is HTML that a WYSIWYG editor might filter out or modify). Protected content is displayed as plain text in the WYSIWYG editor.
<sticky>
<div>
This div is required
</div>
</sticky>
This div is required

Related topics:

External links:

  • None

Additional contributors: None

Edit | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r31 < r30 < r29 < r28 < r27 | More topic actions
 
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use. Please read the following disclaimer.
Ideas, requests, problems regarding the Deployment wiki? Create a new task in the RTC Deployment wiki project