Documentation updates (#87)

* Ignore Manifest.toml files

* Add import statement in install instructions

* Use single backtick for monospace

Double backtick names get passed on to the
(La/Ka)TeX renderer

* Combine markdown lists

Repeated newlines are interpreted as separate lists

* Use python 3 for reference

* Make package name a header

.gitignore

@@ -1,3 +1,4 @@
 *.jl.cov
 *.jl.*.cov
 *.jl.mem
+Manifest.toml

README.md

@@ -37,7 +37,7 @@ This package offers Python-style general formatting and c-style numerical format
 This package is pure Julia. Setting up this package is like setting up other Julia packages:
 
 ```julia
-Pkg.add("Format")
+import Pkg; Pkg.add("Format")
 ```
 or
 ```julia
@@ -59,92 +59,91 @@ This package depends on Julia of version 1.4 or above, and. The package is MIT-l
 
 #### Types to Represent Formats
 
-This package has two types ``FormatSpec`` and ``FormatExpr`` to represent a format specification.
+This package has two types `FormatSpec` and `FormatExpr` to represent a format specification.
 
-In particular, ``FormatSpec`` is used to capture the specification of a single entry. One can compile a format specification string into a ``FormatSpec`` instance as
+In particular, `FormatSpec` is used to capture the specification of a single entry. One can compile a format specification string into a `FormatSpec` instance as
 
 ```julia
 fspec = FormatSpec("d")
 fspec = FormatSpec("<8.4f")
 ```
-Please refer to [Python's format specification language](http://docs.python.org/2/library/string.html#formatspec) for details.
+Please refer to [Python's format specification language](http://docs.python.org/3/library/string.html#formatspec) for details.
 
 
-``FormatExpr`` captures a formatting expression that may involve multiple items. One can compile a formatting string into a ``FormatExpr`` instance as
+`FormatExpr` captures a formatting expression that may involve multiple items. One can compile a formatting string into a `FormatExpr` instance as
 
 ```julia
 fe = FormatExpr("{1} + {2}")
 fe = FormatExpr("{1:d} + {2:08.4e} + {3|>abs2}")
 ```
-Please refer to [Python's format string syntax](http://docs.python.org/2/library/string.html#format-string-syntax) for details.
+Please refer to [Python's format string syntax](http://docs.python.org/3/library/string.html#format-string-syntax) for details.
 
 
 **Note:** If the same format is going to be applied for multiple times. It is more efficient to first compile it.
 
 
 #### Formatted Printing
 
-One can use ``printfmt`` and ``printfmtln`` for formatted printing:
+One can use `printfmt` and `printfmtln` for formatted printing:
 
 - **printfmt**(io, fe, args...)
 
 - **printfmt**(fe, args...)
 
-    Print given arguments using given format ``fe``. Here ``fe`` can be a formatting string, an instance of ``FormatSpec`` or ``FormatExpr``.
-
-    **Examples**
-
-    ```julia
-    printfmt("{1:>4s} + {2:.2f}", "abc", 12) # --> print(" abc + 12.00")
-    printfmt("{} = {:#04x}", "abc", 12) # --> print("abc = 0x0c") 
-
-    fs = FormatSpec("#04x")
-    printfmt(fs, 12)   # --> print("0x0c")
-
-    fe = FormatExpr("{} = {:#04x}")
-    printfmt(fe, "abc", 12)   # --> print("abc = 0x0c")
-    ```
+  Print given arguments using given format `fe`. Here `fe` can be a formatting string, an instance of `FormatSpec` or `FormatExpr`.
 
-    **Notes**
+  **Examples**
 
-    If the first argument is a string, it will be first compiled into a ``FormatExpr``, which implies that you can not use specification-only string in the first argument.
+  ```julia
+  printfmt("{1:>4s} + {2:.2f}", "abc", 12) # --> print(" abc + 12.00")
+  printfmt("{} = {:#04x}", "abc", 12) # --> print("abc = 0x0c")
 
-    ```julia
-    printfmt("{1:d}", 10)   # OK, "{1:d}" can be compiled into a FormatExpr instance
-    printfmt("d", 10)       # Error, "d" can not be compiled into a FormatExpr instance
-                            # such a string to specify a format specification for single argument
+  fs = FormatSpec("#04x")
+  printfmt(fs, 12)   # --> print("0x0c")
 
-    printfmt(FormatSpec("d"), 10)  # OK
-    printfmt(FormatExpr("{1:d}", 10)) # OK
-    ```
+  fe = FormatExpr("{} = {:#04x}")
+  printfmt(fe, "abc", 12)   # --> print("abc = 0x0c")
+  ```
 
+  **Notes**
+
+  If the first argument is a string, it will be first compiled into a `FormatExpr`, which implies that you can not use specification-only string in the first argument.
+
+  ```julia
+  printfmt("{1:d}", 10)   # OK, "{1:d}" can be compiled into a FormatExpr instance
+  printfmt("d", 10)       # Error, "d" can not be compiled into a FormatExpr instance
+                          # such a string to specify a format specification for single argument
+
+  printfmt(FormatSpec("d"), 10)  # OK
+  printfmt(FormatExpr("{1:d}", 10)) # OK
+  ```
 
 - **printfmtln**(io, fe, args...)
 
 - **printfmtln**(fe, args...)
 
-    Similar to ``printfmt`` except that this function print a newline at the end.
+    Similar to `printfmt` except that this function print a newline at the end.
 
 #### Formatted String
 
-One can use ``pyfmt`` to format a single value into a string, or ``format`` to format one to multiple arguments into a string using an format expression.
+One can use `pyfmt` to format a single value into a string, or `format` to format one to multiple arguments into a string using an format expression.
 
 - **pyfmt**(fspec, a)
 
-    Format a single value using a format specification given by ``fspec``, where ``fspec`` can be either a string or an instance of ``FormatSpec``.
+  Format a single value using a format specification given by `fspec`, where `fspec` can be either a string or an instance of `FormatSpec`.
 
 - **format**(fe, args...)
 
-    Format arguments using a format expression given by ``fe``, where ``fe`` can be either a string or an instance of ``FormatSpec``.
+  Format arguments using a format expression given by `fe`, where `fe` can be either a string or an instance of `FormatSpec`.
 
 
 #### Difference from Python's Format
 
 At this point, this package implements a subset of Python's formatting language (with slight modification). Here is a summary of the differences:
 
-- In terms of argument specification, it supports natural ordering (e.g. ``{} + {}``), explicit position (e.g. ``{1} + {2}``). It hasn't supported named arguments or fields extraction yet. Note that mixing these two modes is not allowed (e.g. ``{1} + {}``).
+- In terms of argument specification, it supports natural ordering (e.g. `{} + {}`), explicit position (e.g. `{1} + {2}`). It hasn't supported named arguments or fields extraction yet. Note that mixing these two modes is not allowed (e.g. `{1} + {}`).
 
-- The package provides support for filtering (for explicitly positioned arguments), such as ``{1|>lowercase}`` by allowing one to embed the ``|>`` operator, which the Python counter part does not support.
+- The package provides support for filtering (for explicitly positioned arguments), such as `{1|>lowercase}` by allowing one to embed the `|>` operator, which the Python counter part does not support.
 
 ## C-style functions
 

src/Format.jl

@@ -1,5 +1,5 @@
 """
-Format.jl
+# Format.jl
 
 This package provides various functions to provide formatted output,
 either in a fashion similar to C printf or Python format strings.
@@ -8,18 +8,22 @@ either in a fashion similar to C printf or Python format strings.
 
 #### Types to Represent Formats
 
-This package has two types ``FormatSpec`` and ``FormatExpr`` to represent a format specification.
+This package has two types `FormatSpec` and `FormatExpr` to represent a
+format specification.
 
-In particular, ``FormatSpec`` is used to capture the specification of a single entry. One can compile a format specification string into a ``FormatSpec`` instance as
+In particular, `FormatSpec` is used to capture the specification of a single
+entry. One can compile a format specification string into a `FormatSpec`
+instance as
 
 ```julia
 fspec = FormatSpec("d")
 fspec = FormatSpec("<8.4f")
 ```
-Please refer to [Python's format specification language](http://docs.python.org/2/library/string.html#formatspec) for details.
+Please refer to [Python's format specification language](http://docs.python.org/3/library/string.html#formatspec) for details.
 
 
-``FormatExpr`` captures a formatting expression that may involve multiple items. One can compile a formatting string into a ``FormatExpr`` instance as
+`FormatExpr` captures a formatting expression that may involve multiple items.
+One can compile a formatting string into a `FormatExpr` instance as
 
 ```julia
 fe = FormatExpr("{1} + {2}")
@@ -33,67 +37,77 @@ Please refer to [Python's format string syntax](http://docs.python.org/2/library
 
 #### Formatted Printing
 
-One can use ``printfmt`` and ``printfmtln`` for formatted printing:
+One can use `printfmt` and `printfmtln` for formatted printing:
 
 - **printfmt**(io, fe, args...)
 
 - **printfmt**(fe, args...)
 
-    Print given arguments using given format ``fe``. Here ``fe`` can be a formatting string, an instance of ``FormatSpec`` or ``FormatExpr``.
-    
-    **Examples**
-    
-    ```julia
-    printfmt("{1:>4s} + {2:.2f}", "abc", 12) # --> print(" abc + 12.00")
-    printfmt("{} = {:#04x}", "abc", 12) # --> print("abc = 0x0c") 
-    
-    fs = FormatSpec("#04x")
-    printfmt(fs, 12)   # --> print("0x0c")
-    
-    fe = FormatExpr("{} = {:#04x}")
-    printfmt(fe, "abc", 12)   # --> print("abc = 0x0c")
-    ```
+  Print given arguments using given format `fe`. Here `fe` can be a formatting
+  string, an instance of `FormatSpec` or `FormatExpr`.
 
-    **Notes**
+  **Examples**
 
-    If the first argument is a string, it will be first compiled into a ``FormatExpr``, which implies that you can not use specification-only string in the first argument.
+  ```julia
+  printfmt("{1:>4s} + {2:.2f}", "abc", 12) # --> print(" abc + 12.00")
+  printfmt("{} = {:#04x}", "abc", 12) # --> print("abc = 0x0c")
 
-    ```julia
-    printfmt("{1:d}", 10)   # OK, "{1:d}" can be compiled into a FormatExpr instance
-    printfmt("d", 10)       # Error, "d" can not be compiled into a FormatExpr instance
-                            # such a string to specify a format specification for single argument
+  fs = FormatSpec("#04x")
+  printfmt(fs, 12)   # --> print("0x0c")
 
-    printfmt(FormatSpec("d"), 10)  # OK
-    printfmt(FormatExpr("{1:d}", 10)) # OK
-    ```
+  fe = FormatExpr("{} = {:#04x}")
+  printfmt(fe, "abc", 12)   # --> print("abc = 0x0c")
+  ```
 
+  **Notes**
+
+  If the first argument is a string, it will be first compiled into a `FormatExpr`,
+  which implies that you can not use specification-only string in the first argument.
+
+  ```julia
+  printfmt("{1:d}", 10)   # OK, "{1:d}" can be compiled into a FormatExpr instance
+  printfmt("d", 10)       # Error, "d" can not be compiled into a FormatExpr instance
+                          # such a string to specify a format specification for single argument
+
+  printfmt(FormatSpec("d"), 10)  # OK
+  printfmt(FormatExpr("{1:d}", 10)) # OK
+  ```
 
 - **printfmtln**(io, fe, args...)
 
 - **printfmtln**(fe, args...)
 
-    Similar to ``printfmt`` except that this function print a newline at the end.
+  Similar to `printfmt` except that this function print a newline at the end.
 
 #### Formatted String
 
-One can use ``pyfmt`` to format a single value into a string, or ``format`` to format one to multiple arguments into a string using an format expression.
+One can use `pyfmt` to format a single value into a string, or `format` to
+format one to multiple arguments into a string using an format expression.
 
 - **pyfmt**(fspec, a)
 
-    Format a single value using a format specification given by ``fspec``, where ``fspec`` can be either a string or an instance of ``FormatSpec``.
+  Format a single value using a format specification given by `fspec`, where
+  `fspec` can be either a string or an instance of `FormatSpec`.
 
 - **format**(fe, args...)
 
-    Format arguments using a format expression given by ``fe``, where ``fe`` can be either a string or an instance of ``FormatSpec``.
+  Format arguments using a format expression given by `fe`, where `fe` can be
+  either a string or an instance of `FormatSpec`.
 
 
 #### Difference from Python's Format
 
-At this point, this package implements a subset of Python's formatting language (with slight modification). Here is a summary of the differences:
+At this point, this package implements a subset of Python's formatting language
+(with slight modification). Here is a summary of the differences:
 
-- In terms of argument specification, it supports natural ordering (e.g. ``{} + {}``), explicit position (e.g. ``{1} + {2}``). It hasn't supported named arguments or fields extraction yet. Note that mixing these two modes is not allowed (e.g. ``{1} + {}``).
+- In terms of argument specification, it supports natural ordering (e.g.
+  `{} + {}`), explicit position (e.g. `{1} + {2}`). It hasn't supported named
+  arguments or fields extraction yet. Note that mixing these two modes is not
+  allowed (e.g. `{1} + {}`).
 
-- The package provides support for filtering (for explicitly positioned arguments), such as ``{1|>lowercase}`` by allowing one to embed the ``|>`` operator, which the Python counter part does not support.
+- The package provides support for filtering (for explicitly positioned
+  arguments), such as `{1|>lowercase}` by allowing one to embed the `|>`
+  operator, which the Python counter part does not support.
 
 ## C-style functions