Reformatted docs.

format.mod/doc/intro.bbdoc

@@ -1,87 +1,76 @@
-<p>
-The <b>Format</b> module is a String formatter using C-style <i>sprintf / printf</i> syntax.
-</p>
-<p>printf syntax is a universally recognized method of formatted strings. This module attempts to implement the most-used conversion specifications.
-</p>
-<h3>Requirements</h3>
-<p>The Format module requires the <b>BaH.RegEx</b> module. It should be available from the same place you found this one.</p>
-<h2>Using the Formatter</h2>
-<p>
-You begin by creating a formatter, using the <a href="#TFormatter">TFormatter</a> type. The <a href="#Create">Create</a> method takes a format String as a parameter. See the syntax guide below for formatting details.
-</p>
-<pre>
+
+The **Format** module is a String formatter using C-style *sprintf / printf* syntax.
+
+printf syntax is a universally recognized method of formatted strings. This module attempts to implement the most-used conversion specifications.
+
+### Using the Formatter
+
+You begin by creating a formatter, using the #TFormatter type. The #Create method takes a format String as a parameter. See the syntax guide below for formatting details.
+
+```blitzmax
 Local formatter:TFormatter = TFormatter.Create("VAT = %2.1f%%")
-</pre>
-<p>
-Each conversion specification expects an argument (with the exception of %n and %%), to which you must supply an appropriate value.<br>
-You do this by calling one of the following methods:<br>
-<a href="#ByteArg">ByteArg</a>, <a href="#ShortArg">ShortArg</a>, <a href="#IntArg">IntArg</a>, <a href="#LongArg">LongArg</a>, <a href="#FloatArg">FloatArg</a>, <a href="#DoubleArg">DoubleArg</a> or <a href="#StringArg">StringArg</a>.
-</p>
-<pre>
-formatter.FloatArg(17.5)
-</pre>
-<p>Since each <b>Arg</b> method returns the TFormatter object, it allows you to tag together a sequence of arguments, like so:</p>
-<pre>
+```
+
+Each conversion specification expects an argument (with the exception of `%%`), to which you must supply an appropriate value.
+
+You do this by calling the #Arg() method:
+
+```blitzmax
+formatter.Arg(17.5)
+```
+Since each #Arg() method returns the #TFormatter object, it allows you to chain together a sequence of arguments, like so:
+```blitzmax
 Local formatter:TFormatter = TFormatter.Create("Name = %s : Id = X%09d")
-formatter.StringArg("William Smith").IntArg(65002)
-</pre>
-<p>
-The <a href="#Format">Format</a> method formats the text using the given arguments, and returns the String result.
-</p>
-<pre>
+formatter.Arg("William Smith").Arg(65002)
+```
+
+The #Format() method formats the text using the given arguments, and returns the String result.
+
+```blitzmax
 Print formatter.format()
-</pre>
-<p>
-To reuse a formatter, you can call the <a href="#Clear">Clear</a> method to remove the arguments, allowing you to apply some new ones without the formatting engine having to re-process the format string.
-</p>
-<h2>A quick guide to syntax</h2>
-<p>The format string can contain both ordinary text and conversion specifications.
-</p>
-<p>A conversion specification begins with a <b>%</b> and ends with a particular conversion specifier (d, f, s, n, %).<br>
+```
+
+To reuse a formatter, you can call the #Clear() method to remove the arguments, allowing you to apply some new ones without the formatting engine having to re-process the format string.
+
+## A quick guide to syntax
+The format string can contain both ordinary text and conversion specifications.
+
+A conversion specification begins with a `%` and ends with a particular conversion specifier (d, f, s, %).
+
 In between, and in the following order, there may be zero or more flags, an optional field width, and an optional precision.
-</p>
-<h3>Flags</h3>
-<p>The % character is followed by zero or more flags :</p>
-<table width="90%" align="center">
-<tr><th>Flag</th><th>Description</th></tr>
-<tr><td><b>#</b></td><td>The value should be converted to an <i>alternate form</i>. For <b>f</b> conversions, the result will always contain a decimal point, even if no digits follow it.<br>
-For other conversions, the result is undefined.</td></tr>
-<tr><td><b>0</b></td><td>The value should be zero padded.<br>
-For <b>d</b> and <b>f</b> conversions, the converted value is padded on the left with zeros rather than blanks.<br>
-For other conversions, the behavior is undefined.</td></tr>
-<tr><td><b>-</b></td><td>The converted value is to be left justified on the field boundary. (The default is right justification.)<br>
-Except for <b>n</b> conversions, the converted value is padded on the right with blanks, rather than on the left with blanks or zeros. A - overrides a 0 if both are given.</td></tr>
-<tr><td><b>' '</b> (space)</td><td>A blank should be left before a positive number (or empty string) produced by a signed conversion.</td></tr>
-<tr><td><b>+</b></td><td>A sign (+ or -) should always be placed before a number produced by a signed conversion. By default a sign is used only for negative numbers. A + overrides a space if both are used.</td></tr>
-<tr><td><b>,</b></td><td>For decimal conversion (<b>d</b>, <b>f</b>) the output is to be grouped with thousands’ grouping character.</td></tr>
-</table>
-<h3>Field width</h3>
-<p> An optional number specifying a minimum field width.<br>
-If  the  converted  value  has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left-justify flag has been given). <br>
+
+### Flags
+The `%` character is followed by zero or more flags :
+| Flag | Description |
+|:-:|---|
+| `#` | The value should be converted to an *alternate form*. For `f` conversions, the result will always contain a decimal point, even if no digits follow it.<br/>For other conversions, the result is undefined. |
+| `0` | The value should be zero padded.<br/>For `d` and `f` conversions, the converted value is padded on the left with zeros rather than blanks.<br/>For other conversions, the behaviour is undefined. |
+| `-` | The converted value is to be left justified on the field boundary. (The default is right justification.)<br/>Except for `n` conversions, the converted value is padded on the right with blanks, rather than on the left with blanks or zeros. A - overrides a 0 if both are given. |
+| `' '` (space) | A blank should be left before a positive number (or empty string) produced by a signed conversion. |
+| `+` | A sign (`+` or `-`) should always be placed before a number produced by a signed conversion. By default a sign is used only for negative numbers. A `+` overrides a space if both are used. |
+| `,` | For decimal conversion (`d`, `f`) the output is to be grouped with thousands’ grouping character. |
+
+### Field width
+An optional number specifying a minimum field width.
+
+If  the  converted  value  has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left-justify flag has been given).
+
 In no case does a non-existent or small field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is expanded  to  contain  the  conversion result.
-</p>
-<h3>Precision</h3>
-<p>
-An  optional  precision, in the form of a period ('.') followed by an optional integer value.<br>
-If the precision is given as just '.', or the precision is negative, the precision is taken to be zero.<br>
-This gives the minimum number of digits to appear for <b>d</b> conversions, the number of digits to appear after the radix character for <b>f</b> conversions, or the maximum number of characters to be printed from a string for <b>s</b> conversions.
-</p>
-<h3>Conversion Specifier</h3>
-<p>
-A character that specifies the type of conversion to be applied.  The conversion specifiers and their meanings are:</p>
-<table width="90%" align="center">
-<tr><th>Conversion</th><th>Description</th></tr>
-<tr><td><b>d</b></td><td>The argument (Byte, Short, Int, Long) is converted to signed decimal notation.<br>
-The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left  with zeros.<br>
-The default precision is 1.</td></tr>
-<tr><td><b>f</b></td><td>The argument (Float, Double) is rounded and converted to decimal notation in the  style [-]ddd.ddd,  where  the number  of  digits  after  the decimal-point character is equal to the precision specification.<br>
-If the precision is missing, it is taken as 6; if the precision is explicitly zero, no decimal-point character appears.<br>
-If a decimal point appears, at least one digit appears before it.</td></tr>
-<tr><td><b>s</b></td><td>The argument (String) is converted to a space-padded or left-justified string equal to the width specified.<br>
-If precision is given, no more than the number of characters specified are output.
-</td></tr>
-<tr><td><b>n</b></td><td>The platform specific line-separator.</td></tr>
-<tr><td><b>%</b></td><td>A literal %.</td></tr>
-</table>
 
+### Precision
+
+An optional  precision, in the form of a period ('.') followed by an optional integer value.
+
+If the precision is given as just '.', or the precision is negative, the precision is taken to be zero.
+
+This gives the minimum number of digits to appear for `d` conversions, the number of digits to appear after the radix character for `f` conversions, or the maximum number of characters to be printed from a string for `s` conversions.
+
+### Conversion Specifier
 
+A character that specifies the type of conversion to be applied.  The conversion specifiers and their meanings are:
+| Conversion | Description |
+|:-:|---|
+| `d` | The argument (#Byte, #Short, #Int, #UInt, #Long) is converted to signed decimal notation.<br/>The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left  with zeros.<br/>The default precision is 1. |
+| `f` | The argument (#Float, #Double) is rounded and converted to decimal notation in the  style `[-]ddd.ddd`, where the number of digits  after  the decimal-point character is equal to the precision specification.<br/>If the precision is missing, it is taken as 6; if the precision is explicitly zero, no decimal-point character appears.<br/>If a decimal point appears, at least one digit appears before it. |
+| `s` | The argument (#String) is converted to a space-padded or left-justified string equal to the width specified.<br/>If precision is given, no more than the number of characters specified are output.  |
+| `%` | A literal `%`. |