From ac011a2edc6376590b6dc79772fbe91c43570bc4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Joel=20H=C3=A5kansson?= <joel.hakansson@mtm.se>
Date: Fri, 3 Nov 2017 10:37:45 +0100
Subject: [PATCH] Update documentation [ci skip]

---
 docs/Convert.md     | 36 ++++++------------
 docs/Emboss.md      | 39 ++++++++++++++-----
 docs/GeneratePef.md | 92 ++++++++++++++++++++++++---------------------
 docs/MergePef.md    | 13 +++++--
 docs/PefToText.md   | 15 ++++----
 docs/SplitPef.md    |  2 +-
 docs/TextToPef.md   | 44 +++++++++++-----------
 docs/UsersGuide.md  | 15 ++------
 docs/ValidatePef.md |  9 +++--
 docs/toc.md         | 35 +++++++++--------
 10 files changed, 158 insertions(+), 142 deletions(-)

diff --git a/docs/Convert.md b/docs/Convert.md
index 4200de8..e5a0322 100644
--- a/docs/Convert.md
+++ b/docs/Convert.md
@@ -1,13 +1,13 @@
 [Table of Contents](toc.md)
 
-## Convert ##
+# Convert #
 Converts a document into braille.
 
 Dotify requires two arguments to run:
   * path to an input file
   * path to the output file
 
-### Input File Requirements ###
+## Input File Requirements ##
 The input file should, of course, be something that Dotify understands. Because Dotify has been developed for and funded by [Swedish Agency for Accessible Media, MTM](http://www.mtm.se), the current capabilities may seem odd to an average user. Dotify supports:
   * DTBook
   * HTML
@@ -26,7 +26,7 @@ A plain text can also be used, with similar capabilities as for general XML, i.e
 
 OBFL is the intermediary format used by Dotify, and is likely only of interest to developers.
 
-### Output File Formats ###
+## Output File Formats ##
 The output format is determined by examining the extension of the specified output file name. Supported extensions are:
   * pef
   * txt
@@ -43,15 +43,9 @@ The following optional arguments are available:
   * preset
   * locale
   * outputFormat
-  * identifier
   * writeTempFiles
   * tempFilesDirectory
-  * date
-  * dateFormat
   * table
-  * watch
-  * listOptions
-  * configs
 
 ### preset ###
 The preset specifies some key properties of the finished product, such as row spacing, characters/line, rows/page and sheets/volume. Each of these can be set
@@ -69,26 +63,23 @@ The locale is very important, because it determines the fall-back language used
 ### outputFormat ###
 If specified, the output format is determined by the value of this parameter, instead of from the file name extension.
 
-### identifier ###
-Sets the identifier in the output file (if supported).
-
 ### writeTempFiles ###
 Set to true to write temp files.
 
 ### tempFilesDirectory ###
 Sets the directory to write temp data. If not specified, the user default is used.
 
-### date ###
-Sets the date in the output file (if supported).
-
-### dateFormat ###
-Sets the date format to use when writing the current date in meta data (if supported). The syntax is as specified by [SimpleDateFormat](http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html)
-
 ### table ###
 If specified, an ASCII-braille file is generated in addition to the PEF-file (requires that the output format is PEF).
 
+## Switches ##
+The following switches are available:
+  * watch
+  * listOptions
+  * configs
+
 ### watch ###
-If present, watches the input file for changes and runs the conversion when changes occur
+If present, watches the input file for changes and runs the conversion when changes occur.
 
 ### listOptions ##
 If present, lists additional options available in the context of the current job. Due to the dynamic
@@ -96,9 +87,4 @@ design of the system, the options are listed *after* the conversion has finished
 append them to the options list of the job just finished and run again. 
 
 ### configs ###
-If present, lists the available combinations of locale and braille translators 
-
-# Example Workflow #
-  1. Markup using a format of choice
-  1. Process format into PEF (with Dotify)
-  1. Emboss using Dotify or [Dotify Studio](https://github.com/brailleapps/dotify-studio)
\ No newline at end of file
+If present, lists the available combinations of locale and braille translators.
\ No newline at end of file
diff --git a/docs/Emboss.md b/docs/Emboss.md
index 5320706..a96232c 100644
--- a/docs/Emboss.md
+++ b/docs/Emboss.md
@@ -1,7 +1,7 @@
 [Table of Contents](toc.md)
 
 # Emboss #
-Send a PEF-file to an embosser for embossing.
+Sends a PEF-file to an embosser for embossing.
 
 One argument is required, and can be one of the following:
   * path to a file
@@ -13,23 +13,42 @@ Upon the first run, the application will ask the user for the required setup:
   * embosser model
   * embosser table (if applicable)
   * paper size
+  * paper orientation
 
 The file will be sent directly to the embosser on subsequent runs. To change settings, use either `--setup` or `--clear`.
 
-## Setup ##
-Setup will ask all the user to verify all settings.
+## Change settings ##
+When changing settings, the CLI will ask some questions about the device, model, braille table and paper size. See below for more information.
 
-## Clear ##
-Clear will delete the current settings. The next time the application is started, it runs as on the first run.
+When using `--setup` all setup details will be collected from the user interactively. If setup has already been performed, previous values will be used as defaults (if applicable).
+When using `--clear`, the current settings are deleted. The next time the application is started, it runs as on the first run.
 
-## Device ##
+### Device ###
 The device is the address where the embosser can be contacted. In most cases this should be intuitive. If your device does not show up, make sure that the embosser is turned on.
 
-## Embosser Model ##
+### Embosser Model ###
 Note that the same embosser model may communicate differently depending on firmware or hardware version. Make sure that the embosser version is correct.
 
-## Embosser Table ##
+### Embosser Table ###
 Some embossers require that a table is chosen by the user for the purpose of communication. Make sure that the table chosen in the user interface matches the value expected by the embosser.
 
-## Paper Size ##
-Verify that the paper in the embosser matches the value in the user interface. Some embossers uses rolls of paper. In this case, select a paper size that matches the intended paper size once cut.
\ No newline at end of file
+### Paper Size ###
+Verify that the paper in the embosser matches the value in the user interface. Some embossers uses rolls of paper. In this case, select a paper size that matches the intended paper size once cut.
+
+### Paper orientation ###
+...
+
+## Optional Arguments ##
+The following optional arguments are available:
+  - range
+  - copies
+  - dir
+
+### range ###
+Specifies the range of pages to emboss, for example `--range=1-3`.
+
+### copies ###
+Specifies the number of copies.
+
+### dir ###
+Specifies an output directory for the embosser data. If this is set, no data will be sent to the embosser. Instead, the files will be saved to this folder. The contents of the files are exactly what the embosser would have received if this option was not set.
\ No newline at end of file
diff --git a/docs/GeneratePef.md b/docs/GeneratePef.md
index 3d55ae6..4730bdb 100644
--- a/docs/GeneratePef.md
+++ b/docs/GeneratePef.md
@@ -1,65 +1,73 @@
 [Table of Contents](toc.md)
 
 # Generate a PEF-file #
-Generate a random PEF-file for testing purposes.
+Generates a random PEF-file for testing purposes.
 
 One argument is required: _path to output file_
 
-<pre>
-Example:<br>
-dotify generate output.pef<br>
-</pre>
+Example:
 
-Optional arguments include:
+`dotify generate output.pef`
+
+## Optional Arguments ##
+The following optional arguments are available:
   * volumes
+  * sections
   * pages
-  * eightdot
   * rows
   * cols
-  * duplex
 
-## Volumes ##
+### volumes ###
 Set the number of volumes to generate.
 
-<pre>
-Example:<br>
-dotify generate output.pef -volumes=3<br>
-</pre>
+Example:
 
-## Pages ##
-Set the number of pages in each volume.
+`dotify generate output.pef --volumes=3`
 
-<pre>
-Example:<br>
-dotify generate output.pef -pages=50<br>
-</pre>
+### sections ###
+Sets the number of sections in each volume.
 
-## Eight dot ##
-Set to true to include 8-dot patterns.
+Example:
+
+`dotify generate output.pef --sections=3`
+
+### pages ###
+Set the number of pages in each volume.
+
+Example:
 
-<pre>
-Example:<br>
-dotify generate output.pef -eightdot=true<br>
-</pre>
+`dotify generate output.pef --pages=50`
 
-## Rows ##
+### rows ###
 Set the maximum numbers of rows on a page.
 
-<pre>
-Example:<br>
-dotify generate output.pef -rows=29<br>
-</pre>
+Example:
+
+`dotify generate output.pef --rows=29`
 
-## Cols ##
+### cols ###
 Set the maximum number of characters on a row.
-<pre>
-Example:<br>
-dotify generate output.pef -cols=28<br>
-</pre>
-
-## Duplex ##
-Set the duplex property.
-<pre>
-Example:<br>
-dotify generate output.pef -duplex=true<br>
-</pre>
\ No newline at end of file
+
+Example:
+
+`dotify generate output.pef --cols=28`
+
+## Switches ##
+The following switches are available:
+  * full-range (-f)
+  * simplex (-s)
+
+### full-range ###
+Set to true to include 8-dot patterns.
+
+Example:
+
+`dotify generate output.pef -f`
+
+
+### simplex ###
+Creates a single sided PEF-file.
+
+Example:
+
+`dotify generate output.pef -s`
diff --git a/docs/MergePef.md b/docs/MergePef.md
index f181b19..df1969c 100644
--- a/docs/MergePef.md
+++ b/docs/MergePef.md
@@ -1,14 +1,19 @@
 [Table of Contents](toc.md)
 
 # Merge several PEF-files #
-Merge several PEF files into one.
+Merges several PEF files into one.
 
 The purpose is to facilitating the use of PEF-files with braille editors that do not support multi volume files.
 
 Three arguments are required: _path to input folder_, _path to output file_ and identifier.
 
-Optional arguments include:
+## Optional Arguments ##
+The following optional arguments are available:
   * sort
 
-## Sort ##
-Set the sorting method to use when ordering files in the input folder.
\ No newline at end of file
+### Sort ###
+Set the sorting method to use when ordering files in the input folder.
+
+Example:
+
+`dotify merge /path/to/input /path/to/output identifier --sort=alpha`
\ No newline at end of file
diff --git a/docs/PefToText.md b/docs/PefToText.md
index 20678d8..82179f1 100644
--- a/docs/PefToText.md
+++ b/docs/PefToText.md
@@ -1,31 +1,32 @@
 [Table of Contents](toc.md)
 
 # PEF to Text #
-Convert a PEF-file document into a text braille file.
+Converts a PEF-file document into a text braille file.
 
 Two arguments are required _path to input file_ and _path to output file_.
 
-Optional arguments include:
+## Optional Arguments ##
+The following optional arguments are available:
   * range
   * table
   * breaks
   * fallback
   * replacement
 
-## Range ##
+### Range ###
 Output a range of pages.
 
-## Table ##
+### Table ###
 Set the table (character mapping) to use.
 
-## Breaks ##
+### Breaks ###
 Set the line break style. Most braille applications use DOS line breaks.
 
-## Fallback ##
+### Fallback ###
 Set the action to use if an eight dot pattern is encountered and the current table does not support eight dot:
   * mask
   * replace
   * remove
 
-## Replacement ##
+### Replacement ###
 Set the replacement character to use if an eight dot pattern is encountered and fallback is set to "replace".
\ No newline at end of file
diff --git a/docs/SplitPef.md b/docs/SplitPef.md
index b9d4de9..da9da98 100644
--- a/docs/SplitPef.md
+++ b/docs/SplitPef.md
@@ -1,7 +1,7 @@
 [Table of Contents](toc.md)
 
 # Split a PEF-file #
-Split a PEF file into several files, one file per volume.
+Splits a PEF file into several files, one file per volume.
 
 The purpose is to facilitating the use of PEF files with braille editors that do not support multi volume files.
 
diff --git a/docs/TextToPef.md b/docs/TextToPef.md
index 3caa5a6..483cd4d 100644
--- a/docs/TextToPef.md
+++ b/docs/TextToPef.md
@@ -1,45 +1,45 @@
 [Table of Contents](toc.md)
 
 # Text to PEF #
-Convert a text braille file into a PEF-file.
+Converts a text braille file into a PEF-file.
 
 Two arguments are required _path to input file_ and _path to output file_.
 
 The input file should be a "braille ready" text file, i.e. broken in rows an pages (using the form feed character), and using one unique character to represent each braille pattern.
 
-<pre>
-Example:<br>
-dotify text2pef input.txt output.pef<br>
-</pre>
+Example:
 
-Optional arguments include:
+`dotify text2pef input.txt output.pef`
+
+## Optional Arguments##
+The following optional arguments are available:
   * mode
   * identifier
   * date
   * author
   * title
   * language
-  * duplex
 
 The options `identifier`, `date`, `author`, `title` and `language` all involve setting the meta data of the resulting file. It will not affect the contents of the file in any way.
 
-<pre>
-Example:<br>
-dotify text2pef input.txt output.pef -date=2013-01-01<br>
-</pre>
+Example:
+
+`dotify text2pef input.txt output.pef --date=2013-01-01`
 
-## Mode ##
+## mode ##
 Choose a table to use when converting. Note that, if a character is encountered in the file that isn't in the selected table, an error will occur. The default mode is to attempt to detect. If this fail, choose between the tables suggested in the detector failure message.
 
-<pre>
-Example:<br>
-dotify text2pef input.txt output.pef -mode=nabcc<br>
-</pre>
+Example:
+
+`dotify text2pef input.txt output.pef --mode=nabcc`
+
+## Switches ##
+The following switches are available:
+  * simplex
+  
+### simplex ##
+Creates a single sided PEF-file.
 
-## Duplex ##
-Set the duplex property of the resulting file.
+Example:
 
-<pre>
-Example:<br>
-dotify text2pef input.txt output.pef -duplex=true<br>
-</pre>
\ No newline at end of file
+`dotify text2pef input.txt output.pef -s`
\ No newline at end of file
diff --git a/docs/UsersGuide.md b/docs/UsersGuide.md
index fb8624a..6eea8b7 100644
--- a/docs/UsersGuide.md
+++ b/docs/UsersGuide.md
@@ -9,17 +9,8 @@ To run the command line UI, download and extract the latest release. If you do n
 
 On the command line, navigate to the `bin` folder inside the extracted folder and type: `dotify`. Press enter.
 
-This will bring up a list of applications (or features):
-  * [convert](Convert.md)
-  * [emboss](Emboss.md)
-  * [text2pef](TextToPef.md)
-  * [pef2text](PefToText.md)
-  * [validate](ValidatePef.md)
-  * [split](SplitPef.md)
-  * [merge](MergePef.md)
-  * [generate](GeneratePef.md)
-  * help
+This will bring up a list of applications (or features). See the [Table of Contents](toc.md) for more information about each command.
+
+To use one of these commands, append their name as the first argument, for example:
 
-These are explained in detail in separate sections.
-To start one of them, append their name as the first argument, for example:
 `dotify convert`
\ No newline at end of file
diff --git a/docs/ValidatePef.md b/docs/ValidatePef.md
index 8956718..359e902 100644
--- a/docs/ValidatePef.md
+++ b/docs/ValidatePef.md
@@ -1,14 +1,15 @@
 [Table of Contents](toc.md)
 
 # Validate a PEF-file #
-Validate a PEF-file.
+Validates a PEF-file.
 
 One argument is required: _path to input file_
 
-Optional arguments include:
+## Optional Arguments ##
+The following optional arguments are available:
   * mode
 
-## Mode ##
-Set the validation mode:
+### mode ###
+Sets the validation mode:
   * full
   * light
\ No newline at end of file
diff --git a/docs/toc.md b/docs/toc.md
index ca84e92..da9505f 100644
--- a/docs/toc.md
+++ b/docs/toc.md
@@ -1,16 +1,21 @@
-#Table of Contents#
+# Table of Contents #
 
-* [User's Guide](UsersGuide.md)
-  * Commands
-    * [convert](Convert.md)
-    * [emboss](Emboss.md)
-    * [text2pef](TextToPef.md)
-    * [pef2text](PefToText.md)
-    * [validate](ValidatePef.md)
-    * [split](SplitPef.md)
-    * [merge](MergePef.md)
-    * [generate](GeneratePef.md)
-  * [Plugins](Plugins.md)
-  * [Changes](changes.md)
-  * Appendices
-    * [Unicode Braille Patterns](UnicodeBraillePatterns.md)
\ No newline at end of file
+* [Introduction](UsersGuide.md)
+* Commands
+  * [convert](Convert.md)
+  * [emboss](Emboss.md)
+  * [validate](ValidatePef.md)
+  * inspect
+  * find
+  * [text2pef](TextToPef.md)
+  * [pef2text](PefToText.md)
+  * [split](SplitPef.md)
+  * [merge](MergePef.md)
+  * translate
+  * [generate](GeneratePef.md)
+  * list
+  * help
+* [Plugins](Plugins.md)
+* [Changes](changes.md)
+* Appendices
+  * [Unicode Braille Patterns](UnicodeBraillePatterns.md)
\ No newline at end of file