FS
Documentation

Style Guide

This page was last modified 06:40, 6 August 2007.

From Documentation

(Difference between revisions)
Jump to: navigation, search
Revision as of 01:09, 4 October 2006
Daniels (Talk | contribs)
(Font Styles)
← Previous diff
Current revision
Daniels (Talk | contribs)
(Code Blocks)
Line 5: Line 5:
We have identified several different font requirements from the hardcopy manuals. Examples below are from actual manual text. We have identified several different font requirements from the hardcopy manuals. Examples below are from actual manual text.
-* Inline code snippets+=== Command Line Input ===
-** +==== Inline ====
-* Code segments+The default inline code style can be called using <nowiki>{{icode|<code>}}</nowiki>.
-* Filenames and path information+ 
-** Download the distribution file to /tmp on the target host.+This results in {{icode|cd ~cosmos}}
-* Menu navigation+ 
-** Select Application > Install.+==== Code Blocks ====
-* Field and button names+Check your environment by running env from a duty3G shell:
-* Variable data+ 
 +<nowiki>
 +{{code|
 +$ cos duty -c ksh
 +duty: env &#124; pg
 +}}</nowiki>
 + 
 + 
 +{{code|$ cos duty -c ksh
 + 
 +duty: env &#124; pg}}
 + 
 +{{note|The Pipe character {{icode|&#124;}} cannot be used in a code snippet called via a template. The HTML entity code of {{icode|&amp;#124;}} must be used instead}}
 + 
 + 
 +<sub>Please note the above example is stripped of line breaks, due to ignoring wiki markup. Line breaks will be inserted in standard code</sub>
 + 
 +=== Filenames ===
 +Download the distribution file to <tt>/tmp</tt> on the target host.
 + 
 +<nowiki>Download the distribution file to <tt>/tmp</tt> on the target host.</nowiki>
 + 
 +=== COSmanager Navigation ===
 + 
 +Select <cite>Application &gt; Install</cite>
 + 
 +<nowiki>Select <cite>Application &gt; Install</cite></nowiki>
 + 
 +=== Field Names ===
 +change <em>Schedule name</em> to "<var>Daily - except Thursday Friday</var>"
 + 
 +<nowiki>change <em>Schedule name</em> to "<var>Daily - except Thursday Friday</var>"</nowiki>
 + 
 +=== Buttons ===
 +To make the newly installed duty3G the default version press <big>Accept</big>, then press <big>Continue</big>.
 + 
 +<nowiki>To make the newly installed duty3G the default version press <big>Accept</big>, then press <big>Continue</big>.</nowiki>
 + 
 +=== Variable Data ===
 +Run FSinstall: <code>./FSinstall ./<var>&lt;file&gt;</var></code>
 + 
 +<nowiki>Run FSinstall: <code>./FSinstall ./<var>&lt;file&gt;</var></code></nowiki>
 + 
 +<var>Filename</var>: Enter a file name
 + 
 +<nowiki><var>Filename</var>: Enter a file name</nowiki>
 + 
 +=== Other Object Data ===
 +Two new audit trails are created: <small>duty_log</small> and <small>duty_compl</small>.
 + 
 +<nowiki>Two new audit trails are created: <small>duty_log</small> and <small>duty_compl</small>.</nowiki>
== Product Links == == Product Links ==
Line 61: Line 111:
=== Cautions, Notes, Tips === === Cautions, Notes, Tips ===
-Currently, cautions, notes and tips look like:+Cautions, Notes, Code and Tips should be added using MediaWiki Templates. Templates are called using <nowiki>{{ and }}</nowiki> structures.
- +
----- +
-;Note: This is a note, of some description +
-----+
- +
-This look is achieved using the following code:+
-<nowiki>----</nowiki><br />+<nowiki>{{caution!|This is a caution!}}</nowiki>
-<nowiki>;Note:</nowiki> This is a note, of some description<br />+Will result in:
-<nowiki>----</nowiki><br />+{{caution|This is a caution!}}
-Obviously, change the text to suit your needs. +Likewise,
 +<nowiki>{{note|this is a note}}</nowiki>
 +Will turn into
 +{{note|this is a note}}
-The wiki code of four dashes in a rown (----) is translated to an html Horizontal Rule element.+<nowiki>{{code|this is code, or a code snippet}}</nowiki>
 +{{code|this is code, or a code snippet}}
-The Semi-colon/colon notation is actually a definition list, with the semi-colon representing the Definition term (html element DT) and the text after the colon representing the Definition definition (html element DD).+<nowiki>{{tip|this is a tip}}</nowiki>
 +{{tip|this is a tip}}

Current revision

This is the style guide for formatting text for the Functional Software online Documentation.

Contents

Font Styles

We have identified several different font requirements from the hardcopy manuals. Examples below are from actual manual text.

Command Line Input

Inline

The default inline code style can be called using {{icode|<code>}}.

This results in image:openquote.jpg cd ~cosmos image:closequote.jpg

Code Blocks

Check your environment by running env from a duty3G shell:

{{code| $ cos duty -c ksh duty: env | pg }}


code $ cos duty -c ksh

duty: env | pg


Note
Note
The Pipe character image:openquote.jpg | image:closequote.jpg cannot be used in a code snippet called via a template. The HTML entity code of image:openquote.jpg &#124; image:closequote.jpg must be used instead


Please note the above example is stripped of line breaks, due to ignoring wiki markup. Line breaks will be inserted in standard code

Filenames

Download the distribution file to /tmp on the target host.

Download the distribution file to <tt>/tmp</tt> on the target host.

COSmanager Navigation

Select Application > Install

Select <cite>Application > Install</cite>

Field Names

change Schedule name to "Daily - except Thursday Friday"

change <em>Schedule name</em> to "<var>Daily - except Thursday Friday</var>"

Buttons

To make the newly installed duty3G the default version press Accept, then press Continue.

To make the newly installed duty3G the default version press <big>Accept</big>, then press <big>Continue</big>.

Variable Data

Run FSinstall: ./FSinstall ./<file>

Run FSinstall: <code>./FSinstall ./<var><file></var></code>

Filename: Enter a file name

<var>Filename</var>: Enter a file name

Other Object Data

Two new audit trails are created: duty_log and duty_compl.

Two new audit trails are created: <small>duty_log</small> and <small>duty_compl</small>.

Product Links


How To

  1. To create a link to a main document level, simply use "[[product3G]]"
  2. To link to a sub-section of a document, use "[[product3G/subPage | product3G Subpage]]"
  3. To link to a specific part of a document, use "[[product3G/subPage#sectionName | Section Name]]"

Examples

  1. [[COSmanager]] = COSmanager
  2. [[COSmanager/User_Guide/Appendices | COSmanager User Guide Appendices]] = COSmanager User Guide Appendices
  3. [[COSmanager/User_Guide/Appendices#Appendix_A_.E2.80.94_the_COSmanager_User_Interface| Appendix A—the COSmanager User Interface]] = Appendix A—the COSmanager User Interface

Documentation Styles

Inserting Images

Most of the images in the hard documentation are labelled and referred to in the text, for illustration. MediaWiki provides a mechanism for the insertion of a caption alongside an image.

Images are added to the Wiki using the Special Actions > Upload File menu on the far left. Once uploaded to the server, images can be referenced in the page using:

[[Image:imageName.extension|options|Alt Text or Caption]]

Options may be added in any order, pipe separated. Any unknown option will be interpreted as Alternate Image text, and multiple unknown entries will favour the later ones. That is, if there are three unknown options in the declaration, the third one is the one that will be used as the Alt text for the image.

Available options are:

left|right|center|none
Each of these are exclusive of the others. The one appearing latest in the declaration is the one that will be used.
left
image is left aligned, and text is floated to the right
right
image is right aligned and text is floated to the left
center
image is center aligned, and text wraps at the bottom of the image
none
image is left aligned, and text appears underneath the image.
sizepx
if your image is particularly large, you can use this to shrink the width of the image. This will keep the original scale of the image. Note that this actually generates a new image, rather than resizing the display of the original.
thumb
this will generate a thumbnail at a reasonable size (if no specific size is specified). It will also put the image into a frame, and make the caption appear. If no position is given, it will default to "right". A resize image icon will also be shown next to the caption
frame
this will place the image in a bordered box, with the Alt text as a caption below. This will not resize the image. If no position data is given, it will default to "right".

If none of the options are present (alt text and sizepx are allowed), the image will be displayed inline. All other scenarios result in the image being displayed as a block level element.

Also note, there is no call to use both thumb and frame, but they will not necessarily be cancelled out.

Cautions, Notes, Tips

Cautions, Notes, Code and Tips should be added using MediaWiki Templates. Templates are called using {{ and }} structures.

{{caution!|This is a caution!}} Will result in:

Caution
Caution!
This is a caution!

Likewise, {{note|this is a note}} Will turn into

Note
Note
this is a note

{{code|this is code, or a code snippet}}

code this is code, or a code snippet

{{tip|this is a tip}}

Tip
Here's a Tip:
this is a tip