Big updates to readme

README.md

@@ -49,7 +49,8 @@ and general working:
 -   The hyperref package is automatically included in the base dec.cls
     file. Please use hyperlinks and hyperrefs within the document to
     link to sections, figures and tables where they are mentioned in the
-    text. Also please use the \
+    text (see below for helper functions for these). Also please use the
+    \
     `pdf{...} ` command to wrap any references to other DEC documents.
     This just creates a href to a PDF document in the same directory at
     the moment though that may be subject to change in the future.
@@ -78,6 +79,123 @@ information and can collaborate more seamlessly. Some bleed of
 paragraphs from page to page is fine, but tables, figures, and sections
 should be on the same pages as the original where possible.
 
+# Helper Functions
+
+We have a number of handy helper functions to aid in keeping the layout
+of the document as close to the original as possible without you having
+to think too hard about how to do it.
+
+They are included as (currently) two class files, `dec.cls` and
+`decsectional.cls`. The former is the master class which is geared
+towards simpler non-numbered (single chapter) documents. The latter
+extends the master class to allow creation of longer chapter based
+documents.
+
+## Figures
+
+There are two figure helper functions, `fig` and `ttfig`. The first of
+these is used to include a figure into the document at the current
+location.
+
+    \fig[Scale]{ImageRefCode}{Caption For This Figure}
+
+The `Scale` parameter is optional and sets the width of the image as a
+percentage (0.0 - 1.0) of the page width. The `ImageRefCode` is the ID
+code (XX-NNNN-YY) of an image within the fig directory, and the caption
+is placed above the image and included in the list of figures in the
+contents section.
+
+The `ttfig` is a little different in that it defines a new environment
+which is used for creating text-based (ASCII art, console display, etc)
+figures.
+
+    \begin{ttfig}{This is the caption}
+     _____ _                      
+    |  ___(_) __ _ _   _ _ __ ___ 
+    | |_  | |/ _` | | | | '__/ _ \
+    |  _| | | (_| | |_| | | |  __/
+    |_|   |_|\__, |\__,_|_|  \___|
+             |___/ 
+    \end{ttfig}
+
+Result:
+
+::: ttfig
+This is the caption \_\_\_\_\_ \_ \| \_\_\_(\_) \_\_ \_ \_ \_ \_ \_\_
+\_\_\_ \| \|\_ \| \|/ \_' \| \| \| \| '\_\_/ \_  \| \_\| \| \| (\_\| \|
+\|\_\| \| \| \| \_\_/ \|\_\| \|\_\|\_\_, \|\_\_,\_\|\_\| \_\_\_\|
+\|\_\_\_/
+:::
+
+A DEC-style label is automatically created for every figure (figure:F or
+figure:C-F) for hyperlinks to jump to.
+
+## Tables
+
+Tables are internally handled by the `tabularx` package, but are wrapped
+in extra code to handle DEC style labels and captions. The main table
+environment is:
+
+    \begin{tbl}{Caption Here}{Spec}
+    ... content ...
+    \end{tbl}
+
+The `Spec` is a normal tabularx column set specification describing the
+columns in the table. A top and bottom horizontal line are automatically
+added, so just add the headings, another hline, and then the table body.
+For example:
+
+    \begin{tbl}{A Sample Table}{c c}
+    \textbf{First column} & \textbf{Second column} \\
+    \hline
+    This is something & This is something else \\
+    This is more & This is even more \\
+    \end{tbl}
+
+The result:
+
+::: tbl
+A Sample Tablec c **First column** & **Second column**\
+This is something & This is something else\
+This is more & This is even more\
+:::
+
+If a table is too long to fit on one page you can finish the table
+early, then re-start it on the next page using the `tblcont`
+environment. This is exactly the same as the `tbl` environment except
+the word (Cont.) is added to the caption numbering, and the table is not
+included in the list of tables in the TOC.
+
+    \begin{tblcont}{A Sample Table}{c c}
+    \textbf{First column} & \textbf{Second column} \\
+    \hline
+    This is exta & This bit wouldn't fit in the previous table.\\
+    \end{tblcont}
+
+::: tblcont
+A Sample Tablec c **First column** & **Second column**\
+This is exta & This bit wouldn't fit in the previous table.\
+:::
+
+## Chapters and sections
+
+As well as the normal chapter and section (both starred and unstarred
+variant) commands we have u-prefixed variants which serve as a half-way
+house between the starred and unstarred variants. Like the starred
+variants they are unnumbered, but like the unstarred variants they are
+included in the TOC. This allows for unnumbered documents to be created
+yet still have a functional TOC with minimum fuss.
+
+## References
+
+Creating links within the document is made easier with the use of a few
+reference helper functions: `figref` and `tableref`. Both just take a
+DEC-style figure or table reference number (for example 2-5) and format
+the name of the link for you automatically.
+
+There is also a `pdf` helper function which just takes a DEC order
+number and links to the PDF externally.
+
 # License
 
 These documents are provided with no warranty as regards their accuracy