 |
 |
| GUIDELINES &S ON TIP LOC SOFTWARE TECHNICAL DOCUMENTATION |
No. 4
Aug 17, 2017 |
Hello
and welcome to edition No. 4 of Quick tips, articles on technical
documentation best practices. This issue takes an in-depth look at the
work.css stylesheet used in the SMS Help files. It's intended to give new
application specialists and developers an in-depth introduction and a
refresher to those already familiar. A quick reference table explaining the
formatting of each style with examples and hints is also available at the
end of the email and as a linked PDF document.
Thank-you and have a great day,
Stefano
Many of you are probably aware of the work.css stylesheet used in the SMS Help documents SMSUsers.chm and SMSMembers.chm. It is a stylesheet that is attached to HTM documents and used to standardize the formatting of help documentation and includes formats such as font type, size and colour, and spacing within lists and procedures. For those of you who may be less familiar read on, others can skip to the end or open the PDF document at Quick_tip_files/work.css_rendered_reference_table.pdf to view the reference table.
Attaching the work.css to your HTM document
The following procedure explains how to attach or link the work.css stylesheet found in either the root folder of the Users documentation or in the root of the Tech and Install folders of the Members documentation, to your HTM document. It is preferable to attach the stylesheet before starting to work on the document to avoid creating .auto-styles (see below). You may attach it afterwards and it will apply the styles to the current content, however if there are .auto-styles in your existing document you may have to delete them to let the styles in the work.css take precendence.
To attach the work.css stylesheet to your HTM document follow the procedure below:
Note: You may also manually insert the line in no. 6 below directly at the top of the HTM file, but to ensure that it will work, the sub-folder references must match the level at which your HTM is placed in the folder tree structure. Following the procedure below ensures the proper sub-folder references.
- Open the HTM doc in Expressions Web.
- Click Format menu, click CSS Styles then click Attach stylesheet...
- In the Attach Style Sheet dialog box click Browse.
- In the Select Style Sheet dialog box browse for the work.css stylesheet for either the Users or Members documentation and click Open.
- Ensure that Attach as has Link selected and Attach to is Current page and click OK.
- A new stylesheet link line appears at the top of
the HTM page as shown below:
<link href="/../../Work.css" rel="stylesheet" type="text/css" />
Note: Depending on where your HTM file is located within the folder tree sturcture of Users or Members there may be more or less sub-folder references in front of the "/Work.css"
.autostyles, where are they from? What do they mean?
During my continuing review of existing LOC documentation I've noticed many HTM documents in which there are various styles included at the top of the HTML code page, that are not part of the standard work.css stylesheet. These are automatically created as .auto-style# if formatting is applied to text or an element that is either NOT part of normal HTML formatting such as Bold <strong>, Italic <i>, Underlined <u>, etc... or is NOT a style in an attached stylesheet, such as the work.css
Formatting such as
Centered text
Indented text
Right justified text or elements
or any number of different applied formats such as font size, colour, style and so forth will create these new .auto-styles at the top of the HTML code in-between <head></head> as shown in the example below:
Now, in many cases it is normal that some .auto-styles are created during the process of writing documentation as the work.css stylesheet cannot possibly contain or account for ALL formatting that may be needed in a document.
However, for the sake of consistency and rigor, all applied styles should ideally come from the work.css.
But, what if the style I need isn't available?
OK, I'm with you, one of the tasks I've set for myself is to analyze the .auto-styles in Users and Members and try and come up with a list of the most common styles that are not included in work.css and then add them to the work.css, and make them available to everyone. An example would be the new .indent# series of styles. This is still very much a work in progress, but I'm chipping away at it.
In the meantime the table at the bottom of this email outlines the
current styles in the work.css, explaining the name of each style class, a
description of the style and what the corresponding rendered HTML looks like.
Feel free to keep this email to use as an easy reference while editing
documentation and searching for the right particular style or open the
convenient PDF at
Quick_tip_files/work.css_rendered_reference_table.pdf.
Applying styles from the work.css to your document
Once the work.css stylesheet is attached to your HTM file, now you must apply the styles to the various elements in the document as needed. There are two methods to apply the styles, one involves using Expression web's built-in Apply style panel and the other is to simply manually modify and insert the styles directly in the HTML code.
Manually applying styles
To apply styles manually, simply insert the word Class followed by an equal sign (=) and the desired style in between quotation marks inside of the element tag. In the example below the paragraph element is given the style p.Note from the work.css stylesheet.
<p class="Note">Note: This is a note</p>
In the example below, the paragraph is given a style "p.Note" and the <span> tag is used to additionally indent the note by 40px.
<p class="Note"><span class="ident4">Note: This text is in the "p.Note" style and is also indented by 40px.</span></p>
Note: The style names ARE case-sensitive
Applying styles using Expression Web
Expression web provides a convenient way to apply styles from the work.css, however keep in mind that in some particular cases the application may not work depending on the layout of the HTM document and other factors. This seems to be a bug in Expression web and will have to be looked at on a case-by-case basis, however in most cases the application of styles works just fine.
To apply styles using Expression web's built-in Apply Style panel follow the steps below:
1.If the Apply styles panel is not open, click Panels menu, then click Apply Styles.
2.In the designer panel place the cursor inside the element to which the style is to be applied.
3.In the Apply Styles panel find and click the desired style.
Note: Only those styles applicable to the current element appear in the Apply Styles panel.
Work.css style reference table
Below is a table displaying all of the styles found in the work.css as of Aug 17, 2017. There is also a convenient PDF version of the table at Quick_tip_files/work.css_rendered_reference_table.pdf.
| CSS Style | Description | Rendered Example | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| body | Pre-defined <body> tag with pre-set left-justified Verdana black font set at 10pts | N/A | |||||||||
| a:link | Anchor link | http://www.google.com | |||||||||
| a:visited | Visited Anchor link (after user has clicked the link) | http://www.google.com | |||||||||
| a:active | Active Anchor link (usually when current page is the link) | http://www.google.com | |||||||||
| a:hover | Anchor hover colour (changes to this when user hovers over link) | http://www.google.com | |||||||||
| .Code | Style class that may be applied to snippets of code shown in an HTM doc. Renders code in Courrier font with a grey background to highlight code snippet. | TFreeStackThread =
class(TThread) |
|||||||||
| p | Standard pre-set paragraph
with left-justified, 9pt black Verdana font with a 15px margin at top and
bottom. |
This is an example of a typical paragraph in an HTM doc using the pre-set <p> style. |
|||||||||
| p.Note | Standard pre-set paragraph
with left-justified, 9pt black, italic Verdana font with a 25px margin at top and
bottom. This style class is used for notes within HTM docs. |
This is an example of a typical paragraph in an HTM doc using the pre-set <p> style. |
|||||||||
| p.List | Standard pre-set paragraph
with left-justified, 9pt black, italic Verdana font with a 10px top margin and a
5px
bottom margin. This style class may be used for listing items within HTM docs. |
This is an example of the p.List style. The font is smaller, has slightly different margin settings and is a good choice for listing items in a condensed manner. | |||||||||
| p.NoteList | Standard pre-set paragraph
with left-justified, 9pt black, italic Verdana font with a 20px top margin and a
5px
bottom margin. This style class may be used for inserting notes within a list of items within HTM docs. |
This is an example of the p.NoteList style. The font is the same as the P.List only set as Italic, has slightly different margin settings and is a good choice for inserting notes within a listing of items in a condensed manner. | |||||||||
| p.Table | Paragraph style for insertion in a table cell. Normally the work.css <p> tag has too much spacing for a table cell and the font size does not match the table setting font size. This modified style reduces the spacing and font-size allowing a <p> to be inserted in a table cell and retain proper alignment and formatting. | This is a regular paragraph, styled using the regular <p> tag. This is a paragraph styled with the p.Table paragraph style. |
|||||||||
| p.Img | This paragraph style is used for image captions as it is a smaller font, with spacing specifically for tucking beneath an image. |
 P.img tag under Landscape image |
|||||||||
| .indent4 | This style can be applied to many elements to indent them by 40px from the left hand margin. | This paragraph is idented by 40px. |
|||||||||
| .indent6 | This style can be applied to many elements to indent them by 60px from the left hand margin. | This paragraph is idented by 60px. |
|||||||||
| .indent8 | This style can be applied to many elements to indent them by 80px from the left hand margin. | This paragraph is idented by 80px. |
|||||||||
| img | Standard img tag pre-set with
the following margins: Top and bottom = 15px Note how the image sits higher than the text. See next style to fix that. |
Some
text |
|||||||||
| img.Text | Img tag style pre-set
with all margins set to 0, this style used to insert images in-line with text. Note how the image now sits level with the text. |
Some
text |
|||||||||
| hr | Standard horizontal rule pre-set with a top margin of 30px. | ||||||||||
| hr.Div | Horizontal rule tag pre-set with a top margin of 30px. | ||||||||||
| h1 | Pre-set heading 1 in blank Verdana 18pt, bold font with 2px top margin and 10px bottom margin. | Heading 1 |
|||||||||
| h2 | Pre-set heading 2 in blank Verdana 12pt, bold font with 35px top margin and 10px bottom margin. | Heading 2 |
|||||||||
| h3 | Pre-set heading 3 in blank Verdana 11pt, bold font with 35px top margin and 5px bottom margin. | Heading 3 |
|||||||||
| h4 | Pre-set heading 4 in blank Verdana 10pt, bold font with 35px top margin and 5px bottom margin. | Heading 4 |
|||||||||
| h5 | Pre-set heading 5 in blank Verdana 9pt, bold font with 35px top margin and 5px bottom margin. | Heading 5 |
|||||||||
| h6 | Pre-set heading 5 in blank
Verdana 8pt, bold font with 5px top margin |
Heading 6 |
|||||||||
| table | Pre-set <table> element with no
borders with 25px top and bottom margins. <th> heading element black background with white font. <tr> table row element <td>cell element td.Img is a style applied to the <td> cell tag and changes the font to 8pt for captioning images. |
|
|||||||||
| th | |||||||||||
| td | |||||||||||
| td.Img | |||||||||||
| ol | Pre-set ordered list tag with 10px top margin and 40px bottom margin |
|
|||||||||
| ul | Pre-set unordered list tag with 10px top margin and 40px bottom margin |
|
|||||||||
| li | Pre-set List tag with black
Verdana 8pt font with a 2px padding |
See examples above. | |||||||||
| li.Steps | This style is applied to the
list tag for steps in procedures and adds a 10px Top margin and 15px bottom
margin top open up the steps for clearer reading. Note: Apply style to the first list element i.e.: <li class="Steps">Click File menu</li> then continue writing procedure, each subsequent <li> added by the Enter key automatically adds the class="Steps" to the <li> tags. |
|
|||||||||
| table.List | Style used to apply a single grey border to a Table tag, may be used as another form of highlight of a list of items within a document. |
|
|||||||||
| th.ListTitle | Style used with list heading tag <th> and changes it to a light grey background with white font and is another method to highlight titles in lists. |
|
|||||||||
| th.List | Another style used with list heading tag <th> and changes it to a black background with white font and is another method to highlight titles in lists. |
|
|||||||||
| td.List | Used in conjuction with the th.List above to create a different type of table, depending on the article, using different table types may indicate different material or emphasis on different information. |
|
|||||||||
| td.ListDark | Another variation on the cell element tag style, this one applies a pale grey background with a dark grey font. |
|
|||||||||
| div.PageBreak | Special style applied to a <div> tag to force a page break after the <div> tag | Example not available. The page break only works when printing HTM documents. Can be used to force certain elements to go to a new page. | |||||||||
| span.spannote | Special style applied to a <span> tag to apply an italic font within an already established paragraph tag <p> | This is a normal paragraph with an embedded <span> with a spannote appled. |
