%% Staszek Wawrykiewicz (StaW@gust.org.pl), January 2003.  Public domain.
%% Web2c7.4x (teTeX, fpTeX, TeX Live) and MiKTeX 2.x revision
MeX and pdfMeX

Dokumentacja po polsku i po angielsku (niżej).
The documentation in Polish and in English (below).

------------------------------------------------------------------------
POLSKI (iso8859-2):
------------------------------------------------------------------------
MeX jest adaptacją formatu Plain TeX do składu w języku polskim
z uwzględnieniem polskich zwyczajów drukarskich.
Autorzy: Bogusław Jackowski i Marek Ryćko.
Dokumentacja poniższa omawia pokrótce tworzenie formatu mex.fmt (lub
pdfmex.fmt, dla programu pdfTeX -- wersji TeX-a tworzącej od razu pliki PDF)
i jego użycie w instalacji zgodnej z Web2c (dystrybucje teTeX, fpTeX, TeX
Live) a także MiKTeX. Szczegółowe informacje nt. pakietu MeX zawarto w pliku
mexinfo.pol.

W dystrybucji dołączono ponadto prosty plik przykładowy
doc/polish/mex/tstmex.tex, służący do przetestowania poprawnego działania
formatu MeX. Początkującym użytkownikom zaleca się zapoznanie z zawartością
tego pliku. Plik ten dostępny jest także na serwerze GUST.
------------------------------------------------------------------------

I. Przygotowanie formatu MeX/pdfMeX (polskiej implementacji formatu Plain)

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.

Przygotowanie formatu MeX (lub pdfMeX dla programu pdfTeX, tworzącego pliki
PDF) polega w skrócie na uruchomieniu:

tex --ini mex.ini

(dla pdfTeX: pdftex --ini pdfmex.ini). Podczas przetwarzania wczytywane są
pliki makr formatu MeX, a także plain.tex oraz wzorce przenoszenia wyrazów
dla języka polskiego i angloamerykańskiego.

Ponieważ wygenerowany plik powinien znaleźć się w odpowiednim miejscu
struktury katalogów, a także powinien zostać ,,zarejestrowany''
w instalacji, współczesne dystrybucje ułatwiają proces generowania.

   * W dystrybucjach opartych na Web2c (fpTeX, teTeX, TeX Live) formaty
     generowane są przy pomocy programu fmtutil (fmtutil --help wyświetla
     dostępne opcje) zaś deklaracje formatów znajdują się w pliku
     texmf/web2c/fmtutil.cnf (gdy posiadamy drzewo katalogów zawierające
     lokalne pliki konfiguracyjne instalacji systemu TeX, program fmtutil
     korzysta z lokalnej kopii fmtutil.cnf; dokładne położenie pliku 
     wyświetli uruchomienie polecenia: kpsewhich fmtutil.cnf).

     W systemach Unix/Linux cały proces generowania formatu dostępny jest 
     z menu Formats programu texconfig, które pozwala modyfikować plik 
     fmtutil.cnf, co polega na usunięciu znaku # przed deklacją wybranego 
     formatu bądź zablokowaniu takim znakiem formatów niepożądanych. 
     Po zapisaniu zmian w pliku i zakończeniu edycji, format zostanie 
     automatycznie wygenerowany.
     W systemach Windows należy samodzielnie zmodyfikować plik fmtutil.cnf, 
     po czym uruchomić polecenie fmtutil --byfmt=mex 
     (lub fmtutil --byfmt=pdfmex).

   * W MiKTeX (od wersji 2.0) należy uruchomić w menu MiKTeX Options podmenu
     TeX Formats, zaznaczyć format MeX (pdfMeX) i utworzyć (przyciskiem
     Build) potrzebny plik formatu.

W obu omawianych przypadkach tworzony jest plik formatu mex.fmt (lub
pdfmex.fmt), który jest umieszczany w katalogu właściwym dla tego rodzaju
plików, oraz tworzony jest program mex lub pdfmex (uruchamia on
program tex z formatem mex bądź program pdftex z formatem pdfmex).

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

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:

mex --translate-file=TCXFILE plik.tex

oznacza uruchomienia TeX-a z formatem mex.fmt i z odpowiednią tablicą
przekodowań (ich lista znajduje się poniżej). Polecenie `mex' tworzone 
jest zwykle jako dowiązanie do programu tex w katalogu zawierającym binaria.

Przekodowanie (plik TCX) może być także 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

%&mex --translate-file=il2-pl

to plik może być przetworzony za pomocą polecenia tex plik.tex; zostanie
wtedy wczytany format mex.fmt oraz tablica il2-pl.tcx przekodowania z układu
iso8859-2 do układu fontów PL (wewnętrznego dla programu TeX). 

W dystrybucjach dostarczono szereg plikow TCX. Można je znaleźć w katalogu
texmf/web2c/:

   amiga-pl.tcx  AmigaPL <--> PL
   il2-pl.tcx    iso8859-2 (latin2) <--> PL
   cp1250pl.tcx  Windows cp1250 <--> PL
   cp852-pl.tcx  IBM cp852 <--> PL
   macce-pl.tcx  Apple MacCE <--> PL
   maz-pl.tcx    Mazovia <--> PL
------------------------------------------------------------------------

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 http://www.gust.org.pl/fonty/fonthint.html.

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

MeX is an adaptation of PLAIN TeX format to the Polish language and to the
Polish printing customs.
Authors: Bogus\l{}aw Jackowski & Marek Ry\'cko.
This document describes shortly creation of mex.fmt and usage in MiKTeX
environment. See mexinfo.eng for detailed informations about MeX.

I. Preparing MeX/pdfMeX  (Polish Plain format)
  * Web2c based distributions (teTeX, fpTeX, TeX Live). Invoke texconfig
    and menu Formats, which edits fmtutil.cnf; uncomment mex (or pdfmex)
    format; after saving the file, the desired format will be generated.
  * MiKTeX (from ver. 2.0). Invoke `MiKTeX Options' menu and the submenu
    `TeX Formats'. Select MeX (or pdfMeX). After pressing `Build' button
    the format will be generated.

II. Usage: the current implementations based on web2c 7.x, 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
         %&mex --translate-file=cp1250pl
    it suffices to run `tex --parse file.tex' with mex.fmt and cp1250pl.tcx
    translation table (Windows cp1250 to internal PL reencoding).
    Permanent parsing of the first line needs the following modification
    in texmf.cnf:
             parse_first_line = t
    (instead of default = f)

    You can also use the command
         `tex &mex -translate-file=TCXFILE myfile.tex'
    or just `mex -translate-file=TCXFILE myfile.tex' when you have linked 
    tex[.exe] into mex[.exe] in the directory containing binaries.
    Several TCX files are provided; they can be found in the texmf/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 enconding
          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.

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