From 9a179cc049f4acfae5de8f7bf6170819f56878f8 Mon Sep 17 00:00:00 2001 From: Reuben Thomas Date: Sun, 25 Sep 2022 09:45:57 +0200 Subject: 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. --- README | 45 +++++---------------------- configure.ac | 1 + src/.gitignore | 15 +++++---- src/Makefile.am | 2 +- src/enchant-lsmod.1.in | 2 +- src/enchant.1.in | 42 +++---------------------- src/enchant.5.in | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++ 7 files changed, 105 insertions(+), 86 deletions(-) create mode 100644 src/enchant.5.in 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:\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:\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. -- cgit v1.2.1