summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/testhyphens/testhyphens.dtx
blob: 02808f4060e42a571413bf6044ff0f3a50f1522c (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
% \iffalse meta comment
% !TEX encoding = UTF-8 Unicode
% !TEX TS-program = pdflatex

%<*internal>
\begingroup
\input docstrip.tex
\keepsilent
\preamble
Copyright 2014 Claudio Beccari All rights reserved.

 This system is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

This file is distributed under the LPPL licence, version 1.3c 
dated 2008-05-04 or later as it appears in 
CTAN/macros/latex/base/lppl.tex.
See the end of the file.

IMPORTANT NOTICE:

You are allowed to distribute this file under the conditions that are 
specified in the source file testhyphens.dtx.

If you receive only some of these files from someone, complain!

You are NOT ALLOWED to distribute this file alone.  
You are NOT ALLOWED to take money for the distribution or use 
of either this file or a changed version, except for a nominal 
charge for copying, etc.
\endpreamble
\askforoverwritefalse
%
\generateFile{testhyphens.sty}{f}{\from{testhyphens.dtx}{package}}

\def\tmpa{plain}
\ifx\tmpa\fmtname\endgroup\expandafter\bye\fi
\endgroup
%</internal>
% \fi
%
%% \CharacterTable
%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
% \iffalse 
%^^A The following trick uses the same date for every file header.
%<package>\NeedsTeXFormat{LaTeX2e}
%<*driver>
\ProvidesFile{testhyphens.dtx}[%
%</driver>
%<package>\ProvidesPackage{testhyphens}[%
%<*driver,package>
2015/11/23 v.0.7 
%<package>Prints list of hyphenated words]
%</driver,package>
%<*driver>
]
%</driver>
%<*driver>
\documentclass{ltxdoc}
\GetFileInfo{testhyphens.dtx}
  \title{The \textsf{testhyphens} package%
        \thanks{This file
        has version number \fileversion, last
        revised on \filedate.}}
 \author{Claudio Beccari\thanks{claudio dot beccari at gmail dot com}}
 \date{}
 \providecommand\babel{\pack{babel}}
 \newcommand\lbr{\char123\relax}\newcommand\rbr{\char125\relax}
 \newenvironment{sintassi}{%
      \begin{quote}\parskip0pt\hfuzz10pt\ttfamily\obeylines
      }{%
      \end{quote}\ignorespaces
      }
 \renewcommand*\meta[1]{{\normalfont\textlangle\textit{#1}\textrangle}}
 \newcommand*\pack[1]{\textsf{#1}}
 \newcommand*\prog[1]{\texttt{#1}}
 \newcommand*\Arg[1]{{\normalfont\texttt{\{}\meta{#1}\texttt{\}}}}
 \renewcommand*\oarg[1]{\texttt{[}\meta{#1}\texttt{]}}
 \let\marg\Arg
 \newcommand*\acro[1]{\expandafter\textsc\expandafter{\MakeLowercase{#1}}}
 \usepackage{multicol}
 \usepackage[utf8]{inputenc}
\usepackage[LGR,T1]{fontenc}
\usepackage{lmodern,textcomp}
\usepackage[greek,italian,english]{babel}
\usepackage{testhyphens}
\begin{document}
 \maketitle
 \DocInput{testhyphens.dtx}
\end{document}
%</driver>
% \fi
%
% \CheckSum{106}
% \begin{abstract}
% This small file implements some code that was already published on TUGboat,
% but it is adapted to \LaTeX\ and it is enriched with other commands. It helps
% those who create hyphenation patterns, as well normal \LaTeX\ users, to test
% the correctness of the hyphenations of words lists. It works also with
% \prog{xelatex} and \prog{lualatex}.
% \end{abstract}
%
%{\columnseprule=0.4pt
%\begin{multicols}{2}
%\tableofcontents
%\end{multicols}}
%
% \section{Introduction}
%
% This small package introduces the declaration |\testhyphens| and the environment
% |checkhyphens|. The declaration is to be used within a group where the hyphenation
% parameters may be optionally set to any specific value; it processes a list
% of one or more space delimited words typesetting them one per line with hyphens
% between every syllable.
%
% The language, the hyphenation rules of which are to be tested, may be the
% default language before entering the group, or can be a language specified
% with |\selectlanguage| within the group before activating the declaration:
% this declaration could be set within a |\foreignlangeuage|\Arg{language}
% argument or within the body of an |otherlanguage| environment.
%
% The environment |checkhyphens| accepts an optional argument to set the
% hyphenation parameters, and a body consisting of a list
% of one or more space separated words; if the
% user just pastes a text copied from somewhere that included punctuation,
% the punctuation signs are ignored, but are not taken off from the text.
%
% The main code was published long ago by Victor Eijkout, in ``The bag of
% tricks'', \emph{TUGboat} 14.4 (1993), p. 424. He himself states that
% that code was created by Jonathan Kew; Victor Eijkout just added an empty
% |\discretionary{}{}{}|; the idea came to him from  the code created by
% Oliver Schoett that is used for the hyphenation exception list of TUGboat.
% Credit for the code goes completely to the authors mentioned above; I just
% added some sugar to use that code in \LaTeX\ documents for the benefit of
% hyphenation pattern creators, and of regular users who want to know how a
% certain word or the words of a certain sentence would be hyphenated by
% \TeX\ and friends.
%
% Of course this package does not tell the whole truth: in fact \TeX\ and
% friends hyphenate words only when certain conditions are met; these
% conditions are stated in Appendix~H of the \TeX\-book, which is and remains
% the primary reference for understanding the hyphenation process used by
% \TeX\ and friends.

% Sometimes the user complains that certain words are not hyphenated; the user
% might use this package and find out that her/his words are regularly
% hyphenated; then what's happening? Simply those conditions are not met.
% Therefore the full understanding of the above mentioned Appendix~H is
% fundamental before complaining about \TeX\ not working properly with
% hyphenations and possibly before raising a bug notice.
%
% \section{Incompatibility with the previous version 0.5a}
% I had to change some definitions within the body of this package in order
% to avoid clashes mainly with the |french| language option of babel;
% in facts that option declares most punctuation marls as active characters.
% Unfortunately those characters receive global definitions, therefore they
% remain active even when they should not perform any action. 
%
% It is necessary to emphasize that the previous version used the colon as
% a parameter separator; while, in order to avoid conflicts with |french|,
% the parameter separator is a simple hyphen.
%
% Defining active characters when using |polyglossia| may produce other
% incompatibilities that are easily circumvented by specifying languages
% in a different order. In facts, if you specify languages as such
%\begin{verbatim}
%\setmainlanguage[babelshorthands]{italian}
%\setotherlanguages{english,french}
%\end{verbatim}
% produces an error when |french| sets up its parameters for the UNICODE
% apostrophe: the cause of this error derives from the use of the |italian| option
% |babelshorthands|; of course if this option is not specified, no problems
% arise. But if you interchange the declarations as in
%\begin{verbatim}
%\setotherlanguages{english,french}
%\setmainlanguage[babelshorthands]{italian}
%\end{verbatim}
% no problems arise.
%
% \section{Usage}
% This package has been tested with |pdflatex|, |xelatex|, and |lualatex|; 
% for |lualatex| a package |showhyphens| exists that marks the hyphen
% points of an entire document with thin red vertical strokes at the
% possible break points. The user may use the package s/he prefers by
% taking into consideration her/his needs with respect with the features
% and the functionalities of package |testhyphens| compared to those
% of |showhyphens|.
%
% Remember that normal  Plain \TeX\ and \LaTeX\ have available the command
% |\showhyphens| but, differently from this package, such command works
% only when the typesetting engine is |tex| or |pdftex|; moreover the result
% appears on the console window and in the \texttt{.log} file and no written
% record remains available to the user; for |xelatex| there was a workaround
% provided by another package, but for some reasons it did not work in every
% circumstance.  This package |testhyphens|, on the opposite, prints the result
% in the output document and works also with |xetex| as the typesetting engine.
%
% This simple package  is loaded just with the usual statement 
% \begin{flushleft}
%|\usepackage{testhyphens}|
% \end{flushleft}
% 
% The package defines for the end user one declaration |\testhyphens| and
% one environment |checkhyphens| the syntax of which is the following:
%\begin{sintassi}
% |\begin{checkhyphens}|\oarg{hyphenation parameters}
% \marg{word list}
% |\end{checkhyphens}|
%\end{sintassi}
% where \meta{hyphenation parameters} is a \emph{hyphen separated list} of two 
% digits that in order will be assigned by the environment respectively to
% |\lefthyphenmin| and |\righthyphenmin|; \meta{word list} is self
% explanatory. Nevertheless it good to remember that the environment isolates
% single words by using a space as a word separator; this requires that the
% list is preceded and followed by spaces; setting the environment with the
% opening and closing statements on single lines, as shown above, is sufficient,
% while a source line such as
% |\begin{checkhyphens}|\oarg{hyphenation parameters}\marg{word list}|\end{checkhyphens}|
% might not produce the desired result.
%
% \section[Hyphenation parameters]{Using hyphenation parameters}
% The hyphenation parameters are just |\lefthyphenmin| and |\righthyphenmin|;
% they represent the minimum number of characters that the first and, respectively,
% the last word fragment must have before or until hyphenation takes place;
% for example in English the default values are 2 and~3; in Italian the default
% values are 2 and~2; in Greek the default values are 1 and~1.
%
% Let us make an example: the word \emph{idea} is spelt the same in English and
% Italian, although it is pronounced differently; but in both cases the word is
% not hyphenated at all in both languages. According to the Italian hyphenation
% rules its grammatical hyphenation is \emph{i-de-a}; possibly in English the
% grammatical hyphenation is the same; in any case the initial and the terminal
% syllables are too short to comply with the above mentioned \TeX\ hyphenation
% parameters, and \TeX\ refrains from hyphenating this word. In Greek, on the
% opposite, \foreignlanguage{greek}{ιδέα}  is divided into
% \foreignlanguage{greek}{ι-δέ-α}.
%
% If you use |checkhyphens| with the optional hyphenation parameters specified to
% 1 and~1 in Italian or in English, as in
%\begin{verbatim}
%\begin{checkhyphens}[1-1] 
%idea
%\end{checkhyphens}
%\end{verbatim}
% you don't get any useful result in English, and the word remains un-hyphenated;
% but in Italian is turns out to be \emph{i-de-a} as in Greek. 
%
% This happens because the Italian patterns were created by hand and tested with
% parameters 1 and~1, even if for typesetting purposes the parameters are set
% to 2 and~2. In English the patterns were created by means of the program
% \prog{patgen} where parameters 2 and~3 were set. Typographically speaking
% the values 1 and~1 for Italian are almost useless, but in certain difficult
% narrow-measure texts the user has the possibility to locally set the first
% and/or the second parameter to 1, and solve that particular instance of
% problematic narrow-measure typesetting.
%
% \section{Examples}
% Here we show some actual examples using either the declaration or the environment.
% While typesetting in English we might verify the hyphenation of some words.
% We set in the source file the following lines (notice the |\par| command is a reminder that the group containing the declaration must be used in vertical mode; a blank line would be equivalent):
%\begin{verbatim}
%\par
%{\testhyphens 
%manifests instruments 
%he analyses the samples and submits the analyses to the federal office 
%}
%\end{verbatim}
% The result produced by this package, typeset within a four-column multicols environment, is:
%
%\begin{multicols}{4}{\testhyphens 
%manifests instruments 
%he analyses the samples and submits the analyses to the federal office 
%}\end{multicols}
% Notice the two instances of the word |analyses|; \TeX\ hyphenates them the
% same way in English, but one of the two is hyphenated in a wrong way;
% unfortunately there is no way for \TeX\ to distinguish homographic words
% that are not homophonic ones. In plain terms the verb ``analyses'' is stressed
% on the `y', while the noun ``analyses'' is stressed on the second `a';
% the standard phonetic hyphenation rules for English probably should hyphenate
% the verb as ``an-a-lyses'', but \TeX\ works only on the spelling and not on
% the sound and does not make any logical analysis of the text to find out
% if a word plays the rôle of a noun or of a verb. In this and similar
% situations (for example: ``the record'' and ``to record'') the user should
% check a good reliable dictionary and possibly  use an explicit discretionary
% hyphen~|\-|.
%
% While typesetting in Italian it is possible to insert in the source file
% a set of lines such as these:
%\begin{verbatim}
%\begin{checkhyphens}
%ebbe la bell'idea di viaggiare in scooter
%\end{checkhyphens}
%\end{verbatim}
% that produces the following result:
%\begin{multicols}{4}
%\begin{otherlanguage*}{italian}
%\begin{checkhyphens}
%ebbe la bell'idea di viaggiare in scooter
%\end{checkhyphens}
%\end{otherlanguage*}\end{multicols}
%Notice that ``idea'' cannot be hyphenated by \TeX\ when it is an isolated
% word; but in Italian the apostrophe is used (also) to mark a vocalic elision,
% therefore for hyphenation purposes, even if it is not a letter, it is assigned
% a lowercase code, and it legally becomes part of a word, in our case the word
% ``bell'idea''. Therefore the patterns that involve the apostrophe produce
% the result shown above, where the first grammatical hyphen point shows up again.
%
% While typesetting in Greek we might insert in the source file the following code:
%\begin{flushleft}\ttfamily\obeylines
%|\begin{checkhyphens}|
%\begin{otherlanguage*}{greek}
%επεξεργάζεται αρχεία τα οποία περιέχουν τουσ χαρακτήρες που
% υπάρχουν στο πληκτρολόγιο του υπολογιστή σας
%\end{otherlanguage*}
%|\end{checkhyphens}|
%\end{flushleft}
%and we would get:
%\begin{multicols}{4}
%\begin{otherlanguage*}{greek}
%\begin{checkhyphens}
%επεξεργάζεται αρχεία τα οποία περιέχουν τουσ χαρακτήρες που υπάρχουν 
%στο πληκτρολόγιο του υπολογιστή σας
%\end{checkhyphens}
%\end{otherlanguage*}\end{multicols}
%\noindent while, had we set the hyphenation parameters different from the default
% values 1 and~1, as in: 
%\begin{flushleft}\ttfamily\obeylines
%|\begin{checkhyphens}[2-2]|
%\begin{otherlanguage*}{greek}
%επεξεργάζεται αρχεία τα οποία περιέχουν τουσ χαρακτήρες που 
%υπάρχουν στο πληκτρολόγιο του υπολογιστή σας
%\end{otherlanguage*}
%|\end{checkhyphens}|
%\end{flushleft}
%the result would be:
%\begin{multicols}{4}
%\begin{otherlanguage*}{greek}
%\begin{checkhyphens}[2-2]
%επεξεργάζεται αρχεία τα οποία περιέχουν τουσ χαρακτήρες που υπάρχουν 
%στο πληκτρολόγιο του υπολογιστή σας
%\end{checkhyphens}
%\end{otherlanguage*}\end{multicols}
%
% Notice that as things are at the moment of writing this documentations,
% the monotonic Greek hyphenation patterns fail to hyphenate after an
% accented vowel followed by a consonant\footnote{My PDF file of this
% documentations does not exhibit this feature, because I have available the
% correct hyphenations patterns for the three Greek orthographic spellings, but
% these are not yet officially available to the \TeX\ community because the Greek
% maintainers have not yet finished testing them. You might be reading a
% re-typeset version of this documentation, and this feature might be present.};
% the grammar allows to hyphenate in that position; in any case the patterns
% correctly recognise the hiatus between an accented vowel and an unaccented one.
% The first Greek example shows very clearly the effect of |\lefthyphenmin=1|
% compared to the second example where |\lefthyphenmin=2|. On the other hand,
% the fact that some hyphen points are missing is certainly a feature that
% precludes full hyphenation, but it does not produce hyphenation errors.
%
% For the user information it was the very use of this package that highlighted
% the features/bugs in the Greek hyphenation patterns; at the moment of writing
% this documentation, work is in progress for testing new hyphen sets. Notice
% that this behaviour is present when typesetting with  |pdflatex| and |babel|,
% while these features are absent when  |xelatex| or |lualatex| are used with
% |polyglossia|.
% \StopEventually{}
%
% \section{The code}
%\iffalse
%<*package>
%\fi
% The following code has very few modifications compared to the original code
% published by Victor Eijkout. For my own benefit I changed the declaration
% name from |\printhyphens| to |\t@sthyphens|; with an  at-sign internal name
% it is less likely that  the declaration is redefined by a user. I also moved
% the command |\offinterlineskip| from its penultimate position in the original
% code to the first command to be executed within the |\vbox|; in this way
% I avoided certain cases in which the lack of interline skip would remain
% active after closing the environment.
%
% The code is based on treating the interword space as an active character
% that plays different rôles according to its position; it lets the
% declaration isolate the words to be hyphenated and open suitable boxes,
% that are closed at the moment of processing the following word; the
% |\everypar| token-list distinguishes the various actions to be performed
% at each step.
%
% But the trick is to set each word within a vertical box where the measure
% (the text width |\hsize|) is zero; in this way each word is hyphenated at
% the first hyphen point, but the word fragment that remains in the following
% line is still too long and gets hyphenated again; the process is repeated
% again and again until the initial string is exhausted. The contents of the
% |\vbox|, that now contains the syllables one per line, is reassembled to
% form one line, and this line is output within an |\hbox| and is therefore
% the box typeset in vertical mode; this is why the declaration must be issued
% in vertical mode, so as to start processing the word list with the right
% foot; this is also why the word list must start and end with  spaces; the
% first one before the first word opens the first box, and the last space after
% the last word closes and outputs the last box.
%    \begin{macrocode}
\def\t@sthyphens{\everypar{\setbox0\lastbox \setbox1\hbox{\strut}\vbox\bgroup
\offinterlineskip
\everypar{\setbox0\lastbox \nobreak\hskip\z@}\dimen0=\hsize
\hsize=\z@ \hfuzz\maxdimen \def\par{\endgraf \hsize=\dimen0\getlastline
\egroup\endgraf}}\breakafterword}

\def\breakafterword{\catcode`\^^M\active\catcode`\ \active}

{\breakafterword\gdef^^M{\par}\global\let ^^M}

\def\getlastline{\setbox0\lastbox\ifvoid0\let\next\nomorelines
\else\unskip\unpenalty\setbox1\hbox{\unhbox0\strut\discretionary{}{}{}%
\unhbox1}\let\next\getlastline\fi\next}

\def\nomorelines{\unhbox1}
%    \end{macrocode}
% The above code is substantially the original one; now we define the user
% declaration control sequence |\testhyphens| by letting it to assume the
% meaning of the internal control sequence. Then we define the |checkhyphens|
% environment where  we make sure that the whole process of the word list
% contained in its body takes place in vertical mode. In oder to process
% the optional argument for setting the hyphenation parameters, we define
% a delimited argument macro |\s@thyphenpars| that uses the \emph{hyphen} as
% argument delimiter.
%    \begin{macrocode}
\let\testhyphens\t@sthyphens

\newenvironment{checkhyphens}[1][\lefthyphenmin-\righthyphenmin]{%
\@tempcnta=\lefthyphenmin
\@tempcntb=\righthyphenmin
\s@thyphenpars[#1]\par\bgroup\t@sthyphens
}{%
\egroup\par
}

\def\s@thyphenpars[#1-#2]{%
\@tempcnta=#1\relax
\@tempcntb=#2\relax
\unless\ifnum\@tempcnta=\lefthyphenmin \lefthyphenmin=\@tempcnta\fi
\unless\ifnum\@tempcntb=\righthyphenmin \righthyphenmin=\@tempcntb\fi
}
%    \end{macrocode}
%\iffalse
%</package>
%\fi
% That's all. Happy \TeX\-ing.
%\Finale
\endinput