spelling (13feb13)

git-svn-id: svn://tug.org/texlive/trunk@29102 c570f23f-e606-0410-a88d-b1316a301751

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
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
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