Improve the documentation

These changes were inspired by issue #311.

Move the documentation on personal wordlists from README into enchant.5, and
the documentation on ordering files from enchant.1 to enchant.5. Add a cross
reference from README to the man page.

7 files changed, 105 insertions, 86 deletions

diff --git a/README b/README
index 2c6df24..204d1da 100644
--- a/README
+++ b/README
@@ -40,46 +40,15 @@ instructions.
 Developers or others wishing to install from a git repository, see HACKING.
 
 
-Personal word lists
--------------------
+Usage
+-----
 
-Personal word lists are simple plain text files with one word per line.
-Lines starting with a hash sign (#) are ignored.
+See the man pages for information on how to use Enchant. In particular,
+information about how to configure which spelling checker to use for each
+language and how to work with personal word lists is in the man page
+enchant(5). To see this man page, in a terminal, give the command:
 
-
-Sharing personal word lists between spell-checkers
---------------------------------------------------
-
-It is possible, and usually safe, to share Enchant’s personal word lists
-with other spelling checkers that use the same format (note that other
-spell-checkers may not support comments!). The spell-checkers known to be
-compatible are Hunspell, Nuspell and Ispell. (Although Enchant does not
-support Ispell as a back-end, it’s still fine to share word lists with it.)
-Other spell-checkers supported by Enchant are either incompatible, or have
-no personal word list mechanism. There may well be yet other spell-checkers,
-unknown to Enchant, that use the same format.
-
-Some applications use Hunspell or Nuspell, but store the personal word list
-under another name or in another location. Firefox is one example. Firefox
-also seems to reorder its word list when updating it; again, this is OK, as
-the result is still in the same format. Anonther example is Thunderbird.
-
-To share word lists with Enchant, find the other spelling checker’s word
-list file, e.g. ~/.hunspell_fr_FR or ~/.config/nuspell/fr_FR, and merge it
-with the corresponding Enchant file, in this case ~/.config/enchant/fr_FR.dic
-(on a GNU or BSD system). Use the following command, replacing ENCHANT-DICT
-and OTHER-DICT with the corresponding dictionary file names:
-
-cat ENCHANT-DICT OTHER-DICT | sort -u > merged.txt
-
-Take a look at merged.txt to check the merge has worked, then
-
-mv merged.txt ENCHANT-DICT
-rm OTHER-DICT
-ln -s OTHER-DICT ENCHANT-DICT
-
-to replace the other dictionary file with a link to the Enchant dictionary,
-again filling in the name of the dictionary files.
+    man 5 enchant
 
 
 Bug reports and development
diff --git a/configure.ac b/configure.ac
index 30726d1..1464a4f 100644
--- a/configure.ac
+++ b/configure.ac
@@ -241,6 +241,7 @@ src/libenchant.rc
 src/Makefile
 src/enchant.1
 src/enchant-lsmod.1
+src/enchant.5
 providers/Makefile
 tests/Makefile
 tests/enchant_providers/Makefile
diff --git a/src/.gitignore b/src/.gitignore
index fb5eaca..fad1440 100644
--- a/src/.gitignore
+++ b/src/.gitignore
@@ -1,10 +1,9 @@
-/enchant-[0-9]
-/enchant.1
-/enchant-[0-9].1
-/enchant.1.in
-/enchant-[0-9].exe
-/enchant-lsmod-[0-9]
-/enchant-lsmod-[0-9].exe
+/enchant-[1-9]
+/enchant.[15]
+/enchant-[1-9].1
+/enchant-[1-9].exe
+/enchant-lsmod-[1-9]
+/enchant-lsmod-[1-9].exe
 /enchant-lsmod.1
-/enchant-lsmod-[0-9].1
+/enchant-lsmod-[1-9].1
 /libenchant.rc
diff --git a/src/Makefile.am b/src/Makefile.am
index 7c89b1c..b40b174 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -23,7 +23,7 @@ noinst_HEADERS = debug.h
 
 pkgdata_DATA = enchant.ordering
 
-dist_man_MANS = enchant-@ENCHANT_MAJOR_VERSION@.1 enchant-lsmod-@ENCHANT_MAJOR_VERSION@.1
+dist_man_MANS = enchant-@ENCHANT_MAJOR_VERSION@.1 enchant-lsmod-@ENCHANT_MAJOR_VERSION@.1 enchant.5
 
 edit = sed \
 	-e 's|DATADIR|$(datadir)|g'
diff --git a/src/enchant-lsmod.1.in b/src/enchant-lsmod.1.in
index b1373a2..4f64721 100644
--- a/src/enchant-lsmod.1.in
+++ b/src/enchant-lsmod.1.in
@@ -1,6 +1,6 @@
 .TH ENCHANT-LSMOD-@ENCHANT_MAJOR_VERSION@ 1 "August 2017"
 .SH NAME
-Enchant \- list provider and dictionary information
+enchant-lsmod \- list provider and dictionary information
 .SH SYNOPSIS
 .ll +8
 .B enchant-lsmod-@ENCHANT_MAJOR_VERSION@
diff --git a/src/enchant.1.in b/src/enchant.1.in
index 3b85fc5..31c400a 100644
--- a/src/enchant.1.in
+++ b/src/enchant.1.in
@@ -31,46 +31,12 @@ display help and exit
 .TP
 .B "\-v"
 display version information and exit
-.SH ENCHANT ORDERING FILE
-Enchant uses global and per-user ordering files named \fIenchant.ordering\fR
-to decide which spelling provider to use for particular languages.
-The per-user file takes precedence.
-.PP
-The ordering file takes the form \fIlanguage_tag:<comma-separated list of spelling
-providers>\fR. The language tag is an IETF BCP 47 language tag, typically of the form \fICOUNTRY_LANGUAGE\fR.
-To see what dictionaries are available, run \fIenchant-lsmod-@ENCHANT_MAJOR_VERSION@\fR. '*' is
-used to mean "use this ordering for all languages, unless instructed otherwise." For example:
-.PP
-*:aspell,hunspell,nuspell
-.br
-en:aspell,hunspell,nuspell
-.br
-en_GB:hunspell,nuspell,aspell
-.br
-fr:hunspell,nuspell,aspell
 .SH FILES AND DIRECTORIES
-Enchant looks in the following places for files, in decreasing order of precedence:
-.TP
-\fIENCHANT_CONFIG_DIR\fR
-(If the environment variable is set.)
-.TP
-\fIXDG_CONFIG_HOME/enchant\fR (non-Windows systems)
-Default: \fI~/.config/enchant\fR
-.TP
-\fICSIDL_LOCAL_APPDATA\\enchant\fR (Windows systems)
-Default: \fIC:\\Documents and Settings\\\fRusername\fI\\Local Settings\\Application Data\\enchant
-.TP
-\fIDATADIR/enchant\fR
-(Or the equivalent location relative to the enchant library for a relocatable build.)
-.PP
-Dictionaries are looked for in a subdirectory with the same name as the
-provider; for example, \fIDATADIR/enchant/hunspell\fR and
-\fI~/.config/enchant/hunspell\fR.
-.PP
-Some providers may also look in a standard system directory for their
-dictionaries; the hunspell provider can be configured to do so at build
-time.
+See
+.BR enchant (5)
+for details of configuration files and personal word lists.
 .SH "SEE ALSO"
+.BR enchant-@ENCHANT_MAJOR_VERSION@ (5),
 .BR aspell (1),
 .BR enchant-lsmod-@ENCHANT_MAJOR_VERSION@ (1)
 .SH "AUTHOR"
diff --git a/src/enchant.5.in b/src/enchant.5.in
new file mode 100644
index 0000000..b82f866
--- /dev/null
+++ b/src/enchant.5.in
@@ -0,0 +1,84 @@
+.TH ENCHANT 5
+.SH NAME
+Enchant \- enchant ordering files and personal word lists
+.SH ORDERING FILE
+Enchant uses global and per-user ordering files named \fIenchant.ordering\fR
+to decide which spelling provider to use for particular languages.
+The per-user file takes precedence.
+.PP
+The ordering file takes the form \fIlanguage_tag:<comma-separated list of spelling
+providers>\fR. The language tag is an IETF BCP 47 language tag, typically of the form \fICOUNTRY_LANGUAGE\fR.
+To see what dictionaries are available, run \fIenchant-lsmod-@ENCHANT_MAJOR_VERSION@\fR. '*' is
+used to mean "use this ordering for all languages, unless instructed otherwise." For example:
+.PP
+*:aspell,hunspell,nuspell
+.br
+en:aspell,hunspell,nuspell
+.br
+en_GB:hunspell,nuspell,aspell
+.br
+fr:hunspell,nuspell,aspell
+.SH PERSONAL WORD LISTS
+Personal word lists are simple plain text files with one word per line.
+Lines starting with a hash sign '#' are ignored.
+.SS SHARING PERSONAL WORD LISTS BETWEEN SPELL-CHECKERS
+It is possible, and usually safe, to share Enchant's personal word lists
+with other spelling checkers that use the same format (note that other
+spell-checkers may not support comments!). The spell-checkers known to be
+compatible are Hunspell, Nuspell and Ispell. (Although Enchant does not
+support Ispell as a back-end, it's still fine to share word lists with it.)
+Other spell-checkers supported by Enchant are either incompatible, or have
+no personal word list mechanism. There may well be yet other spell-checkers,
+unknown to Enchant, that use the same format.
+.PP
+Some applications use Hunspell or Nuspell, but store the personal word list
+under another name or in another location. Firefox is one example. Firefox
+also seems to reorder its word list when updating it; again, this is OK, as
+the result is still in the same format. Anonther example is Thunderbird.
+.PP
+To share word lists with Enchant, find the other spelling checker's word
+list file, e.g. \fI~/.hunspell_fr_FR\fR or \fI~/.config/nuspell/fr_FR\fR,
+and merge it with the corresponding Enchant file, in this case
+\fI~/.config/enchant/fr_FR.dic\fR. Use the following command, replacing
+\fIENCHANT-DICT\fR and \fIOTHER-DICT\fR with the corresponding dictionary
+file names:
+.PP
+cat ENCHANT-DICT OTHER-DICT | sort -u > merged.txt
+.PP
+Take a look at merged.txt to check the merge has worked, then
+.PP
+mv merged.txt ENCHANT-DICT
+.br
+rm OTHER-DICT
+.br
+ln -s OTHER-DICT ENCHANT-DICT
+.PP
+to replace the other dictionary file with a link to the Enchant dictionary,
+again filling in the name of the dictionary files.
+.SH FILES AND DIRECTORIES
+Enchant looks in the following places for files, in decreasing order of precedence:
+.TP
+\fIENCHANT_CONFIG_DIR\fR
+(If the environment variable is set.)
+.TP
+\fIXDG_CONFIG_HOME/enchant\fR (non-Windows systems)
+Default: \fI~/.config/enchant\fR
+.TP
+\fICSIDL_LOCAL_APPDATA\\enchant\fR (Windows systems)
+Default: \fIC:\\Documents and Settings\\\fRusername\fI\\Local Settings\\Application Data\\enchant
+.TP
+\fIDATADIR/enchant\fR
+(Or the equivalent location relative to the enchant library for a relocatable build.)
+.PP
+Dictionaries are looked for in a subdirectory with the same name as the
+provider; for example, \fIDATADIR/enchant/hunspell\fR and
+\fI~/.config/enchant/hunspell\fR.
+.PP
+Some providers may also look in a standard system directory for their
+dictionaries; the hunspell provider can be configured to do so at build
+time.
+.SH "SEE ALSO"
+.BR enchant-@ENCHANT_MAJOR_VERSION@ (1),
+.BR enchant-lsmod-@ENCHANT_MAJOR_VERSION@ (1)
+.SH "AUTHOR"
+Written by Dom Lachowicz and Reuben Thomas.