99

99Typicals

Placeholder

This section is used as the start of a chapter, it has a thin line above and an optional side heading

Chapters with only a thin line do not have a heading (the heading is set in the title section — usually level h12), a nominal h6 level (h6 headings do not display) is also given to satisfy HTML validation requirements (sections must contain a heading element).

If a side heading is used, this will have an h2 heading level

99.1

Section

This is a typical section, it will be numbered X.Y.

Sections have an h2 heading level.

99.1.1

Subsection

This is a typical subsection, it will be numbered X.Y.Z.

Subsections have an h3 heading level.

Inline section

This is an inline section, it has no number but does appy emphasis to a distinct section of text

Inline sections have an h4 heading level.

This is an additional section row it follows any section and allows additional sidebars to be used and aligned with the top of the row text.

additional section rows are constructed with <div> elements (rather than <section> elements and consequently do not require a heading).

As many additional section rows can be added as are needed.

99.2

Typicals — Sidebars & lists

This section contains examples of all the standard list features and sidebars that can be applied to text within the website.

This is a numbered list. A numbered list is displayed with numbers in a circle, the list can contain up to 99 entries:

  1. List entry 1

  2. List entry 2

  3. List entry 3

  4. List entry 4

  5. List entry 5

Numbered lists are <ol> (ordered list) elements with class="list-num".

Applying <ol class="list-num" start="5"> will start the numbering at 5 (or any other number that is entered).

An unnumbered list. Each entry is prefixed with a bullet point

  • List entry

  • List entry

  • List entry

  • List entry

  • List entry

Unumbered lists are <ul> elements with class="list-no-num".

Hanging indents are used as notational paragraphs; these are unnumbered lists (<ul> elements) with class="note". These notes are prefixed by the word “Note”, are in italics and are indented e.g:

  • Supernatant is the water in the settling tank that sits above the sediment, this is decanted and returned to the works inlet for treatment.
  • First paragraph with note and hanging indent

Second paragraph without the note inidcator

99.3

Typicals — Links
(internal & external)

Internal links can be to section, tables and figures (in fact any numbered item). This is a link to Figure 99.1

For a link to work with the slow scroll function, the <a> must have a jQuery class of js--sc-fxx.yy where xx.yy is the figure number, the figure itself must have the an <id> with the same number, but without the sc i.e. <div ... id="js--fxx-yy">.

The local jQuery file xx-xx-scroll.js must also have a scroll function added with the relevant class and id.

The red dot at the start of the link indicates that the link has not been tested; the dot appears because the <a> tag has the class utx. This class should be removed once the link is tested and verified (utx stands for untested and does not occur normally in written English — allowing it to be easily searched for in a HTML file).

This is a link to Table 99.1. Tables use the jQuery class of js--sc-txx.yy where xx.yy is the table number, the table itself must have a similar <id> (again without the sc) i.e. <table ... id="js--txx-yy">.

Section links use the waypoint <id> number given to the start of each numbered section. This has the form js--sc-xxyyzz (chapter xx, section yy and subsection zz). The section itself must have the an <id> with the same number, but not the sc i.e. <section ... id="js--xxyyzz">.

This is a link to section 99.1 on this page § 99.1

Linking to a particular section on a different page within the website uses the same <id> reference, no jQuery code is needed for the link, it is a simple html link with a reference § 1.3.

This also works with heading sections, thus: Section 1.

Offsite links are also possible, these are again straight forward html <a> links; this is an offsite link Practical Typography.

Links have two classes, hlink and xref these both place a very light grey background behind the link and cause a lower border to appear on hover. The difference between the two is hlink is in small caps and is generally more noticeable on the web page; it is intended for offsite links and links to other sections. xref maintains the standard text appearance and is an unobtrusive link to figures and tables.

99.4

Typicals — Tables & footnotes

This section contains examples of typical table styles that can be found in the document.

This is a standard table. It has borders at the bottom of each row, a header row and a caption row. Borders can be turned off if requried (see the section 2 row) by adding the .noborder class to the row, e.g. <tr class="noborder">.

Section Name Purpose
1 Introduction This section, an introduction to the website and what it’s for
2 Fairfax WTW
An example document
A worked example showing an extract from a typical engineering document and how it will appear on the website
3 Website fundamentals Explains how the website is structured, how it works and how to use the components of the website
4 A complete set of examples Example pages containing all the individual components of the website for re-use
5 Downloads The entire website (albeit with google fonts) zipped up and ready for download
Appendices Glossary, references and appendices Defines common terms, references to other websites and other useful supporting information
Table 99.1   Document sections (standard)

This is a dense table. It has borders just as the standard table above, but is slightly wider and uses a smaller font size — typically for things like IO tables

Section Name Purpose
1 Introduction This section, an introduction to the website and what it’s for
2 Fairfax WTW
An example document
A worked example showing an extract from a typical engineering document and how it will appear on the website
3 Website fundamentals Explains how the website is structured, how it works and how to use the components of the website
4 A complete set of examples Example pages containing all the individual components of the website for re-use
5 Downloads The entire website (albeit with google fonts) zipped up and ready for download
Appendices Glossary, references and appendices Defines common terms, references to other websites and other useful supporting information
Table 99.2   Document sections (dense)

An incidental table, these are use to add clarifications or additional points (in a similar fashion to sidebars) into the main body of the text.

Incidental Table Heading

Word has a couple of undocumented features; just type =lorem() on a blank line and hit enter to get lorem ipsum padding text (add a number between the brackets to get that many lines of lorem ipsum)..

Word has a couple of undocumented features; just type =lorem() on a blank line and hit enter to get lorem ipsum padding text (add a number between the brackets to get that many lines of lorem ipsum)..

A footnote table. Footnotes†1 are used to reference a particular item in the text and add a clarification or explanation; e.g. explaining an acronym.

†1 Footnotes usually provide additional information or references for particular items in the main body of the text — bibliographical information, clarification etc.

It is possible to combine multiple footnotes†1 in a single table as shown here. Footnotes†2 are indicated using the &dagger; (†) symbol followed by a number (indicating the footnote) in superscript <sup>.

†1 This is the first footnote
†2 This is the second footnote

99.5

Typicals — Basic figures

This section contains examples of typical figure arrangements that can be found throughout the website. These figures are not part of a lightbox arrangement (that is to say, clicking the image will do nothing).

Full width figure. Full width figures occupy a maximum width of 748 px.

Figure 99.1 - Full width image

Figure 99.1   Full width figure

Half width figure. Half width figures occupy a maximum width of 361 px each.

Figure 99.2 - Tall image

Figure 99.2   Tall image

Figure 99.3 - short image

Figure 99.3   short image

One third width figure. One third width figures occupy a maximum width of 232 px each.

Figure 99.4 - short image

Figure 99.4   short image

Figure 99.5 - Tall image

Figure 99.5   Tall image

Figure 99.6 - short image

Figure 99.6   short image

Asymmetric display, ⅓ to ⅔. The first (narrow) image has a maximum width of 232 px, the second (wide) image has a maximum width of 465 px

Figure 99.7 - 1/3 width

Figure 99.7   ⅓ width

Figure 99.8 - 2/3 width

Figure 99.8   ⅔ width

99.6

Typicals — Figures & lightbox

This section contains examples of typical figure arrangements that can be found throughout the website; these figures are all part of a lightbox gallery. That is to say, clicking the image will cause a larger (or even a different) version of the image to appear in front of the page text (this will be greyed out) within a white frame with a caption.

Full width figure. This is the first image in the lightbox.

Figure 99.9 - Fairfax WTW flow diagram

Figure 99.9   Fairfax WTW flow diagram

This is the second image in the lightbox.

Figure 99.10 - Fairfax WTW control system

Figure 99.10   control system

The following three figures are in the lightbox (showing differnt height responses.

Figure 99.11 - short image

Figure 99.11   short image

Figure 99.12 - Tall image

Figure 99.12   Tall image

Figure 99.13 - short image

Figure 99.13   short image

Finally different width images in the lightbox.

Figure 99.14 - Half width

Figure 99.14   Half width

Figure 99.15 - Half width

Figure 99.15   Half width

Figure 99.16 - 1/3 width image

Figure 99.16   ⅓ width

Figure 99.17 - 2/3 width

Figure 99.17   ⅔ width

99.7

Code fragments

The following code fragments are displayed using google-code-prettify; a js plugin that formats code for display on webpages.

This plugin can format various code languages (HTML, CSS, Java Script, C etc.); it does this by applying certain classes to the code section when the website loads.

These classes are formatted to try to reflect the colours used by the Brackets text editor (there are some differences, these are determined by the constraints of the plugin)

Code that is to be displayed must by within a <pre> element and this element must have the class="prettyprint" attribute.

The following are examples of code fragments:

HTML in a standard block with header (filename line) and caption.
The text is formatted in an approximation of the Brackets colour scheme. The background line shadding is done with the prettifylines.css file.

html
    
<nav>                            <!-- TOP NAVIGATION BAR -->
    <div class="top-nav">
        <div class="rg-row">
            <a class="nav-wide" href="#"><span class="top-nav-icon">l</span><span class="top-nav-text">Prev. section</span></a>
            <a class="nav-wide" href="#"><span class="top-nav-icon">u</span><span class="top-nav-text">Prev. chapter</span></a>
            <a class="nav-wide nav-home" href="#"><span class="top-nav-text">Home</span><span class="top-nav-icon">h</span></a>
            <a class="nav-narrow js--sc-top" href="#"><span class="top-nav-icon">t</span><span class="top-nav-text">Top</span></a>
            <a class="nav-narrow" href="#"><span class="top-nav-text">Home</span><span class="top-nav-icon">h</span></a>
            <a class="nav-wide" href="#"><span class="top-nav-text">Next chapter</span><span class="top-nav-icon">d</span></a>
            <a class="nav-wide" href="#"><span class="top-nav-text">Next section</span><span class="top-nav-icon">r</span></a>
        </div>
    </div>
</nav>                            <!-- END OF TOP NAVIGATION -->
                            
Code 99.7.1   Code Fragment — html extract

Code fragment with download link and text wrapping (line 25). Lines that wrap need to be conditioned in the prettifylines.css file:

index.html
<p class="main-text">Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.</p>
            </div>
           
            <div class="side-area">
                <div class="side-box">
                    First side bar entry
                </div>
                <div class="side-box">
                    Second side bar entry
                </div>
                <div class="side-box">
                    Third side bar entry
                </div>
            </div>
           
            <div class="clearfix"></div>
Code 99.7.2   index.html (side area text) a

The next fragment is formatted CSS
Line numbering has been set to start at 10. CSS code has the .pln and .lit classes overwritten by the prettifylines.css file

css
  
.list-num {                     /* TEXT STYLE - Numbered list */
    font-family: "conc-i3-r";
    margin-left: 5rem;
    /* font-feature-settings: 'liga' 1, 'ss01' 0; */
}
.list-num li p {
    font-family: "eqty-ta-r";
    padding-left: 1rem;
    margin-bottom: 0.85rem;
}

.list-no-num {                  /* TEXT STYLE - Un-numbered list */
    font-family: "conc-t3-r";
    margin-left: 5rem;
    list-style: none;
    /* font-feature-settings: 'liga' 1, 'ss01' 0; */
}
.list-no-num li p {
    font-family: "eqty-ta-r";
    padding-left: 1rem;
    margin-bottom: 0.85rem;
}
.list-no-num li:before {        /* prefix the list with a large dot and */
    content: "●"; float: left; /* force the margin to the correct position */
    margin-left: -2rem;
}

.hlink {font-family: "eqty-ca-r"; } /* TEXT STYLE - hyperlink */
.hlink:link,
.hlink:visited{
    background-color: #f8f8f8;
    border-bottom: 1px solid transparent;
    -webkit-transition: background-color 0.2s, border-bottom 0.2s;
    transition: background-color 0.2s, border-bottom 0.2s;
}
.hlink:hover,
.hlink:active { background-color: #f8f8f8; border-bottom: 1px solid #404030; }
                            
Code 99.7.3 — Code Fragment—CSS and forced line numbering)

ANSI C

C
       
#include <stdio.h>
int main() {
    char c;
    printf("Enter a character: ");

    // Reads character input from the user
    scanf("%c", &c);

    // %d displays the integer value of a character
    // %c displays the actual character
    printf("ASCII value of %c = %d", c, c);
    return 0;
}
                            
Code Fragment — ANSI C extract

Fixed height containers can be used to hold code fragments; these containers have both horizontal and vertical scrolling. Fixed height fragments are implemented by adding style="max-height: XXrem" to the <pre> tag; the table below has style="max-height: 5.3rem".

The scroll bars appear automatically as required:

html
    
<nav>                            <!-- TOP NAVIGATION BAR -->
    <div class="top-nav">
        <div class="rg-row">
            <a class="nav-wide" href="#"><span class="top-nav-icon">l</span><span class="top-nav-text">Prev. section</span></a>
            <a class="nav-wide" href="#"><span class="top-nav-icon">u</span><span class="top-nav-text">Prev. chapter</span></a>
            <a class="nav-wide nav-home" href="#"><span class="top-nav-text">Home</span><span class="top-nav-icon">h</span></a>
            <a class="nav-narrow js--sc-top" href="#"><span class="top-nav-icon">t</span><span class="top-nav-text">Top</span></a>
            <a class="nav-narrow" href="#"><span class="top-nav-text">Home</span><span class="top-nav-icon">h</span></a>
            <a class="nav-wide" href="#"><span class="top-nav-text">Next chapter</span><span class="top-nav-icon">d</span></a>
            <a class="nav-wide" href="#"><span class="top-nav-text">Next section</span><span class="top-nav-icon">r</span></a>
        </div>
    </div>
</nav>                            <!-- END OF TOP NAVIGATION -->
                            
Code Fragment (fixed height block) — html extract

Simple code fragments (single line and multiple line) look like the following

Single line:

<div class="top-nav"></div>

Multiple lines:

<div class="top-nav"></div>
<div class="top-nav"></div>
<div class="top-nav"></div>

Inline fragments

An inline fragment: <div class="top-nav"></div> this uses the <code> element instead of the <pre> element.

99.8

Formulae using MathJax

Formulae can be displayed in standard mathematical notation. The formulae are rendered from AsciiMath format to standard notation using MathJax (a Java Script application).

A flexbox arrangement is used to contain each formula. The formula box has a header line (optional), the equation itself, an equation number (optional) and a caption at the bottom (optional). The full arrangement is shown here:

Equation Header
`sum_(i=1)^n i^3=((n(n+1))/2)^2`
(99.1)
Equation caption

Without the header and caption:

`x=(-b +- sqrt(b^2 – 4ac))/(2a)`
(99.2)

Background colouring can be added by applying class .formulae-bkgd to the header and container <div> elements:

Equation Header
`f(a) = 1/(2pii) oint_gamma f(z)/(z-a)dz`
(99.3)
Equation caption

Equations also can be inline: `f(a) = 1/(2pii) oint_gamma f(z)/(z-a)dz`by using <span> elements.

99.9

Text and formats

There are several inline classes that can change the apperance of text within the main body area and in the side bars. The following styles are available:

Class Description
p (section-std) main paragraph, 135 % line spacing and 120 % of point size paragraph spacing
p (aside) Sans serif font set to 85 % of main paragraph point size with 140 % line spacing. Paragraph spacing 120 % of point size
em Uses bold version of font (serif or sans serif) for emphasis
.first-use Applies an italic serif font for emphasis (highlighting the first use of an expression)
.code Applies a blue monospaced font, 85 % of main paragraph point size (used to highlight a section of code)
.menu Indicates a menu selection in Windows or an application
(small caps blue)
.all-caps Converts text to uppercase and applies 1 point letter spacing (generally used to highlight the first words in a chapter)
.serif Applies a serif font, all other properties stay the same
.serif-b Applies a serif BOLD font, all other properties stay the same
.san-serif Applies a sans serif font, all other properties stay the same
.mono Applies a monospace font, all other properties stay the same
.mono Applies a monospace font, all other properties stay the same
.sml-caps-s Applies a small caps serif font, all other properties stay the same
.sml-caps-ns Applies a small caps sans serif font, all other properties stay the same
.red Changes text colour to red for proofing
.notice A large red sans serif font for notification (again used for proofing)
Table 99.3   Text styles

This is all caps, the main text of the paragrah (what you are reading now) is the main paragraph style (p).

First use applies emphasis with italics (if this is used in a sidebar, it will also impose a serif font — italics should not be used with san serif fonts).

Code highlights are indicated with the code class. Emphasis is given in bold with the <em> tag.

Other styles that can be applied to main paragraphs are: small caps serif, small caps sans, standard sans serif and , monospaced.

Any text can also be highlighted in red.

And this is notice text.

Special paragraph breaks, like the one above can be added; these are a graphical object (a flourish) and are used to definitively separate two sections of text without the need of adding section numbering.

It is just an empty <div> with class="flourish".

The end mark below (the Yorkshire rose with two flourishes) is used to mark the end of the page. It also applies some whitespace and a bottom grey border to finish the page prior to the footer. It is an empthy <div> with class="section-last".

99.10

Git VCS styles

There are several central and sidebar styles associated with the Git version control system (VCS). Examples of these styles are given in this section.

We do this by initialising the repository. The blue colour is achieved with the class .git-cmd.

$ git config --global mergetool.p4merge.path "C:/Program Files/Perforce/p4merge.exe"

Exactly the same class can be used in the sidebar and in figure and table captions.

The Git VCS site uses red text in incidental tables, the san-serif is class .git-cmd. The red serif text is.git-incid.

The .git folder—a golden rule

The .git folder is a hidden folder in the root directory of the repository. It contains all that is important: the local repository, any staged files, all the metadata associated with the repository (change records, logs &c.) and all the important bits for a tracked project.

There is one golden rule concerning the .git folder
DON’T MESS WITH IT

Best thing is, don’t even look inside it. If you delete it, you delete everything,
if you change it, everything gets screwed up





End flourish image
ga('set', 'anonymizeIp', true); // anonymise ip address