summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-02-13 23:22:28 +0000
committerKarl Berry <karl@freefriends.org>2013-02-13 23:22:28 +0000
commit469e41303044d048cec1de7cf5d814b9f2b5e52e (patch)
tree6c5aefbb73aa821e171c8beef63723044c2c5476 /Master/texmf-dist/doc
parenta19e8fc23c74d8bb5f11c0fb7c135ab7e108c36a (diff)
spelling (13feb13)
git-svn-id: svn://tug.org/texlive/trunk@29102 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r--Master/texmf-dist/doc/lualatex/spelling/CHANGES27
-rw-r--r--Master/texmf-dist/doc/lualatex/spelling/spelling-doc.pdfbin89685 -> 0 bytes
-rw-r--r--Master/texmf-dist/doc/luatex/spelling/CHANGES47
-rw-r--r--Master/texmf-dist/doc/luatex/spelling/LICENSE (renamed from Master/texmf-dist/doc/lualatex/spelling/LICENSE)0
-rw-r--r--Master/texmf-dist/doc/luatex/spelling/README (renamed from Master/texmf-dist/doc/lualatex/spelling/README)4
-rw-r--r--Master/texmf-dist/doc/luatex/spelling/spelling-doc.bad (renamed from Master/texmf-dist/doc/lualatex/spelling/spelling-doc.bad)3
-rw-r--r--Master/texmf-dist/doc/luatex/spelling/spelling-doc.pdfbin0 -> 106933 bytes
-rw-r--r--Master/texmf-dist/doc/luatex/spelling/spelling-doc.tex (renamed from Master/texmf-dist/doc/lualatex/spelling/spelling-doc.tex)331
8 files changed, 314 insertions, 98 deletions
diff --git a/Master/texmf-dist/doc/lualatex/spelling/CHANGES b/Master/texmf-dist/doc/lualatex/spelling/CHANGES
deleted file mode 100644
index 168e44919ea..00000000000
--- a/Master/texmf-dist/doc/lualatex/spelling/CHANGES
+++ /dev/null
@@ -1,27 +0,0 @@
-This material is subject to the LaTeX Project Public License. See
-<http://www.latex-project.org/lppl/> for the details of that license.
-
-
-
-### v0.2 (2012-12-04)
-
-Fixes:
-
- * File `spelling.lua` could not be found by LaTeX style file
- ([GitHub issue 14][#14]).
-
-[#14]: https://github.com/sh2d/spelling/issues/14
-
-
-### v0.1 (2012-11-30)
-
-First upload to CTAN.
-
-
-
-<!--
-%%% Local Variables:
-%%% coding: utf-8
-%%% mode: markdown
-%%% End:
--->
diff --git a/Master/texmf-dist/doc/lualatex/spelling/spelling-doc.pdf b/Master/texmf-dist/doc/lualatex/spelling/spelling-doc.pdf
deleted file mode 100644
index 94a23f8a048..00000000000
--- a/Master/texmf-dist/doc/lualatex/spelling/spelling-doc.pdf
+++ /dev/null
Binary files differ
diff --git a/Master/texmf-dist/doc/luatex/spelling/CHANGES b/Master/texmf-dist/doc/luatex/spelling/CHANGES
new file mode 100644
index 00000000000..24dd549ca4b
--- /dev/null
+++ b/Master/texmf-dist/doc/luatex/spelling/CHANGES
@@ -0,0 +1,47 @@
+This material is subject to the LaTeX Project Public License. See
+<http://www.latex-project.org/lppl/> for the details of that license.
+
+
+### v0.3 (2013-02-12)
+
+New:
+
+ * [LanguageTool][lt] support: LanguageTool error reports in the XML
+ format can be parsed for spelling errors (with the help of the
+ [LuaXML][luaxml] package). LanguageTool is a cross-platform style
+ and grammar checker.
+
+[lt]: http://www.languagetool.org/
+[luaxml]: http://www.ctan.org/pkg/luaxml
+
+Changes:
+
+ * Default file names used by the package have been changed:
+
+ <jobname>.spb => <jobname>.spell.bad
+ <jobname>.spg => <jobname>.spell.good
+ <jobname>.txt => <jobname>.spell.txt
+
+
+### v0.2 (2012-12-04)
+
+Fixes:
+
+ * File `spelling.lua` could not be found by LaTeX style file
+ ([GitHub issue 14][#14]).
+
+[#14]: https://github.com/sh2d/spelling/issues/14
+
+
+### v0.1 (2012-11-30)
+
+First upload to CTAN.
+
+
+
+<!--
+%%% Local Variables:
+%%% coding: utf-8
+%%% mode: markdown
+%%% End:
+-->
diff --git a/Master/texmf-dist/doc/lualatex/spelling/LICENSE b/Master/texmf-dist/doc/luatex/spelling/LICENSE
index 22443139013..22443139013 100644
--- a/Master/texmf-dist/doc/lualatex/spelling/LICENSE
+++ b/Master/texmf-dist/doc/luatex/spelling/LICENSE
diff --git a/Master/texmf-dist/doc/lualatex/spelling/README b/Master/texmf-dist/doc/luatex/spelling/README
index 204b5471bd2..6489095d30c 100644
--- a/Master/texmf-dist/doc/lualatex/spelling/README
+++ b/Master/texmf-dist/doc/luatex/spelling/README
@@ -7,8 +7,8 @@ This material is subject to the LaTeX Project Public License. See
Package name: spelling
Summary description: Aid spell-checking LuaTeX documents.
-Version: v0.2
-Date: 2012-12-04
+Version: v0.3
+Date: 2013-02-12
License: [LPPL v1.3c](http://www.latex-project.org/lppl/lppl-1-3c.html)
Maintenance status: maintained
Current maintainer: Stephan Hennig, <sh2d@arcor.de>
diff --git a/Master/texmf-dist/doc/lualatex/spelling/spelling-doc.bad b/Master/texmf-dist/doc/luatex/spelling/spelling-doc.bad
index 4904a447e82..c5cc1638119 100644
--- a/Master/texmf-dist/doc/lualatex/spelling/spelling-doc.bad
+++ b/Master/texmf-dist/doc/luatex/spelling/spelling-doc.bad
@@ -1,5 +1,6 @@
-packgae
Ther
+fotenoot
+misspelllings
spellling
foo’s
incorect
diff --git a/Master/texmf-dist/doc/luatex/spelling/spelling-doc.pdf b/Master/texmf-dist/doc/luatex/spelling/spelling-doc.pdf
new file mode 100644
index 00000000000..c1cacbf3c7f
--- /dev/null
+++ b/Master/texmf-dist/doc/luatex/spelling/spelling-doc.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/lualatex/spelling/spelling-doc.tex b/Master/texmf-dist/doc/luatex/spelling/spelling-doc.tex
index b2e45937316..7a0c1bf3af6 100644
--- a/Master/texmf-dist/doc/lualatex/spelling/spelling-doc.tex
+++ b/Master/texmf-dist/doc/luatex/spelling/spelling-doc.tex
@@ -1,5 +1,5 @@
%%% spelling-doc.sty
-%%% Copyright 2012 Stephan Hennig
+%%% Copyright 2012, 2013 Stephan Hennig
%%
%% This work may be distributed and/or modified under the conditions of
%% the LaTeX Project Public License, either version 1.3 of this license
@@ -59,7 +59,7 @@ basicstyle=\ttfamily,
\newcommand*{\lpie}{\latinphrase{i.\,e.}\xspace}
\begin{document}
\author{Stephan Hennig\thanks{sh2d@arcor.de}}
-\title{\pkg\thanks{This document describes the \pkg\ packgae v0.2.}}
+\title{\pkg\thanks{This document describes the \pkg\ package v0.3.}}
\maketitle
@@ -88,7 +88,12 @@ basicstyle=\ttfamily,
\section{Introduction}
\label{sec:intro}
-Ther are three main approaches to spell-checking \TeX\ documents:
+Ther%
+\footnote{A fotenoot containing misspelllings. But note how
+ `misspelllings' currently slips through due to punctuation. Some
+ annoying bugs are listed in \autoref{sec:bugs}.}
+%
+are three main approaches to spell-checking \TeX\ documents:
\begin{enumerate}
@@ -106,10 +111,11 @@ package follows the third approach, providing some unique features:
\begin{itemize}
-\item When extracting text from typeset \acr{dvi}, \acr{ps} or \acr{pdf}
- files, hyphenation has to be switched off during the \TeX\ run to
- avoid lots of false positives being reported by the spell-checker.
- That is, one doesn't work on the original document.
+\item In traditional solutions, text is extracted from typeset
+ \acr{dvi}, \acr{ps} or \acr{pdf} files, including hyphenated words.
+ Therefore, to avoid lots of false positives being reported by the
+ spell-checker, hyphenation has to be switched off during the \TeX\
+ run. So, one doesn't work on the original document any more.
In contrast to that, the \pkg\ package works transparently on the
original |.tex| source file. Text is extracted \emph{during}
@@ -127,13 +133,14 @@ package follows the third approach, providing some unique features:
\section{Usage}
\label{sec:usage}
-The \pkg\ package requires the Lua\TeX\ engine. Currently, only the
-\LaTeX\ format is supported. \emph{The package consists of Lua modules
- that do the actual work. The \LaTeX\ package is effectively a wrapper
- around the modules' Lua-API. Implementing support for other formats
- shouldn't be too difficult. Since the author is a \LaTeX-only user,
- support has to be contributed by, \lpeg, you. By the way, the \LaTeX\
- package needs some polishing, too. Contributions are welcome!}
+The \pkg\ package requires the Lua\TeX\ engine. All functionality of
+the package is implemented in Lua. The \LaTeX\ interface, which is
+described below, is effectively a wrapper around the Lua interface.
+
+\emph{Implementing such wrappers for other formats shouldn't be too
+ difficult. The author is a \LaTeX-only user, though, and therefore
+ grateful for contributions. By the way, the \LaTeX\ package needs
+ some polishing, too, \lpeg, a key-value interface is desirable.}
\subsection{Work-flow}
@@ -145,33 +152,34 @@ The work-flow of the \pkg\ package is as follows:
\item After the package is loaded in the preamble of a |.tex| source
file via °\usepackage{spelling}°, a list of bad spellings is read from
- a file named \descr{jobname}|.spb|, if that file exists.
+ a file named \descr{jobname}|.spell.bad|, if that file exists.
\item During the Lua\TeX\ run, text is extracted from pages and all
words are checked against the list of bad spellings. Words with a
known incorrect spelling are highlighted in \acr{pdf} output.
\item At the end of the Lua\TeX\ run, in addition to the \acr{pdf} file,
- a text file is written, named \descr{jobname}|.txt|, by default. The
- text file should contain most of the text of the original document.
+ a text file is written, named \descr{jobname}|.spell.txt|, by default.
+ The text file should contain most of the text of the original
+ document.
\item The text file is then checked by your favourite spell-checker
application, \lpeg, Aspell or Hunspell. The spell-checker should be
able to write a list of bad spellings to a file. Otherwise, visual
- feedback in \acr{pdf} output won't work. The file should preferably
- be named \descr{jobname}|.spb|, but any other file name works just as
- well.
+ feedback in \acr{pdf} output won't work. Preferably, the file is
+ named \descr{jobname}|.spell.bad|, but any other file name works just
+ as well.
\item Now, there are two ways to proceed:
\begin{enumerate}
\item Visually minded people may just compile their document a second
- time. This time, file \descr{jobname}|.spb| is read-in again and
- the words with incorrect spelling found by the spell-checker should
- now be highlighted in \acr{pdf} output. Checking the \acr{pdf}
- file, the necessary corrections to the |.tex| source file can be
- applied.
+ time. This time, file \descr{jobname}|.spell.bad| is read-in again
+ and the words with incorrect spelling found by the spell-checker
+ should now be highlighted in \acr{pdf} output. Checking the
+ \acr{pdf} file, the necessary corrections to the |.tex| source file
+ can be applied.
\item If you're not interested in visual feedback or if your
spell-checker doesn't provide a non-interactive mode, you can as
@@ -190,32 +198,36 @@ The work-flow of the \pkg\ package is as follows:
\subsection{Word lists}
\label{sec:wordlists}
-As described above, if a file \descr{jobname}|.spb| exists, it is loaded
-by the \pkg\ package. The words found in the file are stored in an
-internal list of bad spellings and are later used for highlighting
-spelling mistakes in \acr{pdf} output. Words from additional files can
-be appended to the internal list of bad spellings with the
-\macro{spellingreadbad} command. Argument is a file name. The format
-of a word list file is one word per line. The same word may occur
-multiple times. The file must be in the \acr{utf-8} encoding.
-
-In addition to file \descr{jobname}|.spb|, a second file
-\descr{jobname}|.spg| is read, if that file exists. The words found in
-that file are stored in an internal list of good spellings. Words in
-the Lua\TeX\ document are only considered spelling mistakes if they
-occur in the list of bad spellings, but not in the list of good
-spellings. That is, words in the list of good spellings are never
-highlighted in \acr{pdf} output. The list of good spellings can be used
-to deal with false positives (words incorrectly reported as bad
-spellings by the spell-checker). Words from additional files can be
-appended to the internal list of good spellings with the
-\macro{spellingreadgood} command. Argument is a file name. File format
-is one word per line. The same word may occur multiple times. The file
-must be in the \acr{utf-8} encoding.
-
-Note, most spell-checkers provide means to deal with unknown words via
-additional dictionaries. It is recommended to configure your
-spell-checker to report as few false positives as possible.
+As described above, if a file \descr{jobname}|.spell.bad| exists, it is
+loaded by the \pkg\ package. The words found in the file are stored in
+an internal list of bad spellings and are later used for highlighting
+spelling mistakes in \acr{pdf} output.
+
+Additionally, a second file \descr{jobname}|.spell.good| is read, if
+that file exists. The words found in that file are stored in an
+internal list of good spellings. Words in the list of good spellings
+are never highlighted in \acr{pdf} output. That is, words in the
+Lua\TeX\ document are only considered spelling mistakes if they occur in
+the list of bad spellings, but not in the list of good spellings. The
+list of good spellings can be used to deal with false positives (words
+incorrectly reported as bad spellings by the spell-checker).
+
+Words from additional files can be appended to the internal lists of bad
+and good spellings with the \macro{spellingreadbad} and
+\macro{spellingreadgood} commands. Argument to both macros is a file
+name. File format is one word per line. Letter case is significant.
+The file must be in the \acr{utf-8} encoding. As an example, the
+command
+
+\begin{lstlisting}[language={[LaTeX]TeX}]
+\spellingreadgood{myproject.whitelist}
+\end{lstlisting}
+%
+reads words from a file |myproject.whitelist| and adds them to the list
+of good spellings. Note, most spell-checkers provide means to deal with
+unknown words via additional dictionaries. It is recommended to
+configure your spell-checker to report as few false positives as
+possible.
\subsection{Highlighting spellling mistakes}
@@ -283,17 +295,17 @@ output is enabled, by default.
\paragraph{File name} \hspace{0pt plus 5em} Text output file name can be
configured via command \macro{spellingoutputname}. Argument is the new
-file name. Default text output file name is \descr{jobname}|.txt|.
-
-\paragraph{Line length} In text output, paragraphs can either be broken
-into lines of a fixed length or paragraph can be put on a single line.
-The behaviour can be controlled via command
-\macro{spellingoutputlinelength}. Argument is a number. If the number
-is smaller than~1, paragraphs are put on a single line. For larger
-arguments, the number specifies the maximum line length. Note, lines
-are broken at spaces only. Words longer than maximum line length are
-put on a single line exceeding maximum line length. Default line length
-is~72.
+file name. Default text output file name is
+\descr{jobname}|.spell.txt|.
+
+\paragraph{Line length} In text output, paragraphs can either be put on
+a single line or broken into lines of a fixed length. The behaviour can
+be controlled via command \macro{spellingoutputlinelength}. Argument is
+a number. If the number is~0 or less, paragraphs are put on a single
+line. For larger arguments, the number specifies the maximum line
+length. Note, lines are broken at spaces only. Words longer than
+maximum line length are put on a single line exceeding maximum line
+length. Default line length is~72.
\paragraph{Line ending convention} The end-of-line (\acr{eol}) character
in text output can be configured via command \macro{spellingoutputeol}.
@@ -425,6 +437,190 @@ table rows). If the argument is~2, a blank line is inserted before and
after every table cell. By default, no blank lines are inserted.
+\section{LanguageTool support}
+\label{sec:languagetool}
+
+Installing spell-checkers and dictionaries can be a difficult task if
+there are no pre-built packages available for an architecture. That's
+one reason the \pkg\ package is rather spell-checker agnostic and the
+manual doesn't recommend a particular spell-checker application.
+Another reason is, there's no best spell-checker. The only
+recommendation the author makes is not to trust in one spell-checker,
+but to use multiple spell-checkers at the same time, with different
+dictionaries or, better yet, different checking engines under the hood.
+
+Among the set of options available, LanguageTool, a style and grammar
+checker%
+\footnote{\url{http://www.languagetool.org/}}
+%
+that can also check spelling since version~1.8, deserves some notice for
+its portability, ease of installation and active development. For these
+reasons, the \pkg\ package provides explicit LanguageTool support.
+LanguageTool uses Hunspell as the spell-checking engine, augmenting
+results with a rule based engine and a morphological analyser (depending
+on the language). The \pkg\ package can parse LanguageTool's error
+reports in the \acr{xml} format, pick those errors that are spelling
+related and use them to highlight bad spellings.%
+\footnote{Support for style and grammar errors found by LanguageTool
+ should be possible, but requires major restructuring of the \pkg\
+ package that won't happen any time soon.}
+
+
+\subsection{Installation}
+\label{sec:lt-installation}
+
+Here are some brief installation instructions for the stand-alone
+version of LanguageTool (tested with LanguageTool~2.0). The stand-alone
+version contains a \acr{gui} as well as a command-line interface. For
+the \pkg\ package, the latter is needed.
+
+\begin{enumerate}
+
+\item LanguageTool is primarily written in Java. Make sure a recent
+ Java Runtime Environment (\acr{jre}) is installed.
+
+\item\label{enum:run-java} Open a command-line and type
+
+\begin{lstlisting}
+java -version
+\end{lstlisting}
+%
+ If you get an error message, find out the full path to the Java
+ executable (called |java.exe| on Windows) for later reference.
+
+\item Download the stand-alone version of LanguageTool (should be a
+ \acr{zip} archive).
+
+\item Uncompress the downloaded archive to a location of your choice.
+
+\item Open a command-line in the directory containing file
+ |LanguageTool.jar| and type
+
+\begin{lstlisting}[escapeinside=°°]
+°\descr{path to}°/java -jar LanguageTool.jar --help
+\end{lstlisting}
+%
+ Prepending the path to the Java executable is optional, depending on
+ the result in step~\ref{enum:run-java}. If you now see a list of
+ LanguageTool's command-line options rush by, all is well.
+
+\item For easier access to LanguageTool, create a small batch script and
+ put that somewhere into the |PATH|.
+
+ \begin{itemize}
+
+ \item For users of Unixoid systems, the script might look like
+
+\begin{lstlisting}[escapeinside=°°]
+#!/bin/sh
+°\descr{path to}°/java -jar °\descr{path to}°/LanguageTool.jar $*
+\end{lstlisting}
+%
+ where \texttt{\descr{path to}} should point to the Java executable
+ (optional) and file |LanguageTool.jar| (mandatory). If the script
+ is named |lt.sh|, you should be able to run LanguageTool on the
+ command shell by typing, \lpeg,
+
+\begin{lstlisting}
+sh lt.sh --version
+\end{lstlisting}
+%
+ Don't forget to put the script into the |PATH|! For other ways of
+ making scripts executable, please consult the operating system
+ documentation.
+
+ \item For Windows users, the script might look like
+
+\begin{lstlisting}[escapeinside=°°]
+@echo off
+°\descr{path to}°\java -jar °\descr{path to}°\LanguageTool.jar %*
+\end{lstlisting}
+%
+ where \texttt{\descr{path to}} should point to the Java executable
+ (optional) and file |LanguageTool.jar| (mandatory). If the script
+ is named |lt.bat|, you should be able to run LanguageTool on the
+ command-line by typing, \lpeg,
+
+\begin{lstlisting}
+lt --version
+\end{lstlisting}
+%
+ Don't forget to put the script into the |PATH|!
+
+ \end{itemize}
+
+\end{enumerate}
+
+
+\subsection{Usage}
+\label{sec:lt-usage}
+
+The results of checking a text file with LanguageTool are written to an
+error report, either in a human readable format or in a machine friendly
+\acr{xml} format. The \pkg\ package can only parse the latter format.
+When it was said in \autoref{sec:wordlists} that the \pkg\ package reads
+files \descr{jobname}|.spell.bad| and \descr{jobname}|.spell.good|, if
+they exist, that was not the whole truth. Additionally, a file
+\descr{jobname}|.spell.xml| is read, if it exists. This file should
+contain a LanguageTool error report in the \acr{xml} format. Additional
+LanguageTool \acr{xml} error reports can be loaded via the
+\macro{spellingreadLT} command. Argument is a file name. Macros
+|\spellingreadLT|, |\spellingreadbad| and |\spellingreadgood| can be
+used in combination in a \TeX\ file.
+
+To check a text file and create an error report in the \acr{xml} format,
+LanguageTool can be called on the command-line like this
+\begin{lstlisting}[escapeinside=°°]
+lt °\descr{options}° °\descr{input file}° > °\descr{error report}°
+\end{lstlisting}
+where \texttt{\descr{options}} is a list of options described below,
+\texttt{\descr{input file}} is the text file written by the \pkg\
+package in the first Lua\TeX\ run and \texttt{\descr{error report}} is
+the file containing the error report. Note, how standard output is
+redirected to a file via the |>| operator. By default, LanguageTool
+writes error reports to standard output, that is, the command-line.
+Redirection is a feature most operating systems provide.
+
+\begin{itemize}
+
+\item Option |-l| determines the language (variant) of the file to
+ check. As an example, language variant US English can be selected via
+ |-l en-US|. The full list of languages supported by LanguageTool can
+ be requested via option |--list|.
+
+\item Option |-c| determines the encoding of the input file. Since the
+ text file written by the \pkg\ package is in the \acr{utf-8} encoding,
+ this part should be |-c utf-8|.
+
+\item By default, LanguageTool outputs error reports in a human readable
+ format. The \pkg\ package can only parse error reports in the
+ \acr{xml} format. If the |--api| option is present, LanguageTool
+ outputs \acr{xml} data.
+
+\item Users that don't want to highlight bad spellings, but prefer to
+ study the list of bad spellings themselves, should refer to the |-u|
+ option. But note, that with the latter option present, LanguageTool
+ doesn't output pure \acr{xml} any more, even if the |--api| option is
+ present. Make sure such error reports aren't read by the \pkg\
+ package.
+
+\item If the |--help| option is present, LanguageTool shows more
+ information about command-line options.
+
+\end{itemize}
+
+As an example, to compile a \LaTeX\ file |myletter.tex| written in
+French that uses the \pkg\ package with standard settings to highlight
+bad spellings and to use LanguageTool as a spell-checker, the following
+commands should be typed on the command-line:
+
+\begin{lstlisting}
+lualatex myproject
+lt --api -c utf-8 -l fr myletter.spell.txt > myletter.spell.xml
+lualatex myproject
+\end{lstlisting}
+
+
\section{Bugs}
\label{sec:bugs}
@@ -457,16 +653,15 @@ The most user-visible issues are listed below:
(\href{https://github.com/sh2d/spelling/issues/7}{issue~7}).
\item Punctuation characters are currently not stripped from words.
- If the list of bad spellings contains an entry, say,
- \emph{incorect}, and the text contains that spelling directly
- followed by a comma, a quotation mark \lpetc, the incorect spelling
- is not highlighted
+ For that reason, misspellings of words with leading or trailing
+ punctuation will currently slip through. This affects at least one
+ word per sentence, the last one
(\href{https://github.com/sh2d/spelling/issues/8}{issue~8}).
\item The first word starting right after an |hlist|, \lpeg, the first
word within an |\mbox|, is never highlighted. It is extracted and
- written to the text file, though
- (\href{https://github.com/sh2d/spelling/issues/6}{issue~6}).
+ written to the text file, though. This might affect acronyms, names
+ \lpetc (\href{https://github.com/sh2d/spelling/issues/6}{issue~6}).
\item Bad spellings that are hyphenated at a page break are not
highlighted