%% Staszek Wawrykiewicz (StaW@gust.org.pl), January 2001.  Public domain.
%% Web2c (teTeX, fpTeX, TeX Live) and MiKTeX 2.0 revision
PLaTeX and pdfPLaTeX

Dokumentacja po polsku i po angielsku (nizej).
The documentation in Polish and in English (below).

------------------------------------------------------------------------
POLSKI (iso8859-2):
------------------------------------------------------------------------
Pakiet PLaTeX dostarcza narzdzi potrzebnych do skadu dokumentw w jzyku
polskim LaTeXem 2e.
Autorzy pakietu: Mariusz Olko i Marcin Woliski.
Wicej informacji na temat samego pakietu -- patrz plik czytaj.txt
dystrybucji PLaTeX.

Dokumentacja niniejsza omawia pokrtce tworzenie formatw dla programw tex
i pdftex (wersji TeX-a tworzcej od razu pliki PDF) ze wsparciem dla jz.
polskiego i ich uycie w rodowisku opartym na web2c (dystrybucje TeX
Live/teTeX/fpTeX) lub MiKTeX.

Poniej (w tym pliku) pokazano prosty przykad tworzenia pliku z uyciem
pakietu platex. Ponadto w najnowszych dystrybucjach doczono przykadowy
plik doc/latex/platex/tstlatex.tex. sucy do przetestowania poprawnego 
dziaania formatu
LaTeX/PLaTeX. Pocztkujcym uytkownikom zaleca si zapoznanie z zawartoci
tego pliku. Plik ten dostpny jest take na serwerze GUST. Techniczne
szczegy dotyczce uycia pakietu polski.sty (gwny element pakietu
platex) dostpne s po dwukrotnym uruchomieniu:
platex polski.dtx
platex polski.dtx
i wywietleniu wynikowego polski.dvi.

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

I. Przygotowanie formatu LaTeX2e do obsugi jzyka polskiego

Format w systemie TeX to wstpnie prekompilowany (aby przyspieszy jego
analiz przez program tex/pdftex) zestaw makrodefinicji oraz regu
przenoszenia wyrazw dla wybranego zestawu jzykw. Plik formatu z reguy
posiada rozszerzenie .fmt. Tworzenie formatu to, w skrcie, uruchomienie
programu tex z opcj --ini i wczytanie odpowiedniego pliku inicjujcego (dla
LateX jest to plik latex.ltx). W LaTeX 2e zestaw regu przenoszenia wyrazw
jest zwyczajowo deklarowany w pliku o nazwie language.dat. Plik ten znajduje
si zwykle w podkatalogu tex/generic/config/language.dat lokalnej
konfiguracji systemu TeX bd w gwnym katalogu instalacji. Modyfikacja
language.dat polega na usuniciu w tym pliku znaku `%' przed plhyph.tex
i ewentualnym zablokowaniu takim znakiem niepodanych deklaracji wzorcw
dzielenia wyrazw. Przygotowanie formatu:

   * standardowe: w teTeX naley uruchomi program texconfig, uaktywni
     reguy dzielenia wyrazw dla jz. polskiego (menu Hyphenation uruchamia
     edycj pliku language.dat); wygenerowany zostanie format latex.fmt
     zawierajcy wybrane wzorce dzielenia oraz mechanizm Babel przeczania
     jzykw; texconfig tworzy ponadto dowizanie (lub program) latex.
     Dla dociekliwych: powysze odpowiada uruchomieniu z linii polece:
     fmtutil --byfmt latex
     za na niszym poziomie -- poleceniu
     tex --ini --progname=latex latex.ini
     W instalacji MiKTeX (od wersji 2.0) naley uruchomi menu MiKTeX
     Options, zaznaczy w podmenu Languages: polish reguy przenoszenia
     wyrazw, po czym w menu TeX Formats wygenerowa nowy format latex.fmt,
     zawierajcy polskie wzorce.
   * niestandardowe, ktre tworzy ,,czysty'' format LaTeX2e zawierajcy
     jedynie wybrane wzorce dzielenia wyrazw, bez zbdnych mechanizmw
     Babel. Jest to metoda preferowana przez wielu polskich uytkownikow.
     ;-) Dlaczego PLaTeX a nie Babel? O tym poniej. Dla odrnienia
     przyjto nazywa taki format platex (lub pdfplatex dla pdfTeX). Formaty
     te korzystaj z ,,prywatnej'' kopii pliku language.dat
     z zadeklarowanymi od razu polskimi i angloamerykaskimi wzorcami
     przenoszenia wyrazw. Procedura opisana w poprzednim punkcie pozwala na
     wygenerowanie takich formatu za pomoc programu texconfig: menu Formats
     uruchamia edycj pliku texmf/web2c/fmtutil.cnf, naley tu odblokowa
     wiersz dotyczcy formatu platex lub pdfplatex (usun znak # przed
     deklaracj interesujcego nas formatu) i, po zapisaniu pliku, powrci
     do menu nadrzdnego; ,,w tle'' zostanie wykonany program fmtutil;
     utworzone zostanie ponadto dowizanie platex (pdfplatex).
     W wypadku gdy nie mamy (jeszcze) programu texconfig (fpTeX dla Windows)
     procedura generowania formatu platex (lub pdfplatex) da si przedstawi
     w kilku krokach:
       1. naley odszuka plik texmf/web2c/fmtutil.cnf (edytujemy kopi tego
          pliku znajdujc si w lokalnym drzewie katalogw TeX-owych
          uytkownika lub w drzewie przeznaczonym na lokalne konfiguracje;
          pooenie waciwego pliku pokae uruchomienie polecenia 
          kpsewhich fmtutil.cnf);
       2. w pliku fmtutil.cnf naley odblokowa wiersz dotyczcy formatu
          platex lub pdfplatex (usun znak #);
       3. uruchomi polecenie: fmtutil --byfmt platex --dolinks (lub fmtutil
          --byfmt pdfplatex --dolinks).
     Dla MiKTeX (od wersji 2.0) naley uruchomi menu MiKTeX Options,
     w podmenu TeX Formats zaznaczy format PLaTeX (lub pdfPLaTeX)
     i utworzy (przyciskiem Build) potrzebne formaty.

     W omawianych wyej przypadkach tworzony jest plik formatu platex.fmt
     (lub pdplatex.fmt), ktry jest kopiowany do waciwego katalogu,
     zawierajcego pliki formatw oraz tworzone jest polecenie platex lub
     pdfplatex (uruchamia on program tex lub pdftex z odpowiednim formatem).

Dlaczego PLaTeX a nie Babel?

(Fragment ten jest cytatem z listu nadesanego na list dyskusyjn GUST
przez Marcina Woliskiego).
W porwnaniu do pakietu Babel, PLaTeX ma kilka mniej lub bardziej istotnych
zalet:

   * PLaTeX udostpnia tradycyjne definicje nazw polskich funkcji
     trygonometrycznych \tg, \ctg, \arc i polskich znakw mniejsze-rwne
     oraz wiksze-rwne.
   * PLaTeX umie poprawne przenosi wyrazy zoone (tj. takie jak np.
     biao-czerwony) udostpniajc do tego celu polecenie \dywiz.
   * PLaTeX wstawia prawidowe odstpy na kocu zdania.
   * Babel nie wspiera do koca fontw w ukadzie OT4 (fontw PL), co
     powoduje, e polskie znaki diakrytyczne w wyrazach wstawianych
     automatycznie przez LaTeX (dokadnie ,,'' w sowie cz oraz ,,''
     w sowie ,,zacznik'') sklejane z dwch znakw. Jest to drobny, ale
     cigle nie usunity bd. (Mona go poprawi samodzielnie dokonujc
     niewielkiej modyfikacji pliku polish.sty z dystrybucji pakietu Babel.)
     Obwiedniowe fonty OT4 s niezastpione przy tworzeniu plikw w formacie
     PDF.

Podsumowujc: jeeli nie potrzebujemy rodowiska wielojzycznego to duo
mniejsza objto pakietu PLaTeX oznacza take mniejsz liczb bdw
i potencjalnych kolizji z innymi czciami LaTeXa.
[achiwum GUST-L, list z 06/06/1997]
------------------------------------------------------------------------

II. Uycie

Aktualne implementacje, oparte na webc 7.3, pozwalaj wreszcie na prawidowe
przekodowanie znakw diakrytycznych w pliku TeX-owym na wewntrzn
reprezentacj. Przekodowanie dziaa te w drug stron, kiedy TeX wywietla
komunikaty i zapisuje pliki .log, .toc, .idx itp. Do tego celu uywa si
zewntrznych, tekstowych plikw TCX. Co wicej, przekodowanie (plik TCX)
moe by deklarowane bezporednio w pliku TeX-owym. Jeli pierwszy wiersz
pliku zawiera komentarz strukturalny postaci
  %&platex --translate-file=il2-pl
to plik moe by przetworzony za pomoc polecenia tex plik.tex; zostanie
wtedy wczytany format platex.fmt oraz tablica il2-pl.tcx przekodowania
z iso8859-2 (latin2) do ukadu fontw PL (wewntrznego dla programu TeX).
Tym samym zbdna jest deklaracja w preambule pliku LaTeX-owego:
  \usepackage[latin2]{inputenc}
Moemy uy take polecenia:
  platex --translate-file=TCXFILE myfile.tex
lub wrcz
  platex myfile.tex
gdy plik myfile.tex zawiera w pierwszym wierszu:
  %& --translate-file=TCXFILE
W tej dystrybucji dostarczono szereg plikow TCX. Mona je znale w katalogu
texmf/web2c/:
 amiga-pl.tcx AmigaPL do PL
 il2-pl.tcx   iso8859-2 (latin2) do PL
 cp1250-pl.tcxWindows cp1250 do PL
 cp852-pl.tcx IBM cp852 do PL
 maz-pl.tcx   Mazovia do PL

A oto przykad pliku LaTeX-owego:

        %& --translate-file=cp1250pl
        \documentclass[a4paper]{article}
        \usepackage{polski}
        \begin{document}
          Polskie literki piszemy w standardzie Windows cp1250: .....
        \end{document}

Jak wida, nasz plik ma krtk preambu -- pakiet polski korzysta domylnie
z zainstalowanych fontw PL. Jeli korzystamy z fontw EC nasza preambua
powinna zawiera dodatkowy wiersz:
\usepackage[T1]{fontenc}

III. Polskie fonty PostScriptowe

Aktualne dystrybucje zawieraj fonty serii PL w wersji Type 1
(postscriptowe). Mona je take znale w najbliszym wle CTAN lub jego
kopii, np.:
ftp://sunsite.icm.edu.pl/CTAN/fonts/psfonts/polish/plpsfont/.
Pliki .pfb znajduj si w podkatalogu texmf/fonts/type1/public/pl/ naszej
instalacji.

Sterownik dvips (zamieniajcy wynik pracy TeX-a, plik DVI, do formatu
PostScript) wymaga aby deklaracje map fontowych (dla fontw PL konkretnie
zawarto texmf/dvips/pl/pl.map) byy doczone do pliku
texmf/dvips/config/psfonts.map. Mapy fontowe mona alternatywnie doczy
w pliku texmf/dvips/config/config.ps (lub jego lokalnej kopii), dopisujc
wiersz:
  p +pl.map
po deklaracji gwnej mapy fontowej: p psfonts.map.

Aby fonty Type 1 byy uyte przez program pdfTeX, naley sprawdzi jakie
mapy fontowe s deklarowane w pliku texmf/pdftex/config/psfonts.map --
powinien on take zawiera deklaracje map fontowych dla fontw PL.

Bardziej szczegowe omwienie instalacji fontw Type1 zawarte jest
w artykule Instalowanie fontw Type1/True Type:
http://www.gust.org.pl/FONTY/fonthint.html.

------------------------------------------------------------------------
ENGLISH:
------------------------------------------------------------------------

PLaTeX provides tools to typeset documents in Polish using LaTeX2e.
Authors: Mariusz Olko & Marcin Woli\'nski.
This document describes shortly creation of latex.fmt (or platex.fmt)
for Polish and usage in MiKTeX environement.
See readme.txt for more informations about the PLaTeX package.

I. Preparing LaTeX2e format for Polish
   There are two methods:
   1. `standard': just activate polish hyphenation patterns in the file
       language.dat (menu `Hyphenation' in teTeX's texconfig or `Languages' 
       in `MiKTeX Options') and recompile latex.ltx (for MiKTeX 2.x from the
       menu `TeX Formats'); as a result, latex.fmt including Babel machinery
       will be generated.
   2. `non standard': it produces a clean and generic LaTeX2e without Babel
       deadwood, containing only patterns for Polish and US English; this
       method is prefered by many users in Poland. ;-)
       The distribution allows to generate such a format: platex.fmt
       (or pdfplatex.fmt) from teTeX's texconfig `Formats' menu (for MiKTeX
       `TeX Formats' menu).

II. Usage: the current implementations based on web2c 7.3, and MiKTeX 
    allow (hopefully) proper reencoding of input national characters 
    into internal TeX's, and back again, for all messages, .log, .toc, 
    .idx files written by TeX, etc. External readable TCX translation 
    files are used and they can be specified explicitly in the TeX file 
    or in the command line.
    If the _first_ line of TeX's file contains a structured comment
    of the form
        %&platex --translate-file=cp1250pl
    it suffices to run `tex file.tex' with platex.fmt and cp1250pl.tcx
    translation table (Windows cp1250 to internal PL reencoding).
    You can use TCX tables instead of LaTeX's
        \usepackage[cp1250]{inputenc}
    If we use latex.fmt with Polish patterns we can compile our file
    with the command `latex -tcx=TCXFILE myfile.tex'.
    We can make a `platex' command available copying latex.exe into
    platex.exe in the directory containing binaries.
    Thus `platex -translate-file=TCXFILE myfile.tex' can be used as well.
    Several TCX files are provided; they can be found in the ...\web2c\
    directory:
           amiga-pl.tcx   AmigaPL <--> PL encoding
           il2-pl.tcx     iso8859-2 (latin2) <--> PL encoding
           cp1250-pl.tcx  Windows cp1250 <--> PL encoding
           cp852-pl.tcx   IBM cp852 <--> PL encoding
           maz-pl.tcx     Mazovia <--> PL encoding

III. Polish PostScript fonts in Type 1 format
     The installation can already contain Type 1 PL fonts;
     they can be also downloaded from the nearest CTAN node or its mirror:
         CTAN//fonts/psfonts/polish/plpsfont/
     or copied from the CD TeX Live.
     .pfb files should reside in the directory: .../fonts/type1/public/pl/ ;
     font map and encoding files should go to .../dvips/pl/ directory.

     Dvips can be prepared for using PL fonts in Type 1 format in two ways:
     * the contents of .../dvips/pl/pl.map should be included
       into the standard .../dvips/config/psfonts.map.
     * in .../dvips/config/config.ps the additional map file can be declared
       after standard `p psfonts.map' line:
         p +pl.map

     In order to use Type 1 fonts with pdfTeX, the line
         map +pl.map
     can be added to the contents of .../pdftex/config/pdftex.cfg, or
     the contents of pdftex/config/psfonts.map file can be updated with
     the contents of pl.map.

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