path: root/language/gurmukhi/singh/manual.gm

@punjabi
%________________________________________________________________________
%
%    This program is free software; you can redistribute it and/or modify
%    it under the terms of the GNU General Public License as published by
%    the Free Software Foundation; either version 1, or (at your option)
%    any later version.
%
%    This program 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.  See the
%    GNU General Public License for more details.
%
%    You should have received a copy of the GNU General Public License
%    along with this program; if not, write to the Free Software
%    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
%________________________________________________________________________
\input gmmacs
\nopagenumbers
\hsize=6in

\font\title=cmr9 scaled\magstep5
\relax
\font\subtitle=cmr9 scaled\magstep2
\relax
\font\pal=cmr9

\bigskip\vbox{






}\bigbreak
\centerline{{\title Gurmukhi for \TeX}\footnote*{\TeX\ is a trademark of the
American Mathematical Society}}
\smallskip
\centerline{\title User Manual}
\smallskip
\centerline{\subtitle Version 1.0}
\centerline{\subtitle October 1995}
\bigskip
\bigskip
\centerline{\title Amarjit Singh}
\bigskip
\eject
{\subtitle Introduction}
\bigskip

The purpose of the ``Gurmukhi for \TeX'' software package is to convert the 
characters in a document from English Alphabet to Gurmukhi 
(script for the Punjabi language), utilizing the \TeX [1][2] and
METAFONT\footnote*{METAFONT is a trademark of Adddison Wesley Publishing Company}[3]
software packages.  \TeX\ is a typesetting system developed by the American
Mathematical Society, used widely on Unix systems, and occassionally on
other operating environments.  METAFONT is a font generation tool supported
by \TeX .  Both \TeX\ and METAFONT are free software packages which can be 
downloaded from \TeX\ archive sites[4].  A working knowledge of \TeX\ will 
greatly help in using the 'Gurmukhi for \TeX ' package.

This document provides information for preparing input text files and use of
the 'Gurmukhi for \TeX ' software.  This is the first version of the software
and it may undergo changes in the near future, so keep an eye out for
enhanced future releases.

\bigskip
{\subtitle Acknowledgement}
\bigskip
The Gurmukhi package was inspired by the Devanagari script generation 
package ``Devanagari for \TeX \footnote\dag{``Devanagari for \TeX '' is a copyright
of Frans J. Vethuis}'' which is developed by Frans J. Velthuis
and has been brought to you with his permission to support Gurmukhi script.
I would also like to thank my mother for repeatedly prompting me to write
a letter to her in Gurmukhi. Last, but not least, I would like to thank
everyone who might use this software package.

\bigskip
If you have comments or suggestion, feel free to send them to me at 
the following address:
\smallskip
\leftline{ E-mail: asingh@evolving.com }

\leftline{ Postal Mail: Amarjit Singh }
\leftline{ 8405 E. Hampden Ave \#11N Denver CO 80231 USA }
\leftline{ A-3 Mansarover Garden, New Delhi 110015 India }
\bigskip
\bigskip
{\subtitle Preparing a Document for Trans-literation }
\bigskip

A document is initially created using regular ASCII text. The text is 
then converted into Gurmukhi using simple transliteration rules, and 
most of \TeX\ features from the initial document are passed to an 
`intermediate' \TeX\ file. The generated output can be sent to a printer or
to the screen

This section describes what ASCII characters can be used to produce
Gurmukhi characters, and the delimiters which are required to put 
together these characters to pass to \TeX . Some control commands are
presented which you might use to modify the behaviour of this
tool to transform ASCII input text into Gurmukhi text. There is a macro
file for \TeX\ which should be included in your text file.
\bigskip
{\bf Characters}

Table 1 presents the ASCII to Gurmukhi character set translation.

To maintain the simplicity of transliteration, more than one 
character may be used, for example; 'kh' would be used to produce 
the Gurmukhi character {\gm kh}. Depending upon the context of 
a vowel, between the word or beginning of a word, a sign 
(like '{\gm \char69}') or a character (like '{\gm i}') will appear. 
An exception to this rule will be two vowels appearing together. 
There is a very limited number of half-characters in Gurmukhi and 
they are for h, v and r.

There are more than one ASCII character sets which can be used in 
input text, for representation of some Gurmukhi characters, like
'kh' and 'K' can be used for '{\gm K}' and it
is totally your choice to use any of them. 

In Gurmukhi text mode digits will appear as :
 
{\gm 0 0 1 2 3 4 5 6 7 8 9 }
\bigskip
\eject
\centerline{\bf Table 1: ASCII Character sets for Gurmukhi characters}
\smallskip
\settabs 8 \columns
\+u&{\gm u}&k&{\gm k}&t&{\gm t}&sh, S or "s&{\gm "s}\cr
\+uu&{\gm uu} or {\gm \char1}&kh or K&{\gm K}&th or T&{\gm T}&.kh or .K&{\gm .K}\cr
\+U&{\gm U} or {\gm \char1}&g&{\gm g}&d&{\gm d}&.g&{\gm .g}\cr
\+a&{\gm a} or&gh or G&{\gm G}&dh or D&{\gm D}&z&{\gm z}\cr
\+aa or A&{\gm A} or {\gm \char65}&"n&{\gm "n}&n&{\gm n}&f&{\gm f}\cr
\+i&{\gm i} or {\gm \char69}&c&{\gm c}&p&{\gm p}&N&{\gm N .ti~apI}\cr
\+ii&{\gm ii} or {\gm \char70}&ch or C&{\gm C}&ph or P&{\gm P}&.m or M&{\gm M biNdI}\cr
\+I&{\gm I} or {\gm \char70}&j&{\gm j}&b&{\gm b}&/&{\gm / caNdrabiNdU}\cr
\+e&{\gm e} or {\gm \char3}&jh or J&{\gm J}&bh or B&{\gm B}&\~\relax a&{\gm ~a aD~ak}\cr
\+ai or E&{\gm E} or {\gm \char123}&\~\relax n&{\gm ~n}&m&{\gm m}&@&{\gm @ (tOR)}\cr
\+o&{\gm o} or {\gm \char111}&.t&{\gm .t}&y&{\gm y}& {\tt |} &{\gm | (.dN.dA)}\cr
\+oo&{\gm oo} or {\gm \char79}&.th or .T&{\gm .T}&r&{\gm r}& {\tt ||}&{\gm ||}\cr
\+O&{\gm O} or {\gm \char79}&.d&{\gm .d}&l&{\gm l}&.o&{\gm .o}\cr
\+s&{\gm s} &.dh or .D&{\gm .D}&v&{\gm v}\cr
\+h&{\gm h} &.n&{\gm .n}&R&{\gm R}\cr

\bigskip
{\bf Delimiters}

All text appearing after \% up to the end of the line, will be
considered comments and will not generate any output. 

All the text between '$\{ \backslash gm$'  and '$\}$' will be converted to
Gurmukhi according to the character set shown in Table 1.

All the text between \$ signs will be converted to Gurmukhi when the @dollars
preprocessor command is given.

The following characters are allowed but do not change representation inside
Gurmukhi delimiters:

    ! ` ' ( ) * - : ; = ? , [ ] +

The following characters are not allowed inside Gurmukhi delimiters:

    {\tt <}  {\tt >} F L Q V W X Y Z \^ \_ q w x

Obviously, characters outside Gurmukhi delimiters will not be changed to
Gurmukhi and will be printed in English Alphabet or will follow the 
rules which you specify.

To change the pointsize of characters within '$\{ \backslash gm$' and '$\}$'
the following delimiters can be used, in incremental sizes, :
\smallskip

\bigskip
\settabs 2 \columns
\+ $\backslash gmsmall$     & 8 point font \cr

\+ $\backslash gmnine$      & 9 point font \cr

\+ $\backslash gmnormal$    & 10 point font \cr

\+ $\backslash gmbig$       & 10 point font, magnified at 1 step \cr

\+ $\backslash gmlarge$     & 10 point font, magnified at 2 steps \cr

\+ $\backslash gmhuge$      & 10 point font, magnified at 3 steps \cr

\bigskip
{\bf Examples}

Different character sets, following above mentioned rules, within Gurmukhi
delimilters can produce desired output, like $\{ \backslash gm$ paNjaab$\}$
and $\{ \backslash gm$ pNjAb$\}$ will print {\gm pNjAb}.

Sometimes, you may have to type an extra `a' to complete a syllable, even
though it may not appear in the Gurmukhi representation of that word.

There are additional gm files other than the source of this document, which
can be referred to for examples.
\bigskip
{\bf Control commands}

At the start of input text, the following preprocessor commands 
can be used, to control the functionality of the preprocessor:

@obeylines
    To follow the line breaks which you type. 

@dollars
    To activate \$ as a special symbol such that text delimited by \$
    is converted to Gurmukhi.

@punjabi
    Does not do anything right now, but may be used when the tool 
    supports other languages.

After the above preprocessor commands, insert the following command 
to include a macro file.  This ia a very important step because 
without the macro file, \TeX\ will not recognize the translated 
text generated by the preprocessor.

\input gmmacs

\bigskip
{\subtitle Transforming a Document}
\bigskip

The ``Gurmukhi for \TeX'' package consists of a preprocessor, font files
and a macro file. See the file ``readme'' and ``install.unix'' for 
installation steps. Installation should be fairly easy, as there is 
no system dependent code. Wherever you can find \TeX\ and metafont, 
you can very possibly install and use this package.
\bigskip
{\bf The Preprocessor}

The job of the preprocessor is to find the correct representation of a 
character according to its context. When a vowel appears in a word, 
a syllable completes, and context changes to what it was at the 
beginning of a new word. It also finds possible half representation of
characters. Output of this preprocessor is a \TeX\ document.
\bigskip
{\bf Example session of commands}

Lets assume that during installation you have prepared the preprocessor 
with name "gurmukhi" and have set paths in your environment to locate font and
macro files. Lets also assume that you have an input file with the name "text.gm".

You would start the preprocessor on the file 'text.gm' as follows:
\bigskip
\settabs 2 \columns
\+ gurmukhi text  & (to get a \TeX\ file)\cr
\bigskip

The \TeX\ file produced here, text.tex, can be used as any other input
file for \TeX . After this a typical sequence of commands may be
\bigskip
\settabs 2 \columns
\+   tex text     & (to get dvi file) \cr
\smallskip
\+   xdvi text    & (to view dvi file) \cr
\bigskip


Another sequence after this may be
\bigskip
\settabs 2 \columns
\+   dvips text    & ( to get postscript file text.ps from text.dvi ) \cr
\smallskip
\+   gs text.ps    & ( to view postscript file ) \cr
\smallskip
\+   ghostview text.ps & ( another way to view postscript file ) \cr
\bigskip


Now it is time to send the postscript file to a postscript printer, and
a command command for this may be:

   lp text.ps    


\bigskip
{\subtitle Devanagari}
\bigskip

This section is presented for those who have used the Devanagari package
or would also like to use the Devanagari package. There are not many 
differences between the two. In Devanagari, you create a text file
in the same manner as with Gurmukhi, but you have slightly different 
character sets for representation and you will use a similar sequence of
commands.

The differences in character sets in Gurmukhi and Devanagari are as
follows:

In Gurmukhi, S and sh can also be used in addition to "s to produce {\gm S}
and N is used in Gurmukhi to print {\gm N (.ti~apI)}, ii produces {\gm ii}
 and not {\gm I}, \~\relax a produces {\gm ~a}.

The Devanagari software package allows many character sets such as .s,
.h, H, q which are not valid in Gurmukhi.

\bigskip
{\subtitle What may be next:}
\bigskip

Support for LaTeX

Porting to different systems and platforms

Combination of Devanagari and Gurmukhi.

\bigskip
{\subtitle Biblography}
\bigskip
[1] Norman Walsh {\it Making \TeX Work} O'Reilly \& Associates, Inc. July 1994.

[2] Donald E. Knuth {\it The \TeX book} Addison Wesley Publishing Co. Sep 1993

[3] Donald E. Knuth {it The METAFONT Book} Addison Wesley, 

[4] FTP Site for \TeX\ and related softwares, including METAFONT, and Devanagri

\indent { \indent{ftp.shsu.edu/tex-archive}}

[5] Frans J. Velthuis {\it Devanagari for \TeX} Version 1.2 

\bye