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