From 9f6decbdec050c6a3f20d4751e458c992b9c83dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Joel=20H=C3=A5kansson?= Date: Tue, 23 Aug 2016 16:35:33 +0200 Subject: [PATCH] Adds complete user documentation --- docs/Emboss.md | 35 ++++++++++++++++++ docs/GeneratePef.md | 65 ++++++++++++++++++++++++++++++++++ docs/MergePef.md | 14 ++++++++ docs/PefToText.md | 31 ++++++++++++++++ docs/Plugins.md | 4 +++ docs/README.md | 2 +- docs/SplitPef.md | 8 +++++ docs/TextToPef.md | 45 +++++++++++++++++++++++ docs/UnicodeBraillePatterns.md | 3 ++ docs/UsersGuide.md | 23 ++++++++++++ docs/ValidatePef.md | 14 ++++++++ docs/changes.md | 5 +++ docs/toc.md | 15 ++++++++ 13 files changed, 263 insertions(+), 1 deletion(-) create mode 100644 docs/Emboss.md create mode 100644 docs/GeneratePef.md create mode 100644 docs/MergePef.md create mode 100644 docs/PefToText.md create mode 100644 docs/Plugins.md create mode 100644 docs/SplitPef.md create mode 100644 docs/TextToPef.md create mode 100644 docs/UsersGuide.md create mode 100644 docs/ValidatePef.md create mode 100644 docs/toc.md diff --git a/docs/Emboss.md b/docs/Emboss.md new file mode 100644 index 0000000..deb4474 --- /dev/null +++ b/docs/Emboss.md @@ -0,0 +1,35 @@ +[Table of Contents](toc.md) + +# Emboss # +Send a PEF-file to an embosser for embossing. + +One argument is required, and can be one of the following: + * path to a file + * `-clear` + * `-setup` + +Upon the first run, the application will ask the user for the required setup: + * device + * embosser model + * embosser table (if applicable) + * paper size + +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. + +## Clear ## +Clear will delete the current settings. The next time the application is started, it runs as on the first run. + +## 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 ## +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 ## +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 diff --git a/docs/GeneratePef.md b/docs/GeneratePef.md new file mode 100644 index 0000000..7fff3c2 --- /dev/null +++ b/docs/GeneratePef.md @@ -0,0 +1,65 @@ +[Table of Contents](toc.md) + +# Generate a PEF-file # +Generate a random PEF-file for testing purposes. + +One argument is required: _path to output file_ + +
+Example:

+java -jar brailleUtils-ui.jar generate output.pef

+
+ +Optional arguments include: + * volumes + * pages + * eightdot + * rows + * cols + * duplex + +## Volumes ## +Set the number of volumes to generate. + +
+Example:

+java -jar brailleUtils-ui.jar generate output.pef -volumes=3

+
+ +## Pages ## +Set the number of pages in each volume. + +
+Example:

+java -jar brailleUtils-ui.jar generate output.pef -pages=50

+
+ +## Eight dot ## +Set to true to include 8-dot patterns. + +
+Example:

+java -jar brailleUtils-ui.jar generate output.pef -eightdot=true

+
+ +## Rows ## +Set the maximum numbers of rows on a page. + +
+Example:

+java -jar brailleUtils-ui.jar generate output.pef -rows=29

+
+ +## Cols ## +Set the maximum number of characters on a row. +
+Example:

+java -jar brailleUtils-ui.jar generate output.pef -cols=28

+
+ +## Duplex ## +Set the duplex property. +
+Example:

+java -jar brailleUtils-ui.jar generate output.pef -duplex=true

+
\ No newline at end of file diff --git a/docs/MergePef.md b/docs/MergePef.md new file mode 100644 index 0000000..f181b19 --- /dev/null +++ b/docs/MergePef.md @@ -0,0 +1,14 @@ +[Table of Contents](toc.md) + +# Merge several PEF-files # +Merge 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: + * sort + +## Sort ## +Set the sorting method to use when ordering files in the input folder. \ No newline at end of file diff --git a/docs/PefToText.md b/docs/PefToText.md new file mode 100644 index 0000000..20678d8 --- /dev/null +++ b/docs/PefToText.md @@ -0,0 +1,31 @@ +[Table of Contents](toc.md) + +# PEF to Text # +Convert 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: + * range + * table + * breaks + * fallback + * replacement + +## Range ## +Output a range of pages. + +## Table ## +Set the table (character mapping) to use. + +## Breaks ## +Set the line break style. Most braille applications use DOS line breaks. + +## 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 ## +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/Plugins.md b/docs/Plugins.md new file mode 100644 index 0000000..65a06d9 --- /dev/null +++ b/docs/Plugins.md @@ -0,0 +1,4 @@ +[Table of Contents](toc.md) + +# Plugins # +Plugins can be added by creating a directory called _plugins_ in the software folder and placing the plugin (.jar) in that folder. \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index ff70e32..3c2496d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -54,4 +54,4 @@ in the source directory. The built library can be found under build/distribution ## 3 Help Resources ## See the latest version of the written documentation on - https://github.com/brailleapps/braille-utils-cli/wiki + https://github.com/brailleapps/braille-utils-cli diff --git a/docs/SplitPef.md b/docs/SplitPef.md new file mode 100644 index 0000000..b9d4de9 --- /dev/null +++ b/docs/SplitPef.md @@ -0,0 +1,8 @@ +[Table of Contents](toc.md) + +# Split a PEF-file # +Split 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. + +Two arguments are required: _path to input file_ and _path to output folder_. \ No newline at end of file diff --git a/docs/TextToPef.md b/docs/TextToPef.md new file mode 100644 index 0000000..2d55c27 --- /dev/null +++ b/docs/TextToPef.md @@ -0,0 +1,45 @@ +[Table of Contents](toc.md) + +# Text to PEF # +Convert 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. + +
+Example:

+java -jar brailleUtils-ui.jar text2pef input.txt output.pef

+
+ +Optional arguments include: + * 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. + +
+Example:

+java -jar brailleUtils-ui.jar text2pef input.txt output.pef -date=2013-01-01

+
+ +## 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. + +
+Example:

+java -jar brailleUtils-ui.jar text2pef input.txt output.pef -mode=nabcc

+
+ +## Duplex ## +Set the duplex property of the resulting file. + +
+Example:

+java -jar brailleUtils-ui.jar text2pef input.txt output.pef -duplex=true

+
\ No newline at end of file diff --git a/docs/UnicodeBraillePatterns.md b/docs/UnicodeBraillePatterns.md index 6085232..e63c897 100644 --- a/docs/UnicodeBraillePatterns.md +++ b/docs/UnicodeBraillePatterns.md @@ -1,3 +1,6 @@ +[Table of Contents](toc.md) + +#Unicode Braille Patterns# Below is a list of braille patterns in Unicode order: ``` 2800 BLANK diff --git a/docs/UsersGuide.md b/docs/UsersGuide.md new file mode 100644 index 0000000..9fb7366 --- /dev/null +++ b/docs/UsersGuide.md @@ -0,0 +1,23 @@ +[Table of Contents](toc.md) + +# Introduction # +This document contains information needed to run the command line user interface contained in the package. Note that this software doesn't target end users directly, but rather developers of user interfaces or braille systems. The functionality in the user interface does not demonstrate the full capability of the package. + +# First Run # +To run the user interface, download and extract the latest release. If you do not have Java installed on your machine, you have to download and install that as well. + +On the command line, navigate to the extracted folder and type: +`java -jar brailleUtils-ui.jar`. Press enter. + +This will bring up a list of applications (or features): + * [emboss](Emboss) + * [text2pef](TextToPef) + * [pef2text](PefToText) + * [validate](ValidatePef) + * [split](SplitPef) + * [merge](MergePef) + * [generate](GeneratePef) + +These are explained in detail in separate sections. +To start one of them, append their name as the first argument, for example: +`java -jar brailleUtils-ui.jar emboss` \ No newline at end of file diff --git a/docs/ValidatePef.md b/docs/ValidatePef.md new file mode 100644 index 0000000..8956718 --- /dev/null +++ b/docs/ValidatePef.md @@ -0,0 +1,14 @@ +[Table of Contents](toc.md) + +# Validate a PEF-file # +Validate a PEF-file. + +One argument is required: _path to input file_ + +Optional arguments include: + * mode + +## Mode ## +Set the validation mode: + * full + * light \ No newline at end of file diff --git a/docs/changes.md b/docs/changes.md index 392cd86..8b554bc 100644 --- a/docs/changes.md +++ b/docs/changes.md @@ -1,5 +1,10 @@ +[Table of Contents](toc.md) + # Changes # +# 1.x.y # +Fixed a problem when optional arguments are placed before required. + ## 1.2.3 ## Added StreamSource to PEFFileCompare. diff --git a/docs/toc.md b/docs/toc.md new file mode 100644 index 0000000..314c2a7 --- /dev/null +++ b/docs/toc.md @@ -0,0 +1,15 @@ +#Table of Contents# + +* [User's Guide](UsersGuide.md) + * Commands + * [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