Debian Codegraph @

texmf-dist/doc/xelatex/fontwrap/fontwrap.tex

raw
1 \documentclass[12pt]{article}
2
3 % Ruby markup renewal
4 \usepackage[overlap, CJK]{ruby}
5 \renewcommand{\rubysep}{-0.3ex}
6 \renewcommand{\rubysize}{0.6}
7
8 % automatically wraps characters from specific unicode blocks with the relevant font tag
9 \usepackage{fontwrap}
10
11 % in this example, fontwrap is only allowed to process content for 'ruby' tags.
12 \setfontwrapallowedmacros{section,subsection,subsubsection,paragraph,subparagraph,emph}
13 \setfontwrapallowedenvironments{tabular}
14
15 % always good to have, in case a sentence is unmanageable and needs to be rewritten.
16 \overfullrule=5pt
17
18 % fontspec
19 \setmainfont{Palatino Linotype}
20
21 % floaty goodness
22 \usepackage{float}
23 \floatstyle{boxed}
24 \newfloat{block}{htbp}{blocks}
25
26 % document start
27 \begin{document}
28
29 % frontmatter
30 \title{fontwrap}
31 \author{Michiel Kamermans\\www.nihongoresources.com}
32 \date{\today}
33 \maketitle
34
35 % set up fontwrap's default font.
36 % not quite sure why I can't issue this before the document start
37 \setfontwrapdefaultfont{Bitstream Cyberbit}
38
39 % set specific unicode groups
40 \setunicodegroupfont{Arabic}{Traditional Arabic}
41 \setunicodegroupfont{Latin}{Palatino Linotype}
42 \setunicodegroupfont{Japanese}{Ume Mincho}
43 \setunicodegroupfont{Chinese}{SimHei}
44 \setunicodegroupfont{Korean}{BatangChe}
45 \setunicodegroupfont{Cyrillic}{Dotum}
46 \setunicodegroupfont{Greek}{Arno Pro}
47
48 % thai and hebrew have no group, just a block
49 \setunicodeblockfont{Thai}{Cordia New}
50 \setunicodeblockfont{Hebrew}{Times New Roman}
51
52
53 % ----------------
54 % START OF CONTENT
55 % ----------------
56
57 \section{What is fontwrap?}
58
59 fontwrap is a Perl\TeX\ package for automatically adding font tags in multilingual
60 documents. More specifically, it adds font tags between unicode block changes
61 in documents that are encoded in UTF8 unicode (which is, thankfully these days,
62 pretty much any new multilingual document).
63
64 The whole reason most of us use \TeX\ or \LaTeX\ or the newer \LaTeXe\ or
65 whichever flavour of \TeX\ you like to use, is because it lets you write your
66 document with a minimal amount of placing control codes inside the actual text
67 you're writing. Most of the time, your text will just be text, and you'll be
68 damned if you have to add all kinds of special codes because that will make the
69 source file less readable. However, when you're working in a multilingual \TeX\ document,
70 you might find you're wrapping bits of "foreign" text in with macros that ensure
71 the right font or other visual styling makes its way to the final document.
72 fontwrap was designed to remove the need for that practice, so that your document
73 stays readable.
74
75 \begin{block}
76 \fontwrap{
77 \emph{Even though I am writing this on an English operating system in an English
78 text editor, I can input quite a lot of different language. I can do this,
79 because of the power of unicode: English, 日本語, 中國話, 한글, 조선글, الْعَرَبيّة
80 , Русский язык, Ελληνικά, Tiếng Việt, ภาษาไทย , עִבְרִית and a whole scala of other
81 languages all use different scripts, which all have their own place in the
82 unicode 5.0 world.}
83 }
84 \caption{A paragraph using many different unicode blocks}
85 \end{block}
86
87 If you look closely at the example paragraph in block 1, you will see that all
88 the different languages use a different font. The English font is \emph{Palatino
89 Linotype}, the font for Japanese is \emph{Ume Mincho}, the font for Chinese is
90 \emph{SimHei}, for Korean \emph{BatangChe}, for Arabic \emph{Traditional Arabic},
91 Cyrillic uses \emph{Dotum}, Greek uses \emph{Arno Pro}, Thai uses \emph{Cordia New},
92 and for Hebrew I used \emph{Times New Roman}. For those wondering, Vietnamese
93 actually uses the Latin and Latin Extended Additional blocks, so it uses the same
94 \emph{Palatino Linotype}\ font as the English text.
95
96 In normal \TeX\ , getting all the languages marked with the right fonts, with all
97 the commas and spaces using the same font as the English text, require a mad amount
98 of font markup, but with fontwrap this requires no markup beyond the 'fontwrap' command:
99 all I had to do to get the text to use all these different fonts is tell fontwrap which
100 fonts to use for which blocks in my frontmatter, and wrap write the paragraph exactly as
101 you see it in this pdf file into my .tex \textemdash\ wrapping it in the \textbackslash
102 fontwrap\{\} macro then takes care of all my fonty needs.
103
104 \section{Getting fontwrap working for your document}
105
106 The basic procedure for getting fontwrap to work in your document is really
107 quite straightforward. First, we must make sure to actually use it:
108
109 \begin{verbatim}
110 \usepackage{autfont}
111 \end{verbatim}
112
113 The rest of the code comes in the document body itself. Before we do anything
114 with fontwrap, it is usually a good idea to tell it which fonts to use for
115 which unicode blocks. There is one \emph{catch-all} command to do this, which
116 sets the same font for every block, and several \textbackslash set commands for
117 both single blocks, and informal multi-block groups. In this document, for
118 instance, I use this:
119
120 \begin{verbatim}
121 % set up fontwrap's default font.
122 \setfontwrapdefaultfont{Bitstream Cyberbit}
123
124 % set specific unicode groups
125 \setunicodegroupfont{Arabic}{Traditional Arabic}
126 \setunicodegroupfont{Latin}{Palatino Linotype}
127 \setunicodegroupfont{Japanese}{Ume Mincho}
128 \setunicodegroupfont{Chinese}{SimHei}
129 \setunicodegroupfont{Korean}{BatangChe}
130 \setunicodegroupfont{Cyrillic}{Dotum}
131 \setunicodegroupfont{Greek}{Arno Pro}
132
133 % thai and hebrew have no group, just a block
134 \setunicodeblockfont{Thai}{Cordia New}
135 \setunicodeblockfont{Hebrew}{Times New Roman}
136 \end{verbatim}
137
138 Of course, you can set as few or as many as you like, or more importantly as
139 is appropriate. If you're using a bilingual document, setting the catch-all
140 binding and an extra font for the "foreign" bits is all you have to do. After
141 having set up the font bindings in this way, all that's left is to type in
142 whichever mix of languages you please, and surround your text with the
143 \textbackslash fontwrap macro:
144
145 \begin{verbatim}
146 \fontwrap{
147 the verbatim environment used to make this
148 block of text only supports Latin, but you
149 would be free to type whatever you like in
150 this macro.
151 }
152 \end{verbatim}
153
154 The only downside to this is that I cannot show the actual text from
155 example paragraph 1, because the \{ verbatim\}\ environment cannot
156 handle more than just Latin, and is one of the few blocks where
157 fontwrap should not be used - adding font tags inside a verbatim
158 block means you're going to get the \TeX\ commands in your final
159 output, instead of having them processed, because that's what
160 verbatim does!
161
162 Moving on, \textbackslash fontwrap does not look into other macros
163 and environments by default. If you want it to process text in macros
164 such as \textbackslash emph or \textbackslash caption then you need
165 to explicitly tell it that it is allowed to do this. This command,
166 and the equivalent command for environments, goes in the preamble:
167
168 \begin{verbatim}
169 % allow processing of content for the following macros:
170 \setfontwrapallowedmacros{section,subsection,
171 subsubsection,paragraph,
172 subparagraph,emph, caption,
173 ... }
174 % allow processing of content for the following environments:
175 \setfontwrapallowedenvironments{tabular, ... }
176 \end{verbatim}
177
178 whenever \textbackslash fontwrap is now used, it will process text
179 in general document structure macros, as well as the tabular environment,
180 which is useful if we use "foreign" text in any tables we're bound to
181 end up using.
182
183 And with that the basic use is pretty much covered.
184
185 \section{Available commands}
186
187 First off, \textbackslash fontwrap of course:
188
189 \begin{verbatim}
190 \fontwrap{ ... }
191 \end{verbatim}
192
193 and wrapped in the fontwrap verbatim environment in case whitespace really, really matters:
194
195 \begin{verbatim}
196 \begin{fontwrapverbatim}
197 \fontwrap{ ... }
198 \end{fontwrapverbatim}
199 \end{verbatim}
200
201 Secondly, the allowances:
202
203 \begin{verbatim}
204 \setfontwrapallowedmacros{comma delimited list}
205 \setfontwrapallowedenvironments{comma delimited list}
206 \end{verbatim}
207
208 Thirdly, the font setup commands:
209
210 \begin{verbatim}
211 \setunicodegroupfont{block name}{font name}
212 \setunicodeblockfont{block name}{font name}
213 \end{verbatim}
214
215 \begin{block}
216 Arabic, Chinese, CJK (which combines all Chinese, Japanese
217 and Korean blocks), Cyrillic, Diacritics, Greek (including some
218 Coptic), Korean, Japanese, Latin, Mathematics, Phonetics, Punctuation,
219 Symbols, Yi and finally, Other, which is just a lump category for everything
220 else, really\dots
221 \caption{All available informal group names}
222 \end{block}
223
224 There are several informal groups available, which are listed
225 in block 2. Also not unimportant to note: these are all case
226 sensitive. The "other" group is a bit of an eyesore, but for
227 now it will have to do. Of course, Linear B and Ethiopian form
228 informal groups too, but I just don't use them, so they will be
229 given their own group when I'm done refining fontwrap, really.
230
231 In addition to these groups, there are also the individual
232 blocks, in case there is no group for what you want to set
233 a font for, such as Hebrew, Thai, or really exotic things
234 like Cuneiform or Byzantine musical symbols! There are a total
235 of 158 blocks available for font binding, listed in block 3.
236
237 \begin{block}
238 AegeanNumbers, AlphabeticPresentationForms, AncientGreekMusicalNotation,
239 AncientGreekNumbers, Arabic, ArabicPresentationFormsA,
240 ArabicPresentationFormsB, ArabicSupplement, Armenian, Arrows,
241 Balinese, BasicLatin, Bengali, BlockElements, Bopomofo,
242 BopomofoExtended, BoxDrawing, BraillePatterns, Buginese,
243 Buhid, ByzantineMusicalSymbols, Cherokee, CJKCompatibility,
244 CJKCompatibilityForms, CJKCompatibilityIdeographs,
245 CJKCompatibilityIdeographsSupplement, CJKRadicalsSupplement,
246 CJKStrokes, CJKSymbolsandPunctuation, CJKUnifiedIdeographs,
247 CJKUnifiedIdeographsExtensionA, CJKUnifiedIdeographsExtensionB,
248 CombiningDiacriticalMarks, CombiningDiacriticalMarksforSymbols,
249 CombiningDiacriticalMarksSupplement, CombiningHalfMarks, ControlPictures,
250 Coptic, CountingRodNumerals, Cuneiform, CuneiformNumbersandPunctuation,
251 CurrencySymbols, CypriotSyllabary, Cyrillic, CyrillicExtendedA,
252 CyrillicExtendedB, CyrillicSupplement, Deseret, Devanagari, Dingbats,
253 DominoTiles, EnclosedAlphanumerics, EnclosedCJKLettersandMonths,
254 Ethiopic, EthiopicExtended, EthiopicSupplement, GeneralPunctuation,
255 GeometricShapes, Georgian, GeorgianSupplement, Glagolitic, Gothic,
256 GreekandCoptic, GreekExtended, Gujarati, Gurmukhi, HalfwidthandFullwidthForms,
257 HangulCompatibilityJamo, HangulJamo, HangulSyllables, Hanunoo, Hebrew,
258 HighPrivateUseSurrogates, HighSurrogates, Hiragana, IdeographicDescriptionCharacters,
259 IPAExtensions, Kanbun, KangxiRadicals, Kannada, Katakana, KatakanaPhoneticExtensions,
260 Kharoshthi, Khmer, KhmerSymbols, Lao, LatinExtendedAdditional, LatinExtendedA,
261 LatinExtendedB, LatinExtendedC, LatinExtendedD, LatinSupplement,
262 LetterlikeSymbols, Limbu, LinearBIdeograms, LinearBSyllabary, LowSurrogates,
263 MahjongTiles, Malayalam, MathematicalAlphanumericSymbols, MathematicalOperators,
264 MiscellaneousMathematicalSymbolsA, MiscellaneousMathematicalSymbolsB,
265 MiscellaneousSymbols, MiscellaneousSymbolsandArrows, MiscellaneousTechnical,
266 ModifierToneLetters, Mongolian, MusicalSymbols, Myanmar, NewTaiLue, NKo,
267 NumberForms, Ogham, OldItalic, OldPersian, OpticalCharacterRecognition,
268 Oriya, Osmanya, PhagsPa, Phoenician, PhoneticExtensions, PhoneticExtensionsSupplement,
269 PrivateUseArea, Runic, Shavian, Sinhala, SmallFormVariants,
270 SpacingModifierLetters, Specials, SuperscriptsandSubscripts,
271 SupplementalArrowsA, SupplementalArrowsB, SupplementalMathematicalOperators,
272 SupplementalPunctuation, SupplementaryPrivateUseAreaA,
273 SupplementaryPrivateUseAreaB, SylotiNagri, Syriac, Tagalog,
274 Tagbanwa, Tags, TaiLe, TaiXuanJingSymbols, Tamil, Telugu,
275 Thaana, Thai, Tibetan, Tifinagh, Ugaritic, UnifiedCanadianAboriginalSyllabics,
276 VariationSelectors, VariationSelectorsSupplement, VerticalForms,
277 YiRadicals, YiSyllables, and finally YijingHexagramSymbols.
278 \caption{All 158 blocks available in unicode 5.0}
279 \end{block}
280
281 These, too, are case sensitive.
282
283 \section{Running Perl\TeX\ and possible errors}
284
285 Running \TeX\ files that use fontwrap means you have to use Perl\TeX\ to
286 get it all to work. Luckily, Perl\TeX\ is just a \TeX\ wrapper, so you can
287 tell it which \TeX\ engine to use and it will. Because fontwrap relies on
288 the fontspec package, we have to use Xe\TeX :
289
290 \begin{verbatim}
291 perltex --latex=xelatex myfile.tex
292 \end{verbatim}
293
294 This should run fine, but there are three problems you might run into.
295
296 \paragraph{No unicode mapping available}
297
298 You get this error when \TeX\ uses a font that cannot represent the
299 unicode glyphs you have written. For instance, using something other
300 than Latin text in a verbatim block will cause this error. It's
301 not fatal in any way, it just means that you will see empty blocks
302 in your final document.
303
304 \paragraph{Free to wrong pool}
305
306 Perl\TeX\ uses Perl \emph{(fairly obviously)}\ but it does so sort
307 of multithreaded. It also uses the Perl "safe" module, and that's
308 where things go funky. The combination of multithread perl and "safe"
309 can lead to perl trying to free the memory it used, but failing
310 at this because it tries to do so in entirely the wrong thread.
311 This is completely inconsequential, other than that it can lead
312 to memory leaks. Now, I made sure to unset all the perl variables
313 I use once fontwrap is done, so you shouldn't run into any problems
314 \emph{(unless maybe you were counting the bytes by hand)} .
315
316 \paragraph{Overfull/underfull hbox}
317
318 The boon of \TeX , this means that a particular sentence is
319 made up of letters and spaces in such a way that \TeX\ cannot
320 really get the glue stretched properly for it to look nice
321 in your final document. You're going to have to go in, and
322 fix the problem yourself by rephrasing the sentence... either
323 that or leave it in and turn off whatever visual notification
324 for problematic hboxes you use during draft generation.
325
326 \section{The end\ldots}
327
328 And\ldots\ I think that's it. I can't think of anything more
329 to tell you with respects to using fontwrap. If you have any
330 questions you can always check out the .sty file, or contact
331 me through the contact page on my website, http://www.nihongoresources.com.
332
333 \bigskip
334
335 Enjoy!
336
337 \bigskip
338 \bigskip
339
340 - Mike Kamermans
341 \end{document}