path: root/Master/texmf-dist/doc/generic/babel/00readme.heb

% \iffalse meta-comment
%
% Copyright 1989-2005 Johannes L. Braams and any individual authors
% listed elsewhere in this file.  All rights reserved.
% 
% This file is part of the Babel system.
% --------------------------------------
% 
% It 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 in
%   http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2003/12/01 or later.
% 
% This work has the LPPL maintenance status "maintained".
% 
% The Current Maintainer of this work is Johannes Braams.
% 
% The list of all files belonging to the Babel system is
% given in the file `manifest.bbl. See also `legal.bbl' for additional
% information.
% 
% The list of derived (unpacked) files belonging to the distribution
% and covered by LPPL is defined by the unpacking scripts (with
% extension .ins) which are part of the distribution.
% \fi
                 Hebrew Package for babel system and LaTeX2e

This new support package for Hebrew language is based on the old LaTeX 2.09
hebrew.sty and is backward compatible with it. A new babel-based language
switching interface is also supported.

Bi-directional support uses TeX--XeT or newer e-TeX engine.

The package is available on-line at http://www.dsg.technion.ac.il/heblatex/
or at ftp://tochna.technion.ac.il/pub/staff/lavva/heblatex/. It consists of:

  1. Hebrew package for babel/LaTeX 2e: heblatex.tar.gz or heblatex.zip.
  2. Hebrew fonts (available also on CTAN or ftp.cc.huji.ac.il):
     hebfonts.tar.gz or hebfonts.zip.
  3. Examples of hebrew documents: hebexmpl.tar.gz or hebexmpl.zip.
  4. This README.html file, available also in plain text format as
     README.txt.

The babel/LaTeX 2e edition of the hebrew package, as well as documentation
(including this README file) was developed and will be supported by Boris
Lavva, lavva@tx.technion.ac.il. Please direct your additions, modifications,
bug fixes and comments to this address.

------------------------------------------------------
Table of contents

     Acknowledgement
     Copyright
     Installation
     Hebrew package usage
     Input code pages
     Font encodings
     Bi-directional sectioning commands
     Table of contents, List of figures, List of tables
     Hebrew calendar
     Document class for preparing Hebrew/English or English/Hebrew thesis
     Compatibility with LaTeX 2.09 style
     Future work

------------------------------------------------------
Acknowledgment

The following people have contributed to Hebrew package in one way or
another, knowingly or unknowingly. In alphabetical order:
Irina Abramovici, Yaniv Bargury, Yael Dubinsky, Sergio Fogel, Dan Haran,
Rama Porrat, Michail Rozman, Alon Ziv.

Johannes Braams is the author of babel - a multilingual support for LaTeX.

Tatiana Samoilov and Vitaly Surazhsky found a number of serious bugs in
preliminary version of Hebrew package.

A number of other people have contributed comments and information. Specific
contributions are acknowledged within the documentation.

I want to thank my wife, Vita, and son, Mishka, for their infinite love and
patience.

If you made a contribution and I haven't mentioned it, don't worry, it was
an accident. I'm sorry. Just tell me and I will add you to the next version.

------------------------------------------------------
Copyright

The copyright similar to other LaTeX 2e packages is added to prevent
inconsistency in version numbers and wide-spread distribution of unsupported
macro files (which was common with the old distributions).

Changes, bug fixes and additions are always welcome, but they should be or
distributed under other name, or incorporated in this package (by mailing
me).

     --------------------------------------------------

     Copyright 1997-1998 Boris Lavva and any individual authors listed
     elsewhere in this file. All rights reserved.

     For further copyright information, and conditions for modification and
     distribution, see any other copyright notices in this file.

     This file is contributed to the Babel system, release 3.6.

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

     For error reports concerning UNCHANGED versions of this file no more
     than one year old, see bugs.txt.

     Please do not request updates from me directly. Primary distribution
     will be through the CTAN archives.

     IMPORTANT COPYRIGHT NOTICE:

     You are NOT ALLOWED to distribute this file alone.

     You are allowed to distribute this file under the condition that it
     is distributed together with all the files listed in manifest.txt.

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

     Permission is granted to customize the declarations in this file to
     serve the needs of your installation, provided that you comply with the
     conditions in the file legal.txt.

     However, NO PERMISSION is granted to distribute a modified version of
     this file under its original name.

     MODIFICATION ADVICE:
     If you want to customize this file, it is best to make a copy of the
     source file(s) from which it was produced. Use a different name for your
     copy(ies) and modify the copy(ies); this will ensure that your modifications
     do not get overwritten when you install a new release of the standard system.

     You can then easily distribute your modifications by distributing the
     modified and renamed copy of the source file, together with a suitable
     .ins file, taking care to observe the conditions in legal.txt; this will
     ensure that other users can safely use your modifications.

------------------------------------------------------
Installation

  1. Full LaTeX 2e distribution should be installed, including TeX--XeT or
     e-TeX. Known such distributions include:
        o teTeX 0.9 for UNIX with e-TeX
          (ftp://ftp.informatik.uni-hannover.de/home/te/private/.0.9/)
        o NTeX for UNIX with TeX--XeT
          (http://darfnix.mathematik.uni-stuttgart.de/pub/tex/ntex/)
        o Web2C for Windows 95 and NT (see at CTAN:systems/win32, for
          example, ftp://ftp.dante.de/tex-archive/systems/win32/)
        o TeX Live CD-ROMs distributed by TeX Users Group (TUG), see details
          at http://www.tug.org.
  2. If e-TeX is installed, check if its format is available in extended
     mode, by running elatex or latex on some .tex file:
     -----------------------------------------------------------------------

     This is e-TeX, Version 3.14159-1.1 (Web2c 7.0)
     entering extended mode
     -----------------------------------------------------------------------

     The second line should be "entering extended mode".
  3. If TeX--XeT is installed, it will use a LaTeX 2e format file, called
     laxet.fmt from the formats directory. This directory is commonly
     located at texmf/web2c or texmf/web2c/ini subdirectories. To produce
     format file, run initexxet program on the following  laxet.ini file:
     -----------------------------------------------------------------------

     % Prevent dumping of LaTeX2e
     \let\xxdump=\dump
     \let\dump=\endinput
     % LaTeX2e format
     \input latex.ltx
     % Read latex2e.add
     \openin1=latex2e.add
     \ifeof1\closein1\message{latex2e.add not found}
     \else\closein1\input latex2e.add
     \fi
     % dump
     \let\dump=\xxdump
     \let\xxdump=\undefined
     \dump
     -----------------------------------------------------------------------

     Put the resulting file laxet.fmt to the formats directory and link (or
     copy) the virtexxet program as laxet.
  4. Download the babel sources from the CTAN sites, directory
     macros/latex/packages/babel. This version of Hebrew package is tested
     with babel version 3.6.
  5. Apply the following changes to the standard babel sources:
        o babel.dtx -- after the line 916 (greek) add:
          \DeclareOption{hebrew}{\input{rlbabel.def}\input{hebrew.ldf}}
        o bbcompat.dtx -- after the line 134 (welsh) add:
          %<+hebrew>\input rlbabel.def\input hebrew.ldf\relax
        o babel.ins -- after the line 346 (bahasa) add:
          \generate{\compatfile{hebrew}}
  6. Download the hebrew package, fonts and examples from the above
     mentioned place.
  7. Open heblatex to the babel sources directory.
  8. Run latex babel.ins and then latex hebrew.ins.
  9. Move all *.cls, *.sty, *.def, *.fd, *.ldf to the babel directory
     searchable by TeX (run MakeTeXls-R or similar program). Usually, babel
     is located at TEXROOT/share/texmf/tex/latex/packages/babel or
     TEXROOT/share/texmf/tex/generic/babel.
 10. Install hebrew fonts from hebfonts as following:
        o Find your public font sources directory, it is usually:
          TEXROOT/share/texmf/fonts/source/public.
        o Unpack hebfonts file into the abovenamed public directory. It will
          create a new directory called hebrew inside public.
        o Find your special.map file - it is usually found at
          TEXROOT/share/texmf/fontname/special.map and add the following
          lines at the end of this file:
          @c Hebrew fonts
          jerus10      public    hebrew
          deads10      public    hebrew
          oldjaf10     public    hebrew
          telav10      public    hebrew
          crml10       public    hebrew
          crmlsl10     public    hebrew
          fr           public    hebrew
          frbx         public    hebrew
          frsl         public    hebrew
          hclassic     public    hebrew
          hcaption     public    hebrew
          redis7       public    hebrew
          redis8       public    hebrew
          redis9       public    hebrew
          redis10      public    hebrew
          redis12      public    hebrew
          redis17      public    hebrew
          redisb10     public    hebrew
          rediss8      public    hebrew
          rediss9      public    hebrew
          rediss10     public    hebrew
          rediss12     public    hebrew
          shold10      public    hebrew
          shscr10      public    hebrew
          shstk10      public    hebrew
        o Run REHASH from texconfig utility or program MakeTeXls-R or newer
          mktexlsr (if available) to build a new ls-R database in
          TEXROOT/share/texmf directory. You can add inserted file names
          manually to ls-R if you cannot find abovenamed programs.
        o Note that only 7-bit (old code) fonts are used by new Hebrew
          package.
 11. You can check if your installation succeed by LaTeXing examples from
     hebexmpl file.

Finally, you can prepare the LaTeX documentation of all components of the
new Hebrew package by running:

     ------------------------------------

     latex hebrew.dtx
     makeindex -s bbind.ist hebrew.idx
     makeindex -s bbglo.ist -o hebrew.gls hebrew.glo
     latex hebrew.dtx
     latex hebrew.dtx

     ------------------------------------

The same procedure can be applied on babel.dtx (or babel.drv) to create the
babel documentation. Files bbind.ist and bbglo.ist are included with babel
installation.

------------------------------------------------------
Hebrew package usage

The usage is simple, for example:

\documentclass[12pt,twoside]{book}
\usepackage[hebrew,english,russian,danish,greek,...]{babel}

LaTeX 2.09 style is also supported (in compatibility mode) to process
existing documents, for example:

\documentstyle[12pt,hebrew_newcode]{article}

Languages can be switched by the following macros:

  1. \sethebrew or \unsethebrew
  2. \selectlanguage{hebrew}, \selectlanguage{english}, etc.
  3. \begin{otherlanguage}{hebrew} ... \end{otherlanguage}, or any other
     language
  4. \R{hebrew text} inside the latin text
  5. \L{latin text} inside the hebrew text

First three commands are equivalent: first one provides switching interface,
compatible with LaTeX 2.09 hebrew style, while second and third ---
babel-based interface.

Last two commands are used for language and direction switching inside
paragraph.

hmbox and embox macros should be used for inserting Hebrew and English text
(respectively) inside a mathematical formula.

------------------------------------------------------
Input code pages

Hebrew package supports the following input code pages:

  1. 7-bit hebrew encoding, also known as old code, defined by Israeli
     Standard 960 (si960)
  2. IBM PC code page also known as pc code (cp862)
  3. WINDOWS code page also known as new code (cp1255)
  4. ISO 8859-8 Hebrew/Latin code page commonly used in UNIX, also known as
     new code (8859-8 also known as new code)

The default input encoding can be set using option defined above in
parentheses with inputenc style (but *before* babel), for example :

\usepackage[cp1255]{inputenc}

Input encoding can be changed also inside the document by the \inputencoding
command, for example:

\inputencoding{cp862}

------------------------------------------------------
Font encodings

Various font encodings can be used, including, of course, Local Hebrew
Encoding (LHE), with the aid of fontenc style (but *before* babel), for
example:

\usepackage[LHE,OT2,LCY,T1]{fontenc}

Many useful font-switching commands are provided in hebfont package which
can be included *after* the babel:

\usepackage{hebfont}

These commands are in format \text<font>{Hebrew text}, for example:
\textoj{Text printed with Old Jaffa font}, \textredis{Text printed with
redis font}.

In addition, for backward compatibility in LaTeX 2.09 documents, the four
old font-switching commands are supported:
{\jm ...}, {\oj ...}, {\ds ...} and {\ta ...} for Jerusalem, Old Jaffa, Dead
Sea and Tel-Aviv fonts respectively.

The following TeX fonts are supported:

   * Jerusalem (used as default font)
   * Dead Sea (used as bold font)
   * Tel-Aviv (used as sans-serif or typewriter font)
   * Old Jaffa (used as italic or slanted font and for emphasize)
   * Hebrew classic normal and slanted (command \textclas)
   * Shalom Old Style (command \textshold)
   * Shalom Script (command \textshscr)
   * Shalom Stick (command \textshstk)
   * Carmel normal and slanted (command \textcrml)
   * Frank Ruehl normal, bold and slanted (command \textfr)
   * Redis normal, bold and slanted (command \textredis)

------------------------------------------------------
Bi-directional sectioning commands

These commands inserts both Hebrew title to the RL table of contents or list
of figures/tables, and English (or other LR language) title to the LR table
of contents or list of figures/tables.

  1. \bpart{hebrew}{english}
  2. \bchapter{hebrew}{english}
  3. \bsection{hebrew}{english}
  4. \bsubsection{hebrew}{english}
  5. \bsubsubsection{hebrew}{english}
  6. \bcaption{hebrew}{english}
  7. \bchapternn{hebrew}{english} - replaces \chapter*
  8. \bsectionnn{hebrew}{english} - replaces \section*

A number of additional bi-directional commands are defined in the
hebtech.cls - thesis document class file, described below.

------------------------------------------------------
Table of contents, List of figures, List of tables

Both Right-to-Left and Left-to-Right versions of the tables (toc, lof and
lot) can be generated simultaneously. The LR files have the default
extensions (.toc, .lof and .lot), while the RL files have reversed
extensions (.cot, .fol and .tol). For example, to include RL tables at the
beginning and LR tables before the end of the document:

     ------------------------------------

     \begin{document}
     \sethebrew
     \tableofcontents % Generates .cot file
     \listoffigures   % Generates .fol file
     \listoftables    % Generates .tol file
     ...
     \unsethebrew
     \tableofcontents % Generates .toc file
     \listoffigures   % Generates .lof file
     \listoftables    % Generates .lot file
     \end{document}

     ------------------------------------

All 6 files are generated simultaneously in two latex passes !

------------------------------------------------------
Hebrew calendar

Original Hebrew calendar style was created by Michail Rozman, and corrected
by Rama Porrat, Michail Rozman and Dan Haran.

This style was adjusted to LaTeX 2e by Boris Lavva, and provided in hebcal
package. It can be included *after* the babel:

\usepackage{hebcal}

The following 2 user-level commands are provided with the package:

\newcount\hd \newcount\hm \newcount\hy

\hd=10 \hm=3 \hy=1992

\HebrewDate{\hd}{\hm}{\hy}

which converts the requested Gregorian date to Hebrew calendar date and
prints it in Hebrew or English (depends on the current language) and:

\HebrewToday or \hebrewtoday

which prints the current Hebrew date (today) .

------------------------------------------------------
Document class for preparing Hebrew/English or English/Hebrew thesis

A useful document class file hebtech for preparing M.Sc. and Ph.D. theses
for the Technion (English/Hebrew and Hebrew/English) is included with this
package too. I believe that it can be adjusted for the needs of other
academic institutions in Israel too. This class automatically includes babel
with hebrew and english option, hebfont and hebcal packages.

The original version for LaTeX 2.09 and old code Hebrew was created in 1994
by Irina Abramovici, at Taub Computer Center, Technion.

How to use this document class?

\documentclass[12pt]{hebtech}

The following parameters should be included in thesis preamble (before
\begin{document}):

  1. Thesis title
     \title{hebrew}{english}
  2. Thesis author
     \author{hebrew}{english}
  3. Department name, e.g. Electrical Engineering Department
     \dept{hebrew}{english}
  4. Domain of research, e.g. Food Processing
     \dom{hebrew}{english}
  5. Main advisor
     \advisori{hebrew}{english}
  6. Second advisor, if exists
     \advisorii{hebrew}{english}
  7. Main sponsor
     \donori{hebrew}{english}
  8. Additional sponsor, if exists
     \donorii{hebrew}{english}
  9. Set thestype counter to:
        o 1 --- for a research thesis
        o 2 --- for a project thesis
        o 3 --- for a final paper

     \setcounter{thestype}{1}
 10. Set grade counter to:
        o 1 --- for master of science
        o 2 --- for master
        o 3 --- for master of technology
        o 4 --- for doctor of science

     \setcounter{grade}{1}
 11. Date is optional, if not included, today's date will be used. The
     Gregorian date entered will be printed and get converted the Jewish
     date.
     \date{28}{2}{1998}
 12. Page style is optional too, if not included, plain will be used.
     \pagestyle{thesis}

In the main document the following additional commands and environments can
be used:

  1. \makecover - creates Hebrew or English cover page, depending on the
     current language.
  2. \maketitle - creates Hebrew or English title page, depending on the
     current language.
  3. \begin{acknowledgment} ... \end{acknowledgment} - builds the
     acknowledgment page and adds inserted customized acknowledgment in
     Hebrew or English, depending on the current language.
  4. \begin{dedication} ... \end{dedication} - builds the dedication page in
     Hebrew or English, depending on the current language.
  5. \tableofcontents, \listoffigures, \listoftables - builds tables
     depending on the current language (all 6 tables can be used
     simultaneously).
  6. \begin{abstract} ... \end{abstract} - builds the abstract pages in
     Hebrew or English, depending on the current language, adds contents
     line to the 2 tables of contents.
  7. \frontmatter, \mainmatter, \backmatter - should be inserted at the
     beginning, before the main part, and at the ending of the thesis to
     change numbering and other style parameters.
  8. \bibliography{...} - now adds "References" line to the 2 tables of
     contents: English and Hebrew.

Some useful bi-directional commands, for figures and tables provided in this
file too:

  1. \bcaptionf{hebrew}{english} - similar to \bcaption but answers to
     thesis formatting requirements at the Technion, used for figures.
  2. \bcaptionff{to RL lof}{to LR lof}{hebrew}{english} - a customized one
     for figures.
  3. \bcaptiont{hebrew}{english} - similar to \bcaption but answers to
     thesis formatting requirements at the Technion, used for tables.
  4. \bcaptiontt{to RL lot}{to LR lot}{hebrew}{english} - a customized one
     for tables.

------------------------------------------------------
Compatibility with LaTeX 2.09 style

Generally, the new package is compatible with LaTeX 2.09 style file
hebrew.sty, i.e. in most cases one can use the new package on old documents
without any errors. Howver, it does not support Plain TeX, please use
heb_macros.tex, or other TeX macro file for Hebrew instead.

A few incompatibilities are described below:

   * The macros with Hebrew names are not provided, for example, macro
     \hadgesh when the command name "hadgesh" is given in Hebrew is not
     supported. The reason is that in new LaTeX 2e it is forbidden to use
     8-bit macros, because all characters 128-255 became to be "active".
     However, the following English-coded equivalents are supported for
     backward compatibility with LaTeX 2.09 style and can be used even in
     the new documents:
       1. \hebday (replaced "hayom").
       2. \hebcopy (for use in letter style)
       3. \hebincl (for use in letter style)
       4. \hebpage (for use in letter style)
       5. \hebto (for use in letter style)
       6. \hadgesh (produces ``poor man's bold'' - heavy printout, it is
          advisable to use real bold fonts, e.g. DeadSea instead)
       7. \piska (can be used only in compatibility mode)
       8. \piskapiska (can be used only in compatibility mode)
       9. \makafgadol (=\textendash)
      10. \makafanak (=\textemdash)
      11. \geresh (=\textquoteright)
      12. \opengeresh (=\textquoteright)
      13. \closegeresh (=\textquoteleft)
      14. \openquote (=\textquotedblright)
      15. \closequote (=\textquotedblleft)
      16. \leftquotation (=\textquotedblright)
      17. \rightquotation (=\textquotedblleft)
      18. \undertext (=\underline, can be used only in compatibility mode)
   * In \documentstyle line the following 3 styles can be used in Hebrew
     documents:
       1. \documentstyle[hebrew_oldcode,...]{...} in old 7-bit documents
          (instead of "hebrew"!).
       2. \documentstyle[hebrew_newcode,...]{...} in 8-bit UNIX or Windows
          documents.
       3. \documentstyle[hebrew_p,...]{...} in 8-bit DOS documents.
   * hebcal style should always be used (instead of older hebcal_p and
     hebcal_newcode).
   * Font names for the included 7-bit fonts were renamed (for the sake of
     multiplatform support)  to lowercase names with no more than 8
     characters as following:
        o jerus10.mf - for Jerusalem (10pt)
        o deads10.mf - for Dead Sea (10pt)
        o telav10.mf - for TelAviv (10pt)
        o oldjaf10.mf - for Old Jaffa (10pt)
        o shold10.mf - for Shalom Old Style (10pt)
        o shscr10.mf - for Shalom Script (10pt)
        o shstk10.mf - for Shalom Stick (10pt)
        o Some other font-related files were renamed too (to lowercase and <
          8 characters):
             + frank_ruehl.mf became frruehl.mf
             + redisfont.mf became redisfnt.mf
             + redisbx10.mf became redisb10.mf
        o All other font names remain unchanged

------------------------------------------------------
Future work

  1. Visual enviroments i.e. tabular, tabbing and array have to be supported
     for hebrew. Now only left-to-right direction of lines is supported.
  2. Update hebrew package for the future babel-3.7 release.
  3. Hebrew points and dots ("nikud") support should be added, so it can be
     used in font-independent way.
     Currently, nikud can be used only on font-dependent way: only shalom
     and classic families of fonts provide nikud, and hebrew point glyphs
     are located in different places.
  4. Machintosh Hebrew/English input code page support should be added.
  5. Type1/TrueType Hebrew fonts should be supported.

------------------------------------------------------
Created by Boris Lavva, lavva@tx.technion.ac.il
Last modified March 1, 1998