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

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

------------------------------------------------------------------------
POLSKI (iso8859-2):
------------------------------------------------------------------------

Dokumentacja niniejsza omawia pokrtce generowanie formatw do tworzenia
plikw DVI oraz PDF, ze wsparciem dla jzyka polskiego i ich uycie 
w rodowisku opartym na Web2c (dystrybucje TeXLive/teTeX/fpTeX) lub MiKTeX.
Od wersji 5.7.3 Web2c oba typy plikw generowane s jednym programem pdfetex.

Poniej pokazano prosty przykad tworzenia pliku z uyciem pakietu PLaTeX.
Pakiet ten 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.

Ponadto w 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/pdftex 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 identycznym podkatalogu katalogu gwnego instalacji. Modyfikacja
language.dat polega na usuniciu w tym pliku znaku komentarza `%' w wierszu
polish plhyph.tex
i ewentualnym zablokowaniu takim znakiem niepodanych deklaracji wzorcw
dzielenia wyrazw. Przygotowanie formatu:

   * standardowe: w teTeX/fpTeX/TeX Live naley uruchomi program texconfig, 
     uaktywni reguy dzielenia wyrazw dla jzyka polskiego - menu Hyphenation
     uruchamia edycj pliku language.dat; po zapisaniu zmian w pliku
     i zakoczeniu edycji, zostanie automatyczne wygenerowany 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; texlinks
     za na niszym poziomie - poleceniu
     pdfetex --ini --progname=latex latex.ini
     (od Web2c wer. 7.5.3 uywamy jednego programu pdfetex).
     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 (przyciskiem Build)
     nowy format latex.fmt, zawierajcy polskie wzorce.
     Format pdflatex.fmt dla programu pdftex tworzony jest analogicznie.

   * 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 wyniku w PDF).
     Formaty te korzystaj z ,,prywatnej'' kopii pliku language.dat
     z zadeklarowanymi od razu polskimi i angloamerykanskimi wzorcami
     przenoszenia wyrazw. Procedura opisana w poprzednim punkcie pozwala
     na wygenerowanie takich formatw za pomoc programu texconfig: menu
     Formats uruchamia edycj pliku 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 nastpujco:
       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; texlinks (lub
          fmtutil --byfmt pdfplatex; texlinks).
     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 pdfplatex.fmt), ktry jest umieszczany w katalogu waciwym dla
     tego rodzaju plikw, oraz tworzony jest program platex lub pdfplatex
     (uruchamia on program pdfetex 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 Web2c, a take MiKTeX pozwalaj na
prawidowe przekodowanie znakw diakrytycznych w pliku TeX-owym na
wewntrzn reprezentacj, stosowan przez programy. W Polsce, niestety,
stosowane s rne ,,standardy'' kodowania diakrytykw w tworzonych przez
uytkownika plikach, zalenie od systemu operacyjnego. Dla potrzeb systemu
TeX uywamy zewntrznych, tekstowych plikw TCX, pozwalajcych ,,obsuy''
rne spotykane ,,standardy''. Dziki temu przekodowanie dziaa te w drug
stron, kiedy TeX wywietla komunikaty i zapisuje pliki .log, a take pliki
ze spisem treci, skorowidzem itp.

Uruchomienie polecenia:
latex --translate-file=TCXFILE myfile.tex
oznacza uruchomienia TeX-a z formatem latex.fmt i z odpowiedni tablic
przekodowa (ich lista znajduje si poniej). W identyczny sposb
uruchamiamy polecenie platex.

Przekodowanie (plik TCX) moe by deklarowane bezporednio w pliku
TeX-owym. Poczwszy od wersji Web2c 7.4, wymaga to podania w wierszu
polece opcji --parse lub wczenia jej na stae, co wymaga zmiany
w gwnym pliku konfiguracyjnym texmf.cnf:
parse_first_line = t
(t -- od `true', zamiast domylnego przypisania f -- od `false').

Przykadowo, jeli pierwszy wiersz pliku zawiera komentarz strukturalny
postaci
%&platex --translate-file=il2-pl
to plik moe by przetworzony za pomoc polecenia (obecnie) 
pdfetex plik.tex; zostanie wtedy wczytany format platex.fmt oraz tablica 
il2-pl.tcx przekodowania z ukadu iso8859-2 (latin2) do ukadu fontw PL 
(wewntrznego dla programu TeX; w LaTeX-u ma on kryptonim OT4).

Tym samym zbdne s deklaracje w preambule pliku LaTeX-owego:
\usepackage[latin2]{inputenc}
\usepackage[OT4]{fontenc}

W dystrybucjach 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
 cp1250pl.tcx  Windows cp1250 do PL
 cp852-pl.tcx  IBM cp852 do PL
 macce-pl.tcx  Apple MacCE 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 (odpowiada mu ukad OT4, wic zbdna
jest deklaracja \usepackage[OT4]{fontenc}). Jeli korzystamy 
z fontw EC nasza preambua powinna zawiera dodatkowy wiersz:
\usepackage[T1]{fontenc}

III. Polskie fonty PostScriptowe

Aktualne dystrybucje zawieraj fonty serii PL (spolonizowane standardowe
dla TeX-a fonty CM) 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 powinny znale si w podkatalogu texmf/fonts/type1/public/pl/
naszej instalacji, pliki map fontowych (.map) w katalogu 
texmf/fonts/map/dvips/pl/ za wektory kodowa 
(.enc) -- w katalogu texmf/fonts/enc/dvips/pl/

W dystrybucjach opartych na Web2c zautomatyzowano, poprzez uycie programu
updmap, proces tworzenia map fontowych dla programw dvips, pdftex
i dvipdfm. Poniej omwiono wic jedynie czego ten proces dotyczy.

Sterownik dvips (zamieniajcy wynik pracy TeX-a, plik DVI, do formatu
PostScript) wymaga aby deklaracje map fontowych (dla fontw PL konkretnie
zawarto texmf/fonts/map/dvips/pl/pl.map) byy doczone do pliku
texmf/fonts/map/dvips/updmap/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/fonts/map/pdftex/updmap/pdftex.map --
powinien on take zawiera deklaracje map fontowych dla fontw PL.

W dystrybucjach wszystkie aktualnie dostpne polskie fonty Type1 s gotowe
do uycia zarwno przez program dvips, jak i pdftex.

Bardziej szczegowe omwienie instalacji fontw Type1 zawarte jest
w artykule Instalowanie fontw Type1/True Type 
(na stronie http://www.gust.org.pl/fonty/).

------------------------------------------------------------------------
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, 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 we use latex.fmt with Polish patterns we can compile our file
    with the command `latex --translate-file=TCXFILE myfile.tex'.
    If the parse_fist_line is enabled (`--parse' option in the command line
    or, permanently, parse_fist_line=t in texmf.cnf)
    and the *first* line of TeX's file contains a structured comment
    of the form
        %&platex --translate-file=il2-pl
    it suffices to run `pdfetex file.tex' with platex.fmt and il2-pl.tcx
    translation table (iso8859-2 to internal PL reencoding, which in fact
    is recognized as LaTeX's OT4).
    You can use TCX tables instead of LaTeX's
        \usepackage[latin2]{inputenc}
	\usepackage[OT4]{fontenc}
    We can make a `platex' command available making on Unix a soft link
    to pdfetex, or (Windows) making a copy tex.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
           cp1250pl.tcx   Windows cp1250 <--> PL encoding
           cp852-pl.tcx   IBM cp852 <--> PL encoding
	   macce-pl.tcx   Apple MacCE <--> PL
           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 files should go to .../fonts/map/dvips/pl/ directory;
     font enc files should go to .../fonts/enc/dvips/pl/ directory.

     The preparation of map files are now automatized by running updmap
     program. In short:
     
     Dvips can be prepared for using PL fonts in Type 1 format in two ways:
     * the contents of texmf/fonts/map/dvips/pl/pl.map should be included
       into the standard texmf/fonts/map/dvips/updmap/psfonts.map.
     * in texmf/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 contents of 
     texmf/fonts/map/pdftex/updmap/pdftex.map file can be updated with
     the contents of pl.map.

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