path: root/Master/texmf-dist/source/generic/vntex/doc/vntex.tex

% vntex-@VERSION@
%
% Copyright 2003-2005 Han The Thanh <HanTheThanh@gmail.com>.
%
% Authors: Han The Thanh <HanTheThanh@gmx.net> and 
%	   Reinhard Kotucha <Reinhard.Kotucha@web.de>
%
% This file is part of vntex.
%
% 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
%
%         http://www.latex-project.org/lppl.txt
%
% The current maintainers are Werner Lemberg, Han The Thanh, and 
% Reinhard Kotucha.

\documentclass[a4paper,11pt]{article}
\usepackage{amsmath,amsfonts,amssymb}
\usepackage[utf8]{inputenc}
\usepackage[T1,T2A,T5]{fontenc}
%\usepackage[T1]{fontenc}
%\usepackage[T2A]{fontenc}
%\usepackage[T5]{fontenc}
\usepackage[russian,vietnamese]{babel}
\usepackage{charter}
\usepackage{textcomp}
\usepackage[scaled=.9]{helvet}
\usepackage{parskip}
\usepackage{upquote}
\usepackage{microtype}
\usepackage{url}
\usepackage{graphicx} % for XeTeX logo
\usepackage{fancyvrb}\DefineShortVerb{\|}
%\usepackage{showframe}
%\usepackage{mparhack}

\RequirePackage[dvipsnames]{color}

\newif\ifprint
\ifdefined\printversion
  \printtrue
\else
  \printfalse
\fi

\def\arraystretch{1.25}

\raggedbottom

%\def\vi#1{\foreignlanguage{vietnamese}{#1}}

\makeatletter
\let\ifundefined\@ifundefined

\renewcommand\@seccntformat[1]{\llap{\@nameuse{the#1}\hspace{1em}}}

\renewcommand\section{\@startsection {section}{1}{\z@}%
                                   {-3.5ex \@plus -1ex \@minus -.2ex}%
                                   {0.3ex \@plus.2ex}%
                                   {\normalfont\Large\bfseries   
                                     \rightskip\z@ plus3em
                                     \spaceskip.3333em
                                     \xspaceskip.5em\color[named]{BrickRed}}}

\renewcommand\subsection{\@startsection{subsection}{2}{\z@}%
                                     {.25ex\@plus -1ex \@minus -.2ex}%
                                     {0.2ex \@plus .2ex}%
                                     {\normalfont\large\bfseries   
                                       \rightskip\z@ plus3em
                                       \spaceskip.3333em
                                       \xspaceskip.5em\color[named]{BrickRed}}}

\renewcommand\subsubsection{\@startsection{subsubsection}{3}{\z@}%
                                     {1.25ex\@plus -1ex \@minus -.2ex}%
                                     {0.1ex}%
                                     {\normalfont\normalsize\bfseries
                                       \rightskip\z@ plus2em
                                       \spaceskip.3333em
                                       \xspaceskip.5em
                                       \color[named]{BrickRed}}}

\renewcommand\paragraph{\@startsection{paragraph}{4}{\z@}%
                                    {\parskip}%
                                    {-1em}%
                                    {\normalfont\normalsize\bfseries\color[named]{BrickRed}}}
\renewcommand\subparagraph{\@startsection{subparagraph}{5}{\parindent}%
                                    {\parskip}%
                                    {-1em}%
                                    {\normalfont\normalsize\bfseries\color[named]{BrickRed}}}
\makeatother


%%% Colors

\definecolor{labelitemicolor}{rgb}{0,.5,0}
\definecolor{labelitemiicolor}{rgb}{.75,0,0}
\definecolor{labelitemiiicolor}{rgb}{0,0,.6}
 
\def\labelitemi{\color{labelitemicolor}{$\blacktriangleright$}}
\def\labelitemii{\color{labelitemiicolor}{{\large$\bullet$}}}
\def\labelitemiii{\color{labelitemiiicolor}
  {{\raisebox{.3ex}{\mbox{\scriptsize$\blacksquare$}}}}}

\def\bibcolor#1{{\color[named]{MidnightBlue}#1}}
%\def\bibcolor#1{{\color[cmyk]{.8,.8,0,.4}#1}}

\def\headcolor#1{{\color[named]{BrickRed}#1}}

\def\hrefcolor#1{{\color[named]{Fuchsia}#1}}
%\def\hrefcolor#1{{\color[cmyk]{.3,1,0,.6}#1}}
\def\xbibcolor#1{{\color[named]{Fuchsia}#1}}
%\def\xbibcolor#1{{\color[cmyk]{.3,1,0,.6}#1}}

%\def\codecolor{\color[named]{OliveGreen}}
\def\codecolor{\color[cmyk]{.65,0,.65,.7}}
%%%\def\codecolor{\color[cmyk]{.65,0,.65,.0}}

\def\pkg#1{{\sffamily#1}}

\def\marginnote#1{\marginpar{\headcolor{\textit{#1}}}}
\def\marginnote#1{\vadjust{\llap{\smash{\headcolor{\textit{#1~~}}}}}}
\def\marginnote#1{\leavevmode\llap{\headcolor{\textit{\smash{\parbox[t]{2.5cm}{\raggedleft #1}~~}}}}}




\def\mailto#1{$\langle$\href{mailto:#1}{\texttt{\hrefcolor{#1}}}$\rangle$}


\def\URL#1{{\fontfamily{cmvtt}\selectfont{\xbibcolor{http://#1}}}}

\def\indenturl{\leavevmode\texttt{\phantom{xx}}}
\def\http#1{\ifvmode\leavevmode\texttt{\phantom{xx}}\fi\href{http://#1}{\URL{#1}}}
\def\ftp#1{\ifvmode\leavevmode\texttt{\phantom{xx}}\fi\href{ftp://#1}{\URL{#1}}}

\def\path#1{\texttt{#1}}
\def\file#1{\texttt{#1}}

%%% Internal/External Documentation

\def\texmfdocvi{../../../../texmf-doc/doc/vietnamese}
\def\CTANbase{ctan.org/tex-archive/info}

\def\bibfile#1#2#3{\textit{#1, }\href{file:#2}{\bibcolor{#3}}} 
\def\bibfilenoauthor#1#2{\href{file:#1}{\bibcolor{#2}}} 
\def\bibfileprint#1{\ifx\printversion\undefined\hspace{\fill}\href{file:#1}{[\bibcolor{print~version}]}\fi} 

\def\xbibfile#1#2#3{\textit{#1, }\href{http://#2}{\xbibcolor{#3}}} 
\def\xbibfilenoauthor#1#2{\href{http://#1}{\xbibcolor{#2}}} 

\def\extbibfile#1#2#3{\textit{#1}, #2,\\\href{http://#3}{\fontfamily{cmvtt}\selectfont{\xbibcolor{http://#3}}}}

\def\xbibfileprint#1{\hspace{\fill}\ifx\printversion\undefined\href{http://#1}{[\bibcolor{print~version}]}\fi} 

%%%\reversemarginpar

% \makeatletter
% \let\docpath\@namedef
% %\InputIfFileExists{vntexdoc-conf.tex}{}{}

% \makeatletter
% \let\docpath\@nameuse
% \makeatother

%%% Verbatim

\newenvironment{code}{\codecolor}{}
\newenvironment{verbcode}{\codecolor\begin{verbatim}}{\end{verbatim}}
\def\code{\ifvmode~~~\fi\codecolor} %%% \setbox0 \wd0

\CustomVerbatimEnvironment{Code}{Verbatim}
   {commandchars=\|\(\),formatcom=\codecolor}
\def\texcomment#1{\textrm{\textcolor{black}{#1}}}
\def\sometext#1{\textcolor{black}{\textrm
   {$\langle$\ldots\textit{#1}\ldots$\rangle$}}}

\AtBeginDocument{\def\abstractname{\headcolor{\textbf{\normalsize
        Abstract}}}}

\advance\oddsidemargin by -.5cm
%\advance\marginparwidth 1cm
\evensidemargin=\oddsidemargin
\advance\textwidth by 2cm
\advance\topmargin by -2cm
\advance\textheight by 4cm
\advance\textheight by 2pt

%%% From File: ltlogos.dtx
\makeatletter
\DeclareRobustCommand{\LaTeX}{L\kern-.26em% orig: -.36em
  {\sbox\z@ T\vbox to\ht\z@{\hbox{\check@mathfonts
   \fontsize\sf@size\z@\math@fontsfalse\selectfont{}A}\vss}}%
   \kern-.07em% orig: -.15em
   \TeX}\makeatother

%%%\def\TeX{T\kern-.1667em\lower.5ex\hbox{E}\kern-.125emX\@}

\makeatletter
\DeclareRobustCommand{\XeTeX}{X\kern-.125em
  \lower.5ex\hbox{\reflectbox{E}}\kern-.1667em\TeX}\makeatother

\def\releasenotes{
  \parskip 0pt
  \def\version[##1]##2##3{\par\normalfont\normalsize
    \textcolor[named]{BrickRed}{Version~\textbf{##2}} --- released ##3
    ##1\par\penalty10000\small}}

\edef\YR{\number\year}
\edef\MO{\ifnum\month<10 0\fi\number\month}
\edef\DY{\ifnum\day<10 0\fi\number\day}

\usepackage[unicode, colorlinks, urlcolor=black, filecolor=black,
pdfdisplaydoctitle=true]{hyperref}

% we need \hypersetup if we are using unicode
\hypersetup{pdftitle={VnTeX - Typesetting Vietnamese (Revision \YR/\MO/\DY)}}
\hypersetup{pdfsubject={VnTeX User Manual}}
\hypersetup{pdfauthor={Hàn Thế Thành and Reinhard Kotucha}}
\hypersetup{pdfkeywords={VnTeX, typesetting Vietnamese, Vietnamese fonts,
  encodings, LaTeX macro packages}}

\hypersetup{pdfnewwindow=true}

\begin{document}
\leavevmode{\centering\Huge\textbf{\headcolor{Vn\TeX\ --- Typesetting
  Vietnamese}}\par}
\vspace{3mm}
{\centering\Large Hàn Thế Thành~~~~Reinhard Kotucha\par}
\vspace{1cm}

\begin{abstract}
\vspace*{-1ex}\parskip=1ex \parindent=0pt \noindent 
Vn\TeX\ is an extension to Donald Knuth's \TeX\ typesetting system which
provides support for typesetting Vietnamese.

The primary site of Vn\TeX\ is {\normalsize\http{vntex.sf.net}}.
\end{abstract}

\section{Where to get Help}
The current maintainers of Vn\TeX\ are:
\begin{itemize}
\item Hàn Thế Thành \mailto{HanTheThanh@gmail.com}
\item Reinhard Kotucha \mailto{Reinhard.Kotucha@web.de}
\item Werner Lemberg \mailto{WL@gnu.org}
\end{itemize}

There is a mailing list (very low traffic) for questions about
Vn\TeX\ and typesetting Vietnamese.  To subscribe to the list, visit:

\http{lists.sourceforge.net/lists/listinfo/vntex-users}

There is also a Wiki:

\http{vntex.info}

\section{Related Documents}
The following files are part of the Vn\TeX\
distribution\ifx\printversion\undefined\footnote{The print versions
  should be used with monochrome printers. A print version of this
  file is \href{vntex-print.pdf}{\bibcolor{here}}.}\fi
\begin{itemize}
%\href{}{\bibcolor{here}}}
%%%%\item \href{file:vntex-man.pdf}{VnTeX Manual}
\item \bibfile{Hàn Thế Thành}{vntex-man.pdf}{Hỗ trợ tiếng Việt cho \TeX}
  \ifx\printversion\undefined\bibfileprint{vntex-man-print.pdf}\fi
\item \bibfile{Hàn Thế Thành} {vn-min.pdf}{Minimal steps to typeset
    Vietnamese} \bibfileprint{vn-min-print.pdf}
\item \bibfile{Hàn Thế Thành và Thái Phú Khánh Hòa} {vn-fonts.pdf}
  {Dùng font với Vn\TeX} \bibfileprint{vn-fonts-print.pdf}
\end{itemize}
The following files are not part of Vn\TeX\ but might be part of the
\TeX\ distribution you are using. 
% \begin{itemize}
% \item \ifundefined{vntexdoc-amsldoc-vi}
%   {\xbibfile{The American Mathematical Society}{\CTANbase/amslatex/vietnamese/amsldoc-vi.pdf}
%     {Hướng dẫn sử dụng gói \pkg{amsmath}}.}
%   {\bibfile{The American Mathematical Society}{\docpath{vntexdoc-amsldoc-vi}}{Hướng dẫn sử dụng gói
%       \pkg{amsmath}}}
%   Translated by Huỳnh Kỳ Anh.
%   \ifundefined{vntexdoc-amsldoc-vi}
%   {\xbibfileprint{\CTANbase/amslatex/vietnamese/amsldoc-print-vi.pdf}}
%   {\bibfileprint{\docpath{vntexdoc-amsldoc-print-vi}}}
% \item \ifundefined{vntexdoc-lshort-vi}
%   {\xbibfile{H.~Partl, E.~Schlegl, I.~Hyna, T.~Oetiker}
%     {\CTANbase/lshort/vietnamese/lshort-vi.pdf}{Một tài liệu ngắn gọn
%       giới thiệu về \LaTeXe}.}
%   {\bibfile{H.~Partl, E.~Schlegl, I.~Hyna, T.~Oetiker}
%     {\docpath{vnzexdoc-lshort-vi}} {Một tài liệu ngắn gọn
%       giới thiệu về \LaTeXe}.} 
%   Translated by Nguyễn Tân Khoa.

% \item \bibfile{Wolfgang May, Andreas
%     Schlechte}{\texmfdocvi/ntheorem-vn/ntheorem-doc-vn.pdf} {Mở rộng
%     môi trường định lý}. Translated by Huỳnh Kỳ Anh.
%\end{itemize}

\begin{itemize}
\item \textit{The American Mathematical Society}, Hướng dẫn sử dụng gói
      \pkg{amsmath},\\ 
      \http{\CTANbase/amslatex/vietnamese/amsldoc-vi.pdf}\\
      \http{\CTANbase/amslatex/vietnamese/amsldoc-print-vi.pdf}

\item \textit{H.~Partl, E.~Schlegl, I.~Hyna, T.~Oetiker}, Một tài
      liệu ngắn gọn giới thiệu về \LaTeXe, Translated by Nguyễn Tân Khoa.\\
      \http{\CTANbase/lshort/vietnamese/lshort-vi.pdf}

\item \textit{Wolfgang May, Andreas Schlechte}, Mở rộng
      môi trường định lý. Translated by Huỳnh Kỳ Anh.\\
      \http{\CTANbase/translations/vn/ntheorem-doc-vn.pdf}
\end{itemize}


\section{Typesetting Vietnamese}

In order to typeset Vietnamese, you need a text editor which supports
Vietnamese.  In particular, it should support an \emph{input encoding}
and an \emph{input method} suitable for Vietnamese.

If you are not familiar with encodings, here is a brief explanation:
Each key on your keyboard is assigned to a letter.  Computers don't
understand letters, they only understand numbers.  The table which
assigns letters to numbers is called \emph{input encoding}.

\marginnote{input encoding}A popular input encoding system used in
Vietnam is VISCII.  The problem is that only 256 characters can be
used at the same time.  It's sufficient for typesetting Vietnamese,
however, it's not well suited for multilingual texts.  A better
approach had been provided by the Unicode Consortium: UTF-8.  This is
a very efficient encoding system which supports all writing systems of
the world.  You can have Vietnamese, Arabic, Korean, Ethiopian,
Hindi,\ldots characters in one and the same file.  UTF-8 is the
encoding system of the future and it becomes even more popular in
Vietnam.

Vn\TeX\ supports many input encodings such as VISCII, TCVN, or UTF-8,
but there is no support for VNI (nor will there ever be).

You can use the input encoding of your choice, but you have tell \TeX\
which one you are using.  How to do this is decribed below.

\marginnote{font encoding}There is a similar issue with fonts.  A font
is a collection of \emph{glyphs}.  A glyph is the graphical
representation of a character.  Graphical representations of the
character \texttt{a} might be `a', `\textit{a}', or `\textbf{a}', for
example.  Fonts never contain characters; they contain only glyphs,
sometimes more than a single glyph for a given character.  A font
usually contains more than 256 glyphs, but \TeX\ can only access 256
characters at the same time. The table which maps characters to glyphs
is called a \emph{font encoding}.

However, if you are using \LaTeX, a name is assigned to each character
read from the keyboard.  This way it can deal with an arbitrary number
of characters internally.  You can specify more than one font encoding
and \LaTeX\ switches between them automatically.  In most cases it's
sufficient to know that font encoding |T1| supports Western European
languages and |T5| supports Vietnamese.

\marginnote{input method}But how to enter all the characters if you
have only an American keyboard?  You have to select an \emph{input
  method}.  An input method allows you to access characters which are
not supported by your keyboard.  If you select VIQR as an input
method, you can write ``\verb/Ha` No^.i/'' on your keyboard but you
see ``\texttt{H\`a N\d\ocircumflex i}'' on screen and you get ``H\`a
N\d\ocircumflex i'' in your typeset document.

However, input methods are quite system dependent.  If your operating
system doesn't support anything appropriate, check whether your editor
or \TeX\ shell supports them.

\marginnote{editors}It's not easy to propose a particular editor.  If
you are using a reasonably powerful editor for writing your own
programs, then use it for \TeX\ too.

Editors which are supposed to work on all operating systems are
\xbibfilenoauthor{www.vim.org}{\pkg{vim}},
\xbibfilenoauthor{gnu.org/software/emacs}{\pkg{Emacs}},
\xbibfilenoauthor{www.xm1math.net/texmaker}{\pkg{\TeX{}Maker}}, and 
\xbibfilenoauthor{tug.org/texworks}{\pkg{\TeX{}works}}.
On Windows there are some alternatives, like 
\xbibfilenoauthor{projectory.de/texshell}{\pkg{\TeX{}shell}}, 
\xbibfilenoauthor{www.winedt.com}{\pkg{WinEDT}}, and
\xbibfilenoauthor{www.texniccenter.org}{\pkg{\TeX{}nicCenter}}.
\xbibfilenoauthor{www.texniccenter.org}{\pkg{\TeX{}nicCenter}}
supports UTF-8 as of version 2.0.

If you are on Mac\,OS\,X,
\xbibfilenoauthor{www.uoregon.edu/~koch/texshop}{\pkg{\TeX{}shop}} is
a good choice.  \pkg{\TeX{}shop} is aimed at beginners but it is
extremely powerful though.  It provides a very fast PDF viewer and if
you click on a particular word in the PDF file, the cursor moves to
this word in the text editor, and vice
versa. \xbibfilenoauthor{tug.org/texworks}{\pkg{\TeX{}works}} is
something very similar. But it is supposed to work on all operating
systems and is shipped with \TeX~Live and Mik\TeX.

There are some different flavours of \TeX, such as Plain \TeX, \LaTeX,
and Context. \LaTeX\ is the most popular one and there are many books
available about it.

\subsection{Typesetting with \LaTeX}

The idea of \LaTeX\ is to treat content and layout separately.  If you
never used \LaTeX\ before, please read {\xbibfilenoauthor
  {\CTANbase/lshort/vietnamese/lshort-vi.pdf}{Một tài liệu ngắn gọn
    giới thiệu về \LaTeXe}} first.

\subsubsection{Using \pkg{vietnam} or \pkg{vntex}}

There are two packages, \pkg{vietnam} and \pkg{vntex}.  They are quite
similar, the only difference is that the default input encoding is VISCII
in \pkg{vietnam} and UTF-8 in \pkg{vntex}.  However, both packages
allow you to specify any supported input encoding.  The following
encoding systems are supported:

\begin{tabular}{ll}\hline
  \code{|viscii|}     &  use VISCII input encoding\\
  \code{|mviscii|}    &  use MVISCII input encoding\\
  \code{|tcvn|}       &  use TCVN input encoding\\
  \code{|vps|}	      &  use VPS input encoding\\
  \code{|utf8|}	      &  use UTF-8 input encoding (\LaTeX)\\
  \code{|utf8x|}      &  use UTF-8 input encoding (ucs package)\\
  \code{|noinputenc|} &  do not load the inputenc package (use of TCX is assumed)\\\hline
\end{tabular}

Examples: %\par\kern -2pt % avoid and unpleasant page break
\begin{Code}
  \documentclass{report}
  \usepackage{vietnam} % |texcomment(use VISCII input encoding)
  \begin{document}
  |sometext(text in VISCII encoding)
  \end{document}
\end{Code}

\begin{Code}
  \documentclass{report}
  \usepackage{vntex} % |texcomment(use UTF-8 input encoding)
  \begin{document}
  |sometext(text in UTF-8 encoding)
  \end{document}
\end{Code}

\begin{Code}
  \documentclass{report}
  \usepackage[tcvn]{vntex} % |texcomment(use TCVN input encoding)
  \begin{document}
  |sometext(text in TCVN encoding)
  \end{document}
\end{Code}

Both packages, \pkg{vietnam} and \pkg{vntex}, have the following
additional options:

\begin{tabular}{ll}\hline
  \code{|nocaptions|} &  do not define Vietnamese captions\\
  \code{|varioref|} &  load the \pkg{varioref-vi} package\\
  \code{|cmap|} & load the \pkg{cmap} package\\\hline
\end{tabular}

If the option {\code|nocaptions|} is set, then captions
are typeset in English.  On the other hand, if you are using the
\pkg{varioref} package, you might want to set
the {\code|varioref|} option in order to get
``\h{\ohorn} trang li\`\ecircumflex{}n sau'' instead of ``on the
following page'', for example.

The \pkg{cmap} packages makes the PDF file searchable.

\newpage
\subsubsection{Using \pkg{babel} instead of
  \pkg{vietnam}/\pkg{vntex}}

For multilingual documents it's better to use the \pkg{babel} package,
which is part of the \LaTeX\ core.  Though the \pkg{inputenc} package
allows you to select the input encoding of your choice, UTF-8 is the
preferred encoding for multilingual documents.

\begin{Code}
  \documentclass{report}
  \usepackage[T2A,T5]{fontenc}
  \usepackage[utf8]{inputenc} 
  \usepackage[russian,vietnamese]{babel}
  \begin{document}
     Tiếng Việt,
     \selectlanguage{russian}%
     |selectlanguage(russian)русский язык, 
     \selectlanguage{vietnamese}%
     |selectlanguage(vietnamese)tiếng Việt.
  \end{document}
\end{Code}

Note that last optional argument passed to \pkg{babel} is the language
which is active at the beginning of your document.

The result of the example above is:~~ 
{\fboxsep5pt
  \fbox{\fontfamily{lmr}\large 
    Tiếng Việt,
    \selectlanguage{russian}%
    русский язык,
    \selectlanguage{vietnamese}%
    tiếng Việt.}}

\subsubsection{Using \pkg{hyperref}}
In order to use Vietnamese characters in the bookmark panel or in the
``Document Properties'' box, \pkg{hyperref} must be loaded with the
{\code|unicode|} option.

\begin{Code}
  \usepackage[unicode]{hyperref}
  \hypersetup{pdftitle={VnTeX – hỗ trợ tiếng Việt cho TeX}}
\end{Code}

\subsubsection{Using \pkg{TCX} files}
\TeX\ itself can't use non-ASCII characters when writing error
messages to screen or to the log file.  Instead, it prints non-ASCII
chacters in hexadecimal notation, like |^^DF|.  But there is an
extension called \pkg{TCX}.  If you activate \pkg{TCX}, a translation
table is loaded, and all files \TeX\ reads are translated before they
are processed.  If you are using \pkg{TCX}, you can't use the
\pkg{inputenc} package because the translation can be done only once.

If you are using an engine which supports UTF-8 natively, like \XeTeX\
or Lua\TeX\, you can't use \pkg{TCX} (and you don't need to).

% \pkg{TCX} and \pkg{inputenc} are more or less equivalent.  The
% advantage of \pkg{TCX} is that you get Vietnamese characters in
% messages about overfull/underfull boxes and the like.  The main
% drawback is that it doesn't support UTF-8.  On the other hand, \XeTeX\
% and Lua\TeX\ support UTF-8 natively but not \pkg{TCX}.

Vn\TeX\ provides two \pkg{TCX} tables, {\code|viscii-t5|} and
{\code|tcvn-t5|}.  Here is an example:

\begin{Code}
  %& -translate-file=viscii-t5
  \documentclass{report}
  \usepackage[noinputenc]{vntex}
  \begin{document}
  |sometext(text in VISCII encoding)
  \end{document}
\end{Code}

The very first line says that the option {\code|-translate-file=viscii-t5|}
is passed to \TeX\ when compiling the document.  It has the same effect
as if you run

     {\code|latex -translate-file=viscii-t5 foo.tex|}

on the command line.  Using TCVN is similar.

%\newpage

\subsubsection{Creating HTML from \LaTeX\ sources}

In order to create HTML documents from \LaTeX\ sources, run

   {\code|tex4ht "html,uni-html4,charset=utf8"|} \textit{yourfile.tex}

on the command line.  You can't use \pkg{TCX} with \pkg{tex4ht}.

\subsection{Typesetting with plain TeX}

Unfortunately, there is no package for UTF-8 input encoding in plain
TeX yet.  

\subsubsection{\pkg{plainenc} and \pkg{plnfss}}

\pkg{plnfss} provides a \LaTeX-like interface for font selection.  

\begin{Code}
  \input t5code
  \input plnfss
  \input plainenc
  \fontencoding{T5}
  \inputencoding{viscii} % |texcomment(or any other encoding mentioned)
                         % |texcomment(above except |texttt(utf8))
  \setfontencoding{T5}
  \selectfont
  |sometext(text in VISCII encoding)
  \bye
\end{Code}

\pkg{plainenc} and \pkg{plnfss} are not part of the Vn\TeX\
distribution any more but it is very likely that they are part of the
\TeX\ system you are using.

%If you have a version of \pkg{plnfss}\ which doesn't already support
%Vietnamese, please install

%\http{vntex.sf.net/download/vntex-support/plnfss.zip}

\subsubsection{Using \pkg{TCX}}

\pkg{TCX} files can be used as described in the \LaTeX\ section.

\begin{Code}
  %& -translate-file=viscii-t5
  \input t5code
  \input plnfss
  \setfontencoding{T5}
  \selectfont
  |sometext(text in VISCII encoding)
  \bye
\end{Code}

\subsection{Using \pkg{texinfo}}
TCX is required:
\begin{Code}
  %& -translate-file=viscii-t5
  \def\fontprefix{vn}
  \input t5code.tex
  \input texinfo
  |sometext(text in VISCII encoding)
\end{Code}

There are some test files for Vn\TeX\ in |texmf*/source/latex/vntex/tests/|.
Please read the file \pkg{README} in this directory.


\section{Vietnamese Fonts}

Vn\TeX\ provides a lot of Vietnamese fonts.  If you are using
{\code|T5|} font encoding but do not specify any font (as in the
examples above) you get \pkg{Vietnamese Computer Modern}.  These VNR
fonts are extensions to Donald Knuth's \pkg{Computern Modern Fonts}
and were designed by Hàn Thế Thành.

\subsection{Acquiring Vietnamese Fonts}

\subsubsection{Fonts provided by Vn\TeX}

The following fonts are part of Vn\TeX.  Vietnamese Glyphs were added
by Hàn Thế Thành.
\begin{itemize}
\item Arev (a version of Bitstream Vera Sans)
\item Bitstream Charter
\item Computer Modern
\item Computer Modern Bright
\item Concrete
\item txtt
\item URW Grotesk
\item urwvn (URW version of Adobe's LaserWriter fonts)
\item Vntopia (based on Adobe Utopia)
\end{itemize}

\subsubsection{Vn\TeX\ nonfree Fonts}
%\marginnote{nonfree fonts}Vn\TeX\ provides Vietnamese versions of free
%fonts donated by Adobe, URW, and Bitstream.  

Some of the fonts donated by URW can be used freely but they can't be
distributed if money is charged for the distribution.  These fonts are
not part of the Vn\TeX\ core distribution because otherwise Vn\TeX\
can't be in \pkg{TeX Live} or in Linux distributions.

These fonts are:
\begin{itemize}
\item URW Classico (URW version of Hermann Zapf's Optima)
\item URW Garamond
\end{itemize}

There is an extra package containing these fonts:

\indenturl\http{vntex.sourceforge.net/download/vntex/vntex-nonfree.zip}\\
\indenturl\http{vntex.sourceforge.net/download/vntex/vntex-nonfree.tar.xz}

If you are using \pkg{TeX Live}, you can download and execute
\pkg{install-getnonfreefonts} from

\indenturl\http{tug.org/fonts/getnonfreefonts}

and run {\code|getnonfreefonts --help|} on the command line for more
information.

\subsubsection{Microsoft Core Fonts}

Support for Microsoft's \emph{Web Fonts} was removed from Vn\TeX\
because the actual fonts cannot be provided for legal reasons.  Please
consult the \href{http://vntex.sf.net}{\xbibcolor{Vn\TeX\ homepage}}
for more information.

\subsubsection{Other Fonts supporting Vietnamese}


There are many other fonts supporting Vietnamese which are not shipped
with Vn\TeX\ because they are an integral part of any modern \TeX\
distribution anyway.

\newpage

% \marginnote{\pkg{Latin Modern} and \pkg{\TeX Gyre}} Some quite
% interesting fonts are the \pkg{Latin Modern} and \pkg{\TeX\ Gyre}
% fonts created by Bogus\l{}aw Jackowski and Janusz M. Nowacki.  They
% fully support Vietnamese but their main advantage is that they support
% virtually all Latin scripts used today.  Thus, they are well suited
% for multilingual documents.

\marginnote{font samples}There are sample files of all fonts which
support Vietnamese, can be used with \TeX, and can be used freely,
even commercially.  However, some of them can't be distributed if you
charge money for the distribution.

\http{vntex.sf.net/fonts/samples}

Not every font supports maths.  If you have to typeset math
formulas, consult:

\http{ctan.org/tex-archive/info/Free\_Math\_Font\_Survey/vn/survey-vn.pdf}


\subsection{Font Selection}

We describe how to use fonts with \LaTeX\ first.  A description of
\pkg{plnfss} (plain TeX) is given below.

\subsubsection{Selecting Fonts in \LaTeX}
Some fonts provide a \LaTeX\ macropackage which loads the necessary
fonts.

To use Latin Modern instead of VNR, simply
\begin{Code}
   \usepackage{lmodern}
   \usepackage{vntex}
\end{Code}

For Antikwa Toru\'nska, do
\begin{Code}
   \usepackage{anttor}
   \usepackage{vntex}
\end{Code}
   
\ldots or use \pkg{inputenc} and \pkg{babel} instead of \pkg{vietnam}
or \pkg{vntex}.

Some font packages do not provide such a \LaTeX\ macro package.  An
example is \pkg{urwvn}.

It is recommended to specify a roman font, a sans-serif font and a
typewriter font separately.  You do not have to specify all of them.
It makes sense, for instance, not to specify a typewriter font --- you
get Computer Modern Typewriter then, which is a good choice.

\begin{tabular}{lll}\hline
Command                               & PostScript Name   & Font Family Name\\\hline
{\code|\renewcommand\sfdefault{uag}|} & |VnURWGothicL|    & AvantGarde\\
{\code|\renewcommand\rmdefault{ubk}|} & |VnURWBookmanL|   & Bookman\\
{\code|\renewcommand\ttdefault{ucr}|} & |VnNimbusMonL|    & Courier\\
{\code|\renewcommand\sfdefault{uhv}|} & |VnNimbusSanL|    & Helvetica\\
{\code|\renewcommand\rmdefault{unc}|} & |VnCenturySchL|   & New Century Schoolbook\\
{\code|\usepackage{mathpazo}|}        & |VnURWPalladioL|  & Palatino\\
{\code|\usepackage{mathptm}|}         & |VnNimbusRomNo9L| & Times\\\hline
\end{tabular}

\marginnote{small caps}There is also a real small caps font for
|VnURWPalladioL|, made by Ralf Stubner and extended by Hàn Thế Thành.
There are still some support files missing.

By default, you get the faked small caps but you can use real small caps with
some restrictions.  To make use of them, put the following macro definition
into the preamble of your document:

{\code|\newcommand{\textfplsc}[1]{\bgroup\usefont{T5}{fpl}{m}{sc}#1\egroup}|}

You can use it like this:

 {\code||\sometext{some text} 
 \code|\textfplsc{|\sometext{some text in small caps}\code|}| 
 \sometext{some text}} 

The macro argument should not contain any numbers because they will appear
as oldstyle numbers.% but you cannot use oldstyle numbers with other font
%shapes in T5 encoding (Vietnamese) yet.  This problem will be fixed in a
%future release.

\marginnote{math fonts}If you have to typeset math formulas, be aware
that not all fonts support math.  The following fonts support math
very well:

\begin{tabular}{ll}\hline
  Font            & Command \\\hline
  Computer Modern & do nothing \\
  Latin Modern    & {\code|\usepackage{lmodern}|}  \\
  Palatino        & {\code|\usepackage{mathpazo}|} \\
  Times           & {\code|\usepackage{mathptm}|}  \\\hline
\end{tabular}

There are many others too, please consult:

%  \http{ctan.org/tex-archive/info/Free\_Math\_Font\_Survey/vn/survey-vn.pdf}
  \http{vntex.sf.net/fonts/samples/survey-vn.pdf}

  However, some of the fonts borrow math symbols from other fonts and
  it's worthwhile to check whether all the symbols you need blend well
  with the base font you are using.  Be very careful when using
  \textsf{sans-serif} fonts in math formulas.  It's very
  painful if there is no significant difference between ``\textsf{l}''
  and ``\textsf{I}''.  Do you see any difference at all?  The first
  one is a lowercase ``\texttt{L}'', the second one is an uppercase
  ``\texttt{i}''.

%\clearpage

\marginnote{MS core fonts}If you are using Windows, you also can use
the fonts provided by Microsoft:

\begin{tabular}{lll}\hline
Command                                 & PostScript Name     & Font Family Name\\\hline
  {\code|\renewcommand\sfdefault{ma1}|} & |ArialMT|           & Arial \\
  {\code|\renewcommand\ttdefault{mcr}|} & |CourierNewPSMT|    & Courier \\
  {\code|\renewcommand\rmdefault{lpr}|} & |PalatinoLinotype|  & Palatino \\
  {\code|\renewcommand\rmdefault{mns}|} & |TimesNewRomanPSMT| & Times New Roman \\
  {\code|\renewcommand\sfdefault{jth}|} & |Tahoma|            & Tahoma \\
  {\code|\renewcommand\sfdefault{jvn}|} & |Verdana|           & Verdana \\\hline
\end{tabular}

None of the Microsoft fonts supports mathematics.  Though the quality of 
the fonts is quite high, not much care had been taken in the design of
Vietnamese accents (except in \emph{Palatino Linotype}).  See:

	\http{vntex.sf.net/fonts/samples}

Unless someone insists that you use these fonts, you can use

\begin{tabular}{lll}\hline
  |VnNimbusMonL|    & instead of |CourierNewPSMT|    & Courier\\
  |VnNimbusSanL|    & instead of |ArialMT|           & Helvetica/Arial\\
  |VnNimbusRomNo9L| & instead of |TimesNewRomanPSMT| & Times/Times New Roman\\
  |VnURWPalladioL|  & instead of |PalatinoLinotype|  & Palatino\\\hline
\end{tabular}

\subsubsection{Selecting Fonts in plain \TeX}

If you are using plain \TeX, you can use \pkg{plnfss.tex} to select fonts.

% Instead of 
% \begin{Code}
%   \renewcommand\rmdefault{...}
%   \renewcommand\sfdefault{...}
%   \renewcommand\ttdefault{...}
% \end{Code}

% you have to select fonts like this:
\begin{Code}
  \setrmdefault{...}
  \setsfdefault{...}
  \setttdefault{...}
\end{Code}

See the \pkg{plnfss} documentation for more details.

\section{Licenses}

The URW and Bitstream Type1 fonts are copyrighted under the GNU GPL,
\texttt{.map} files are public domain, \pkg{varioref-vi.sty} is under
LGPL, \pkg{Vntopia} is under the Adobe/TUG Utopia license agreement,
all other files are under LPPL, version 1.3 or newer.

\begin{itemize}
\item \http{www.gnu.org/licenses/gpl.txt}
\item \http{www.gnu.org/licenses/lgpl.txt}
\item \http{www.latex-project.org/lppl.txt}
\item \http{tug.org/fonts/utopia/LICENSE-utopia.txt}
\end{itemize}

%\clearpage


\section{Contributors}
The author of Vn\TeX\ is Hàn Thế Thành.  Current maintainers are
Reinhard Kotucha and Werner Lemberg.

\LaTeX\ support (input encoding files, font encoding files,
\pkg{babel} support files and vietnam.sty) were provided by Werner
Lemberg.  \pkg{vntex.sty} was proposed by Huỳnh Kỳ Anh.

Vietnamese fonts for \pkg{tex4ht} originally were provided by Hàn
Thế Thành, but they are now part of the \pkg{tex4ht} distribution.

\pkg{plnfss} was written by Hàn Thế Thành and Michal Konečný.  It was
removed from Vn\TeX\ because it supports many other languages as well.

\section{Known Problems}
\begin{itemize}
\item In order to use \pkg{amsart.cls} (and other AMS \LaTeX\ document
  classes) with Unicode you must add the following lines immediately
  before {\code|\begin{document}|}:
\begin{Code}
  \def\firstofone#1{#1}
  \let\uppercase\firstofone
  \let\MakeUppercase\firstofone
\end{Code}
\end{itemize}

This completely disables \LaTeX's uppercasing commands which might
cause bad secondary effects.  Note that this problem is not specific
to Vietnamese but affects any multibyte encoding.

\ifx\printversion\undefined
\section{Release Notes}
   The Vn\TeX\ history is \bibfilenoauthor{ReleaseNotes.pdf}{here}.
\fi


\end{document}

% \item In order to use Vn\TeX\ with \pkg{prosper}, you have to install
  
%   \http{vntex.sf.net/download/vntex-support/prosper-vn.zip}

% \item In order to use Vn\TeX\ with \pkg{prosper}, put the lines
% \begin{verbatim}
%   \usepackage[T1,T5]{fontenc}
%   \def\usefont#1#2#3#4{%
%     \fontfamily{#2}\fontseries{#3}\fontshape{#4}\selectfont}
% \end{verbatim}
% into the preamble before you laod \pkg{prosper}.  Or better use
% \pkg{beamer} instead.

  
% \item In order to use Vn\TeX\ with Foil\TeX, you have to install

%   \http{vntex.sf.net/download/vntex-support/foiltex-vn.zip}
  
% \item If you have an old version of \LaTeX\ which does not support
%   UTF-8, you have to use \pkg{ucs.sty}.  If \pkg{ucs.sty} is not
%   present on your system you can install
  
%   \http{vntex.sf.net/download/vntex-support/ucs-vn.zip}
  
%   We will keep this file as long as \pkg{ucs} is unmaintained.  If
%   a maintainer is found you should download a fresh \pkg{ucs}
%   distribution from the original site.
  
%   This is a small subset of the \pkg{ucs} package which supports
%   Vietnamese only.  You can invoke it with
%   {\code|\usepackage[utf8x]{inputenc}|}.
  
%   Instead of installing ucs we recommend you update \LaTeX.  The
%   latest version can be downloaded from
  
%   \begin{itemize}
%   \item \leavevmode\http{www.dante.de/tex-archive/macros/latex/base.zip} (Germany)
%   \item \leavevmode\http{www.tex.ac.uk/tex-archive/macros/latex/base.zip}  (UK)
%   \item \leavevmode\http{tug.ctan.org/tex-archive/macros/latex/base.zip}  (USA)
%   \end{itemize}

__
Everything below the line above is ignored.

Local Variables:
coding: utf-8
End:

%%% initemxf --edit-config-file updmap


% \marginnote{MS core fonts}The Microsoft core fonts are supported too.
% Vn\TeX\ only provides the additional files needed to make them
% accessible to \TeX, but not the fonts themselves.  If you are on
% Windows, they are available already.

% If you are on Unix, you have to install them yourself.

% \http{sourceforge.net/project/showfiles.php?group\_id=34153}

% Though the quality of the original fonts was quite good, the
% Vietnamese accents were added later, and obviously not by
% the guys who designed the fonts.  The only exception is \pkg{Palatino
%   Linotype}.  Inspect the fonts carefully before you decide which one
% you want to use.