%% Staszek Wawrykiewicz (StaW@gust.org.pl), January 2003.  Public domain.
%% Web2c (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 pokrótce tworzenie formatów dla programów tex
i pdftex (wersji TeX-a tworzącej od razu pliki PDF) ze wsparciem dla języka
polskiego i ich użycie w środowisku opartym na web2c (dystrybucje TeX
Live/teTeX/fpTeX) lub MiKTeX.

Poniżej pokazano prosty przykład tworzenia pliku z użyciem pakietu PLaTeX.
Pakiet ten dostarcza narzędzi potrzebnych do składu dokumentów w języku
polskim LaTeXem 2e.
Autorzy pakietu: Mariusz Olko i Marcin Woliński.
Więcej informacji na temat samego pakietu -- patrz plik czytaj.txt
dystrybucji PLaTeX.

Ponadto w dystrybucjach dołączono przykładowy plik
doc/latex/platex/tstlatex.tex. służący do przetestowania poprawnego
działania formatu LaTeX/PLaTeX. Początkującym użytkownikom zaleca się
zapoznanie z zawartością tego pliku. Plik ten dostępny jest także na
serwerze GUST. Techniczne szczegóły dotyczące użycia pakietu polski.sty
(główny element pakietu platex) dostępne są po dwukrotnym uruchomieniu:
platex polski.dtx
platex polski.dtx
i wyświetleniu wynikowego polski.dvi.

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

I. Przygotowanie formatu LaTeX2e do obsługi języka polskiego

Format w systemie TeX to wstępnie prekompilowany (aby przyspieszyć jego
analizę przez program tex/pdftex) zestaw makrodefinicji oraz reguł
przenoszenia wyrazów dla wybranego zestawu języków. Plik formatu z reguły
posiada rozszerzenie .fmt. Tworzenie formatu to, w skrócie, uruchomienie
programu tex/pdftex z opcją --ini i wczytanie odpowiedniego pliku
inicjującego (dla LateX jest to plik latex.ltx). W LaTeX 2e zestaw reguł
przenoszenia wyrazów 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 bądź
w identycznym podkatalogu katalogu głównego instalacji. Modyfikacja
language.dat polega na usunięciu w tym pliku znaku komentarza `%' w wierszu
polish plhyph.tex
i ewentualnym zablokowaniu takim znakiem niepożądanych deklaracji wzorców
dzielenia wyrazów. Przygotowanie formatu:

   * standardowe: w teTeX należy uruchomić program texconfig, uaktywnić
     reguły dzielenia wyrazów dla języka polskiego (menu Hyphenation
     uruchamia edycję pliku language.dat; po zapisaniu zmian w pliku
     i zakończeniu edycji, zostanie automatyczne wygenerowany format
     latex.fmt zawierający wybrane wzorce dzielenia oraz mechanizm Babel
     przełączania języków; texconfig tworzy ponadto dowiązanie (lub
     program) latex.
     Dla dociekliwych: powyższe odpowiada uruchomieniu z linii poleceń:
     fmtutil --byfmt latex
     zaś na niższym poziomie -- poleceniu
     tex --ini --progname=latex latex.ini
     W instalacji MiKTeX (od wersji 2.0) należy uruchomić menu MiKTeX
     Options, zaznaczyć w podmenu Languages: polish reguły przenoszenia
     wyrazów, po czym w menu TeX Formats wygenerować (przyciskiem Build)
     nowy format latex.fmt, zawierający polskie wzorce.
     Format pdflatex.fmt dla programu pdftex tworzony jest analogicznie.

   * niestandardowe, które tworzy ,,czysty'' format LaTeX2e zawierający
     jedynie wybrane wzorce dzielenia wyrazów, bez zbędnych mechanizmów
     Babel. Jest to metoda preferowana przez wielu polskich użytkownikow.
     ;-) Dlaczego PLaTeX a nie Babel? O tym poniżej. Dla odróżnienia
     przyjęto nazywać taki format platex (lub pdfplatex dla pdfTeX).
     Formaty te korzystają z ,,prywatnej'' kopii pliku language.dat
     z zadeklarowanymi od razu polskimi i angloamerykanskimi wzorcami
     przenoszenia wyrazów. Procedura opisana w poprzednim punkcie pozwala
     na wygenerowanie takich formatów za pomocą programu texconfig: menu
     Formats uruchamia edycję pliku fmtutil.cnf, należy tu odblokować
     wiersz dotyczący formatu platex lub pdfplatex (usunąć znak # przed
     deklaracją interesującego nas formatu) i , po zapisaniu pliku,
     powrócić do menu nadrzędnego; ,,w tle'' zostanie wykonany program
     fmtutil; utworzone zostanie ponadto dowiązanie platex (pdfplatex).
     W wypadku gdy nie mamy (jeszcze) programu texconfig (fpTeX dla
     Windows) procedura generowania formatu platex (lub pdfplatex) da się
     przedstawić następująco:
       1. należy odszukać plik texmf/web2c/fmtutil.cnf (edytujemy kopię
          tego pliku znajdującą sią w lokalnym drzewie katalogów TeX-owych
          użytkownika lub w drzewie przeznaczonym na lokalne konfiguracje;
          położenie właściwego pliku pokaże uruchomienie polecenia
          kpsewhich fmtutil.cnf);
       2. w pliku fmtutil.cnf należy odblokować wiersz dotyczący formatu
          platex lub pdfplatex (usunąć znak #);
       3. uruchomić polecenie: fmtutil --byfmt platex --dolinks (lub
          fmtutil --byfmt pdfplatex --dolinks).
     Dla MiKTeX (od wersji 2.0) należy uruchomić menu MiKTeX Options,
     w podmenu TeX Formats zaznaczyć format PLaTeX (lub pdfPLaTeX)
     i utworzyć (przyciskiem Build) potrzebne formaty.

     W omawianych wyżej przypadkach tworzony jest plik formatu platex.fmt
     (lub pdfplatex.fmt), który jest umieszczany w katalogu właściwym dla
     tego rodzaju plików, oraz tworzony jest program platex lub pdfplatex
     (uruchamia on program tex lub pdftex z odpowiednim formatem).

Dlaczego PLaTeX a nie Babel?

(Fragment ten jest cytatem z listu nadesłanego na listę dyskusyjną GUST
przez Marcina Wolińskiego).
W porównaniu do pakietu Babel, PLaTeX ma kilka mniej lub bardziej istotnych
zalet:

   * PLaTeX udostępnia tradycyjne definicje nazw polskich funkcji
     trygonometrycznych \tg, \ctg, \arc i polskich znaków mniejsze-równe
     oraz większe-równe.
   * PLaTeX umie poprawne przenosić wyrazy złożone (tj. takie jak np.
     biało-czerwony) udostępniając do tego celu polecenie \dywiz.
   * PLaTeX wstawia prawidłowe odstępy na końcu zdania.
   * Babel nie wspiera do końca fontów w układzie OT4 (fontów PL), co
     powoduje, że polskie znaki diakrytyczne w wyrazach wstawianych
     automatycznie przez LaTeX (dokładnie ,,ę'' w słowie część oraz ,,ą''
     w słowie ,,załącznik'') sklejane z dwóch znaków. Jest to drobny, ale
     ciągle nie usunięty błąd. (Można go poprawić samodzielnie dokonując
     niewielkiej modyfikacji pliku polish.sty z dystrybucji pakietu Babel.)
     Obwiedniowe fonty OT4 są niezastąpione przy tworzeniu plików
     w formacie PDF.

Podsumowując: jeżeli nie potrzebujemy środowiska wielojęzycznego to dużo
mniejsza objętość pakietu PLaTeX oznacza także mniejszą liczbę błędów
i potencjalnych kolizji z innymi częściami LaTeXa.
[achiwum GUST-L, list z 06/06/1997]
---------------------------------------------------------------------------

II. Użycie

Aktualne implementacje, oparte na Web2c, a także MiKTeX pozwalają na
prawidłowe przekodowanie znaków diakrytycznych w pliku TeX-owym na
wewnętrzną reprezentację, stosowaną przez programy. W Polsce, niestety,
stosowane są różne ,,standardy'' kodowania diakrytyków w tworzonych przez
użytkownika plikach, zależnie od systemu operacyjnego. Dla potrzeb systemu
TeX używamy zewnętrznych, tekstowych plików TCX, pozwalających ,,obsłużyć''
różne spotykane ,,standardy''. Dzięki temu przekodowanie działa też w drugą
stronę, kiedy TeX wyświetla komunikaty i zapisuje pliki .log, a także pliki
ze spisem treści, 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ę poniżej). W identyczny sposób
uruchamiamy polecenie platex.

Przekodowanie (plik TCX) może być deklarowane bezpośrednio w pliku
TeX-owym. Począwszy od wersji Web2c 7.4, wymaga to podania w wierszu
poleceń opcji --parse lub włączenia jej na stałe, co wymaga zmiany
w głównym pliku konfiguracyjnym texmf.cnf:
parse_first_line = t
(t -- od `true', zamiast domyślnego przypisania f -- od `false').

Przykładowo, jeśli pierwszy wiersz pliku zawiera komentarz strukturalny
postaci
%&platex --translate-file=il2-pl
to plik może być przetworzony za pomocą polecenia tex plik.tex; zostanie
wtedy wczytany format platex.fmt oraz tablica il2-pl.tcx przekodowania
z układu iso8859-2 (latin2) do układu fontów PL (wewnętrznego dla programu
TeX; w LaTeX-u ma on kryptonim OT4).

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

W dystrybucjach dostarczono szereg plikow TCX. Można 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 przykład 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 krótką preambułę -- pakiet polski korzysta
domyślnie z zainstalowanych fontów PL (odpowiada mu układ OT4, więc zbędna
jest deklaracja \usepackage[OT4]{fontenc}). Jeśli korzystamy 
z fontów EC nasza preambuła 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). Można je także znaleźć
w najbliższym węźle 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, zaś pliki map fontowych (.map) oraz wektory kodowań
(.enc) -- w katalogu texmf/dvips/pl/

W dystrybucjach opartych na Web2c zautomatyzowano, poprzez użycie programu
updmap, proces tworzenia map fontowych dla programów dvips, pdftex
i dvipdfm. Poniżej omówiono więc jedynie czego ten proces dotyczy.

Sterownik dvips (zamieniający wynik pracy TeX-a, plik DVI, do formatu
PostScript) wymaga aby deklaracje map fontowych (dla fontów PL konkretnie
zawartość texmf/dvips/pl/pl.map) były dołączone do pliku
texmf/dvips/config/psfonts.map. Mapy fontowe można alternatywnie dołączyć
w pliku texmf/dvips/config/config.ps (lub jego lokalnej kopii), dopisując
wiersz:
p +pl.map
po deklaracji głównej mapy fontowej: p psfonts.map.

Aby fonty Type 1 były użyte przez program pdfTeX, należy sprawdzić jakie
mapy fontowe są deklarowane w pliku texmf/dvips/config/pdftex.map --
powinien on także zawierać deklaracje map fontowych dla fontów PL.

W dystrybucjach wszystkie aktualnie dostępne polskie fonty Type1 są gotowe
do użycia zarówno przez program dvips, jak i pdftex.

Bardziej szczegółowe omówienie instalacji fontów Type1 zawarte jest
w artykule Instalowanie fontów Type1/True Type.

------------------------------------------------------------------------
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 `tex 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 tex, 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 and encoding files should go to .../dvips/pl/ directory.

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

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