Posts Tagged pygments

Pakiet minted w praktyce – konfiguracja

Poniżej można znaleźć kilka informacji o sposobach użycia pakietu minted, pozwalającego na kolorowanie składni w Latexu.

Oznaczanie kodu źródłowego w dokumencie

Kod źródłowy można w przypadku tego pakietu włączyć na kilka sposobów, każdy może się przydać w określonych sytuacjach:

  • \mint – osadzenie pojedynczej linii kodu.
    Kod Latex Efekt działania
    1
    Osadzenie kodu \mint{java}|public class HelloWorld|
    Użycie mint

    Do oznaczenia kodu źródłowego można użyć praktycznie dowolnych znaków, które w nim nie występują. Można także dodać dodatkowe opcje konfiguracyjne.

  • minted – osadzanie większej ilości kodu

    Oznaczenie obszaru kodu źródłowego można zrealizować w następujący sposób:

    Kod Latex Efekt działania
    1
    2
    3
    4
    5
    \begin{minted}{java}
      private boolean hello() {
        return true;
      }
    \end{minted
    }
    Użycie minted
  • listing – pozwala na otoczenia kodu źródłowego i dodanie jeszcze dodatkowego opisu i referencji do kodu
    Kod Latex Efekt działania
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    Bardzo interesująca funkcję można
    znaleźć w przykładzie \ref{java:hello}

    \begin{listing}
      \begin{minted}[gobble=4]{java}
        private boolean hello() {
          return true;
        }
      \end{minted}
      \caption{Funkcja hello}
      \label{java:hello}
    \end{listing
    }
    Użycie listing

    Z takim sposobem wyświetlania kodu łączą się jeszcze dodatkowe polecenia:

    • \listoflistings – wyświetlenie listy wszystkich listingów
    • \renewcommand\listingscaption{Kod źródłowy} – przedefiniowanie standardowego podpisu pod kodem źródłowym
    • \renewcommand\listoflistingscaption{Lista kodów źródłowych} – przedefiniowawszy standardowego opisu do listy kodów źródłowych

Definicja własnych skrótów

Istnieje możliwość zdefiniowania własnych sposobów na oznaczanie kodu źródłowego. W połączeniu wyborem języka oraz zestawem domyślnie używanych opcji może to bardzo ułatwić wprowadzanie kodu źródłowego w ramach dokumentu i zapewni jego spójny wygląd.

  • \newminted – pozwala na definicję skrótu dla środowiska minted:
    Kod Latex Efekt działania
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    \newminted{java}{gobble=2,linenos}

    \begin{javacode}
      private boolean hello() {
        return true;
      }
    \end{javacode
    }

    % definicja dodatkowych opcji

    \begin{javacode*}{linenos=false}
      private boolean hello() {
        return true;
      }
    \end{javacode*
    }
    Użycie newminted

    Istnieje także możliwość definicji własnej nazwy dla środowiska:

    Kod Latex Efekt działania
    1
    2
    3
    4
    5
    6
    \newminted[ja]{java}{frame=single}
    \begin{ja}
      private boolean hello() {
        return true;
      }
    \end{ja
    }
    Własna nazwa środowiska

Niektóry opcje konfiguracyjne

minted pozwala na użycie szeregu opcji konfiguracyjnych, które mają wpływ na sposób formatowania kodu źródłowego. Poniżej lista tych parametrów dla mnie najważniejszych.

  • baselinestretch (auto|dimension) – ustalenie odstępu pomiędzy wierszami:
    Kod Latex Efekt działania
    1
    2
    3
    4
    5
    6
    \begin{minted}[gobble=2,
          baselinestretch=1.5
    ]{java}
      private boolean hello() {
        return true;
      }
    \end{minted
    }
    baselinestretch
  • firstline (integer) – pierwsza linia kodu źródłowego do pokazania, domyślnie wartość 1
    Kod Latex Efekt działania
    1
    2
    3
    4
    5
    6
    \begin{minted}[gobble=2,
          firstline=2
    ]{java}
      private boolean hello() {
        return true;
      }
    \end{minted
    }
    firstline
  • lastline (integer) – ostatnia linia kodu źródłowego do wyświetlania, pozostałe będą ignorowane, domyślnie ostatnia linia
    Kod Latex Efekt działania
    1
    2
    3
    4
    5
    6
    \begin{minted}[gobble=2,
          lastline=2
    ]{java}
      private boolean hello() {
        return true;
      }
    \end{minted
    }
    lastline
  • firstnumber (auto|integer) – numer pierwszej linii, jeżeli włączone jest ich numerowanie
    Kod Latex Efekt działania
    1
    2
    3
    4
    5
    6
    7
    \begin{minted}[gobble=2,
          linenos,
          firstnumber=43
    ]{java}
      private boolean hello() {
        return true;
      }
    \end{minted
    }
    firstnumber
  • frame (none|leftline|topline|bottomline|lines|single) – format ramki wokół kodu xródłowego
    Kod Latex Efekt działania
    1
    2
    3
    4
    5
    6
    \begin{minted}[gobble=2,
          frame=lines
    ]{java}
      private boolean hello() {
        return true;
      }
    \end{minted
    }
    frame
  • gobble (integer) – wycięcie określonej ilości znaków na początku kodu, przydatne aby niwelować wcięcia z kodu Latex
    Kod Latex Efekt działania
    1
    2
    3
    4
    5
    \begin{minted}[gobble=2]{java}
      private boolean hello() {
        return true;
      }
    \end{minted
    }
    gobble
  • linenos (boolean) – dodanie numeracji do poszczególnych linii
    Kod Latex Efekt działania
    1
    2
    3
    4
    5
    6
    \begin{minted}[gobble=2,
          linenos
    ]{java}
      private boolean hello() {
        return true;
      }
    \end{minted
    }
  • samepage (boolean) – nie dzieleniu kodu między różne strony
  • showspaces (boolean) – zaznaczenie spacji (i u mnie nie zadziałało…)

Źródła

Tags: , , ,

Kolorowanie kodu źródłowego w Latex przy użyciu pygments

Do kolorowania (czy też może formatowania) kodu źródłowego można w przypadku Latexa używać pakietu listings. Zapewnia on całkiem spore możliwości formatowania kodu źródłowego, ale ma kilka wad:

  • pakiet ten nie rozumie składni kodu źródłowego, po prostu koloruje tekst wg wprowadzonych słów kluczowych
  • istnieją problemy z obsługą standardu UTF8 (do przeskoczenia, ale zawsze)

Ratunkiem na to może być użycie pakietu pygments napisanego w Pythonie i zintegrowanie go z Latexem przy użyciu pakietu minted.

Instalacja aplikacji pygments

Pierwszym krokiem będzie zainstalowanie pakietu pygments, który będzie odpowiedzialny za generowanie odpowiednio kolorowanej składni. W przypadku systemu Debian oraz Ubuntu wystarczy zainstalować pakiet python-pygments:

$ sudo aptitude install python-pygments

Instalacja pakietu minted

Teraz czas integrację pygments z Latexem. Będzie tutaj pomocny pakiet o nazwie minted. Niestety nie jest on dostępny w ramach pakietów dostarczany z Ubuntu, więc należy go zainstalować w ramach Latexa ręcznie. Poniżej krótka instrukcja jak można to zrobić:

  1. Pobranie plików.

    Pliki można pobrać w formie archiwum (ze strony projektu). Ja jednak wybrałem pobranie aktualnej wersji bezpośrednio z repozytorium (w wersji pakietowej znajduje się błąd, uniemożliwiający kompilacje dokumentacji na Linuksie: Issue 5):

    $ wget "http://minted.googlecode.com/hg/minted.ins" \
            "http://minted.googlecode.com/hg/Makefile" \
            "http://minted.googlecode.com/hg/README" \
            "http://minted.googlecode.com/hg/minted.dtx" \
            "http://minted.googlecode.com/hg/minted.sty"
  2. Kompilacja dokumentacji.
    $ make minted.pdf
    $ make clean
  3. Instalacja pakietu.
    $ sudo mkdir -p /usr/local/share/texmf/tex/latex/minted
    $ sudo cp minted.sty /usr/local/share/texmf/tex/latex/minted
  4. Instalacja dokumentacji
    $ sudo mkdir -p /usr/local/share/texmf/doc/latex/minted
    $ sudo cp minted.pdf /usr/local/share/texmf/doc/latex/minted

    Po instalacji pakietu i dokumentacji należy jesze upewnić się, że uprawnienia nadane plikom będą odpowiednie.

  5. Rejestracja nowych pakietów.
    $ sudo mktexlsr

Dzięki takiej instalacji pakiet będzie dostępny dla wszystkich użytkowników, także jego dokumentacja będzie dostępna poprzez polecenie:

$ texdoc minted

Kolorowanie składni

Aplikacja zainstalowana, moduł do Latexa także więc czas uruchomić i sprawdzić jak działa kolorowanie składni, przykładowy kod:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
\documentclass[a4paper]{article}
\usepackage{fontspec}
\usepackage{minted}

\begin{document}

  Fragment kodu Javy:

  \begin{minted
}[linenos,% numeracja linii
                 numbersep=5pt,% separator numeracji od tekstu
                 gobble=2,% domyślne wcięcie kodu
                 frame=lines,% linie ograniczające
                 framesep=2mm
                 ]{java}
  public class HelloWorld extends Hello {
    private final String STALA = "Tekst"

    public HelloWorld() {
      int zmienna = 5;
    }
  }
  \end{minted}
\end{document
}

Czas teraz na kompilację. Tutaj spotkała mnie niespodzianka, bo okazało się że polecenie pdflatex nie zadziałało:

$ pdflatex  -shell-escape kolorowo.tex

...
 ********************************************
 * XeTeX is required to compile this document.
 * Sorry!
 ********************************************.
...

Komunikat błędu całkiem jasny, ale jakoś nie słyszałem wcześniej o czymś co się nazwy XeTeX (a wielka szkoda, z tego co widzę oszczędziłoby mi to kilku problemów z polskimi znakami). Więc mała modyfikacja polecenia i wszystko powinno już działać:

$ xelatex -shell-escape kolorowo.tex

W wyniku działania tego polecenia powinno być wygenerowanie pliku kolorowo.pdf z ładnym kodem źródłowym. Należy pamiętać o użyciu przełącznika -shell-escape, dzięki czemu jest możliwe wywoływanie zewnętrznych aplikacji (w tym przypadku pygments).

Źródła

Tags: , , , , ,