summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/lualatex/spelling/spelling-doc.tex
blob: b2e4593731698c3e57ada4a8b17fdd1ebf3ac2c4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
%%% spelling-doc.sty
%%% Copyright 2012 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
%% or (at your option) any later version.  The latest version of this
%% license is in http://www.latex-project.org/lppl.txt
%% and version 1.3 or later is part of all distributions of LaTeX
%% version 2005/12/01 or later.
%%
%% See file README for more information.
%%
\documentclass[11pt]{article}
\usepackage{fontspec}
\defaultfontfeatures{Ligatures=TeX}
\usepackage{multicol}
\usepackage{listings}
\lstset{
  basicstyle=\ttfamily,
  columns=spaceflexible,
}
% Short-cut for non-language code snippets.
\lstMakeShortInline\|
% Short-cut for LaTeX code snippets.
\lstMakeShortInline[
language={[LaTeX]TeX},
basicstyle=\ttfamily,
]°
\usepackage{xspace}
\usepackage{array}
\usepackage{booktabs}
\usepackage[latin, UKenglish]{babel}
\usepackage[rgb, x11names]{xcolor}
\usepackage{hyperref}
\hypersetup{
  pdftitle={spelling},
  pdfauthor={Stephan Hennig},
  pdfkeywords={spell-checking, spelling, TeX, LuaTeX}
}
\hypersetup{
  english,% For \autoref.
  pdfstartview={XYZ null null null},% Zoom factor is determined by viewer.
  colorlinks,
  linkcolor=RoyalBlue3,
  urlcolor=Chocolate4,
  citecolor=DeepPink2
}
\usepackage{spelling}
\spellingreadbad{\jobname.bad}
\newcommand*{\pkg}{\textsf{spelling}}
\newcommand*{\acr}[1]{\mbox{\scshape#1}}
\newcommand*{\descr}[1]{〈\emph{#1}〉}
\newcommand*{\cmd}[1]{\mbox{\ttfamily\textbackslash#1}}
\newcommand*{\macro}[1]{\cmd{#1}\marginpar{\cmd{#1}}}
\newcommand*{\latinphrase}[1]{\foreignlanguage{latin}{\emph{#1}}}
\newcommand*{\lpcf}{\latinphrase{cf.}\xspace}
\newcommand*{\lpeg}{\latinphrase{e.\,g.}\xspace}
\newcommand*{\lpetc}{\latinphrase{etc.}\xspace}
\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.}}
\maketitle


\begin{abstract}
  This package aids spell-checking of \TeX\ documents compiled with the
  Lua\TeX\ engine.  It can give visual feedback in \acr{pdf} output
  similar to \acr{wysiwyg} word processors.  The package relies on an
  external spell-checker application to check spelling of a text file
  and to output a list of bad spellings.  The package should work with
  most spell-checkers, even dumb, \TeX-unaware ones.

  \emph{Warning!  This package is in a very early state.  Everything may
    change!}
\end{abstract}

\begin{multicols}{2}
\small
% Set toc entries ragged right.  Trick taken from tocloft.pdf.
\makeatletter
\renewcommand{\@tocrmarg}{2.55em plus1fil}
\makeatother
\tableofcontents
\end{multicols}


\section{Introduction}
\label{sec:intro}

Ther are three main approaches to spell-checking \TeX\ documents:

\begin{enumerate}

\item checking spelling in the |.tex| source file,

\item converting a |.tex| file to another format, for which a proved
  spell-checking solution exists,

\item checking spelling after a |.tex| file has been processed by \TeX.

\end{enumerate}

All of these approaches have their strengths and weaknesses.  This
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.

  In contrast to that, the \pkg\ package works transparently on the
  original |.tex| source file.  Text is extracted \emph{during}
  typesetting, after Lua\TeX\ has applied its catcode and macro
  machinery, but before hyphenation takes place.

\item The \pkg\ package can highlight words with known incorrect
  spelling in \acr{pdf} output, giving visual feedback similar to
  \acr{wysiwyg} word processors.%
  \footnote{Currently, only colouring words is implemented.}

\end{itemize}


\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!}


\subsection{Work-flow}
\label{sec:work-flow}

The work-flow of the \pkg\ package is as follows:

\begin{enumerate}

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

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

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

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

  \item If you're not interested in visual feedback or if your
    spell-checker doesn't provide a non-interactive mode, you can as
    well apply the necessary corrections directly to the |.tex| source
    file(s), either interactively, during the spell-checker run, or by
    looking at the final list of bad spellings in an editor (whatever
    file it was saved to).  That way, the benefit of this package is,
    that spell-checker input has already been processed by Lua\TeX, but
    contains no hyphenated words.

  \end{enumerate}

\end{enumerate}


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


\subsection{Highlighting spellling mistakes}
\label{sec:highlight}

\paragraph{Enabling/disabling} Highlighting spelling mistakes (words
with known incorrect spelling) in \acr{pdf} output can be toggled on and
off with command \macro{spellinghighlight}.  If the argument is |on|,
highlighting is enabled.  For other arguments, highlighting is disabled.
Highlighting is enabled, by default.

\paragraph{Colour} The colour used for highlighting bad spellings can be
determined by command \cmd{spellinghighlightcolor}.  Argument is a
colour statement in the \acr{pdf} language.  As an example, the colour
red in the \acr{rgb} colour space is represented by the statement %
|1 0 0 rg|.  In the \acr{cmyk} colour space, a reddish colour is
represented by |0 1 1 0 k|.  Default colour used for highlighting is %
|1 0 0 rg|, \lpie, red in the \acr{rgb} colour space.  \emph{Warning:
  There's currently no error checking.  Make sure, you're applying a
  valid PDF colour statement!}


\subsection{Text output}
\label{sec:textoutput}

\paragraph{Text file} After loading the \pkg\ package, at the end of the
Lua\TeX\ run, a text file is written that contains most of the document
text.  The text file is no close text rendering of the typeset document,
but serves as input for your favourite spell-checker application.  It
contains the document text in a simple format: paragraphs separated by
blank lines.  A paragraph is anything that, during typesetting, starts
with a |local_par| whatsit node in the node list representing a typeset
page of the original document, \lpeg, paragraphs in running text,
footnotes, marginal notes, (in-lined) °\parbox° commands or cells from
°p°-like table columns \lpetc

Paragraphs consist of words separated by spaces.  A word is the textual
representation of a chain of consecutive nodes of type |glyph|, |disc|
or |kern|.  Boxes are processed transparently.  That is, the \pkg\
package (highly imperfectly) tries to recognise as a single word what in
typeset output looks like a single word.  As an example, the \LaTeX\
code

\begin{center}
  \begin{tabular}{c}
\begin{lstlisting}[language={[LaTeX]TeX}]
foo\mbox{'s bar}s
\end{lstlisting}
  \end{tabular}
\end{center}
which is typeset as

\begin{center}
  foo\mbox{'s bar}s
\end{center}
is considered two words \textit{foo's} and \textit{bars}, instead of the
four words \textit{foo}, \textit{'s}, \textit{bar} and~\textit{s}.%
\footnote{This document has been compiled with a custom list of bad
  spellings, which is why the word \emph{foo's} should be highlighted.}

\paragraph{Enabling/disabling} Text output can be toggled on and off
with command \macro{spellingoutput}.  If the argument is |on|, text
output is enabled.  For other arguments, text output is disabled.  Text
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.

\paragraph{Line ending convention} The end-of-line (\acr{eol}) character
in text output can be configured via command \macro{spellingoutputeol}.
Argument is an arbitrary sequence of characters in the \acr{utf-8}
encoding.

Well, things are a bit more complicated, because in Lua\TeX, as in the
original \TeX, some characters are treated special.  To keep Lua\TeX\
from messing with our \acr{eol} characters in the input, we need to set
their category codes accordingly.  As an example, to set \acr{eol}
character to follow \acr{dos} line ending convention (carriage return
followed by line feed, \TeX\ notation |^^M^^J|), the following code can
be used:

\begin{lstlisting}[language={[LaTeX]TeX}]
\begingroup
\catcode`\^^J=12% make line feed and carriage return
\catcode`\^^M=12% of category Other
\spellingoutputeol{^^M^^J}
\endgroup
\end{lstlisting}
%
For the \acr{unix} line ending convention (a single line feed), just
leave out |^^M| in the argument to |\spellingoutputeol|.

Default line ending convention depends on the operating system
determined by Lua\TeX.  If |os.type| is either |windows| or |msdos|,
\acr{dos} line ending convention is used.  Otherwise \acr{unix} line
ending convention is used.


\subsection{Text extraction}
\label{sec:textextraction}

\paragraph{Enabling/disabling} Text extraction can be enabled and
disabled in the document via command \macro{spellingextract}.  If the
argument is |on|, text extraction is enabled.  For other arguments, text
extraction is disabled.  The command should be used in vertical mode,
\lpie, outside paragraphs.  If text extraction is disabled in the
document preamble, an empty text file is written at the end of the
Lua\TeX\ run.  Text extraction is enabled, by default.

Note, text extraction and visual feedback are orthogonal features.  That
is, if text extraction is disabled for part of a document, \lpeg, a long
table, words with a known incorrect spelling are still highlighted in
that part.


\subsection{Code point mapping}
\label{sec:cp-mapping}

As explained in \autoref{sec:textoutput}, the text file written at the
end of the Lua\TeX\ run is in the \acr{utf-8} encoding.  Unicode
contains a wealth of code points with a special meaning, such as
ligatures, alternative letters, symbols \lpetc Unfortunately, not all
spell-checker applications are smart enough to correctly interpret all
Unicode code points that may occur in a document.  For that reason, a
code point mapping feature has been implemented that allows for mapping
certain Unicode code points that may appear in a node list to arbitrary
strings in text output.  A typical example is to map ligatures to the
characters corresponding to their constituting letters.  The default
mappings applied can be found in \autoref{tab:cp-mapping}.

\begin{table}
  \centering

  \begin{tabular}{>{\ttfamily}l>{\ttfamily}l>{\ttfamily}l}
    \normalfont Unicode name & \normalfont code point & \normalfont target characters\\
    \addlinespace
    \toprule
    \addlinespace

    LATIN CAPITAL LIGATURE IJ & 0x0132 & IJ\\
    LATIN SMALL LIGATURE IJ & 0x0133 & ij\\
    LATIN CAPITAL LIGATURE OE & 0x0152 & OE\\
    LATIN SMALL LIGATURE OE & 0x0153 & oe\\
    LATIN SMALL LETTER LONG S & 0x017f & s\\
    LATIN CAPITAL LETTER SHARP S & 0x1e9e & SS\\
    LATIN SMALL LIGATURE FF & 0xfb00 & ff\\
    LATIN SMALL LIGATURE FI & 0xfb01 & fi\\
    LATIN SMALL LIGATURE FL & 0xfb02 & fl\\
    LATIN SMALL LIGATURE FFI & 0xfb03 & ffi\\
    LATIN SMALL LIGATURE FFL & 0xfb04 & ffl\\
    LATIN SMALL LIGATURE LONG S T & 0xfb05 & st\\
    LATIN SMALL LIGATURE ST & 0xfb06 & st\\
  \end{tabular}

  \caption{Default code point mappings.}
  \label{tab:cp-mapping}

\end{table}

Additional mappings can be declared by command \macro{spellingmapping}.
This command takes two arguments, a number that refers to the Unicode
code point, and a sequence of arbitrary characters that is the mapping
target.  The code point number must be in a format that can be parsed by
Lua.  The characters must be in the \acr{utf-8} encoding.

New mappings only have effect on the following document text.  The
command should therefore be used in the document preamble.  As an
example, the character |A| can be mapped to |Z| and \latinphrase{vice
  versa} with the following code:

\begin{lstlisting}[language={[LaTeX]TeX}]
\spellingmapping{65}{Z}% A => Z
\spellingmapping{90}{A}% Z => A
\end{lstlisting}

Another command \macro{spellingclearallmappings} can be used to remove
all existing code point mappings.


\subsection{Tables}
\label{sec:tables}

How do tables fit into the simple text file format that has only
paragraphs and blank lines as described in \autoref{sec:textoutput}?
What is a paragraph with regards to tables?  A whole table?  A row?  A
single cell?

By default, only text from cells in °p°(aragraph)-like columns is put on
their own paragraph, because the corresponding node list branches
contain a |local_par| whatsit node (\lpcf \autoref{sec:textoutput}).
The behaviour can be changed with the \macro{spellingtablepar} command.
This command takes as argument a number.  If the argument is~0, the
behaviour is described as above.  If the argument is~1, a blank line is
inserted before and after every table row (but at most once between
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{Bugs}
\label{sec:bugs}

Note, this package is in a very early state.  Expect bugs!  Package
development is hosted at
\href{http://github.com/sh2d/spelling/}{\bfseries GitHub}.  The full
list of known bugs and feature requests can be found in the
\href{http://github.com/sh2d/spelling/issues/}{\bfseries issue tracker}.
New bugs should be reported there.

The most user-visible issues are listed below:

\begin{itemize}

\item There's no support for the Plain \TeX\ or Con\TeX\ formats other
  than the \acr{API} of the package's Lua modules, yet
  (\href{https://github.com/sh2d/spelling/issues/1}{issue~1}).

\item Macros provided by the \LaTeX\ package have very long names.  A
  \emph{key-value} package option interface would be much more
  user-friendly
  (\href{https://github.com/sh2d/spelling/issues/2}{issue~2}).

\item There are a couple of issues with text extraction and highlighting
  incorrect spellings:

  \begin{itemize}

  \item Text in head and foot lines is neither extracted nor highlighted
    (\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
    (\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}).

  \item Bad spellings that are hyphenated at a page break are not
    highlighted
    (\href{https://github.com/sh2d/spelling/issues/10}{issue~10}).

  \end{itemize}


\end{itemize}

Any contributions are warmly welcome!

\bigskip
\emph{Happy \TeX ing!}


\end{document}



%%% Local Variables: 
%%% mode: latex
%%% TeX-PDF-mode: t
%%% TeX-master: t
%%% coding: utf-8
%%% End: