MINIMALNY PRZYKŁADI INNE ZASADY RAPORTOWANIA PROBLEMÓW Z LATEX-EM

Joanna Ludmiła Ryćkorycko@informatik.hu-berlin.de

BachoTEX 2006

30 kwietnia – 2 maja 2006

TYTUŁEM WSTĘPU

Większa część tego referatu powstała na podstawieprzetłumaczonego przeze mnie z języka niemieckiego artykułu,napisanego przez Christiana Faulhammera.

Oryginalny tekst można obejrzeć na stronie:http://www.minimalbeispiel.de

English version and of course german version are available.

Część I

ZADAWANIE PYTAŃ

ZADAWANIE PYTAŃDlaczego ważne jest staranne sformułowanie?Jak jeszcze pisać, żeby nie otrzymać odpowiedzi?Jak zwiększyć szanse na pomocną odpowiedź?

DLACZEGO WAŻNE JEST STARANNE SFORMUŁOWANIE? IZADAWANIE PYTAŃ

Wiem, ze na pytanie "dlaczego nie działa" bardzo trudnoodpowiedziec, i zdaje sobie sprawe ze troche tak zabrzmi mojepytanie, niemniej...Po kompilacji nie ma ani jednej strony, a ja nie wiem dlaczego.Plik wyglada mniej wiecej tak:\documentclass[a4paper,12pt,twoside,dvips]{manual_w1250}\usepackage[OT4]{polski}\usepackage{colordvi, times}\usepackage[bookmarks=true]{hyperref}\makeindex\begin{document}\title{Tytu\l}\issue{Numer wydania}\descri{Opis}\author {Jan Kowalski}\sklad {Marek Nowak}\date{\today}\inserttitlepage\tableofcontents\input plik1.tex \input plik2.tex %oczywiscie to nie sa puste pliki\appendix \input dodatek.tex \input plik.ind\end{document}

DLACZEGO WAŻNE JEST STARANNE SFORMUŁOWANIE? IIZADAWANIE PYTAŃ

a wychodzi:LaTex-Result: 0 Error (s), 0 Warning (s), 0 Bad Box (ex), 0 Page (s)

DLACZEGO WAŻNE JEST STARANNE SFORMUŁOWANIE? IIIZADAWANIE PYTAŃ

Błędy:I Brak informacji na temat używanych

programów/pakietów/platformy.I Użyta niestandardowa klasa dokumentu wyklucza możliwość

przetestowania pliku przez kogoś z listy dyskusyjnej.I Z powodu włączanych zewnętrznych plików, które nie zostały

załączone nie jest możliwe skompilowanie dokumentu.I Brak kontekstu wystąpienia wspomnianego błędu.

DLACZEGO WAŻNE JEST STARANNE SFORMUŁOWANIE? IVZADAWANIE PYTAŃ

Temat: pytanie

mam jedno pytanieczy instalowanie fontow pod Tex-em odbywa sie w ten samsposob co pod linuxem?piusze prace dyplomowa, i pragnieniem promotora jest abymopisal jak zachowuje sie czcionka TrueType i Adobe Type 1 podlinuxem. jak odbywa sie konwersja badz rozpoznanie czcionki. czymozecie mi pilnie pomoc?

DLACZEGO WAŻNE JEST STARANNE SFORMUŁOWANIE? VZADAWANIE PYTAŃ

Błędy:I Brak konkretnego tematu: słowo „pytanie” nic nikomu nie

powie.I Słowo „pilnie” w treści.I Niestarannie napisane (brak dużych liter, znaków

przestankowych, literówki).I Autor nie wspomniał, co już wie w tym temacie, czego się już

nauczył, jakie informacje i gdzie znalazł.I Na brak polskich liter przymykamy oko. . .

JAK JESZCZE PISAĆ, ŻEBY NIE OTRZYMAĆ ODPOWIEDZI?ZADAWANIE PYTAŃ

I Anonim, brak podpisu imieniem i nazwiskiem.I Ogólnie postawa roszcząca.I Brak konkretów.I Niestaranna stylistyka, gramatyka, ortografia. . .

JAK ZWIĘKSZYĆ SZANSE NA POMOCNĄ ODPOWIEDŹ? IZADAWANIE PYTAŃ

1. Przejrzyj dokumentację LATEX-a, dystrybucji i pakietów.Na wielu systemach wystarczy wpisać:texdoc <Paketname> (bez rozszerzenia)graficznie: texdoctk

2. Przejrzyj FAQ po polsku http://faq.gust.org.pllub w innym znanym Ci języku, np.: po niemieckuhttp://www.dante.de/faq/de-tex-faq/lub po angielskuhttp://www.tex.ac.uk/cgi-bin/texfaq2html/

3. Przeszukaj archiwa grup dyskusyjnych dotyczących TEX-a,np. w Google Groups (http://groups.google.pl).

JAK ZWIĘKSZYĆ SZANSE NA POMOCNĄ ODPOWIEDŹ? IIZADAWANIE PYTAŃ

4. Sprawdź, czy Twój dokument nie zawiera przestarzałych lubniewskazanych pakietów czy poleceń. Informacjew ftp://dante.ctan.org/tex-archive/info/l2tabu/w języku angielskim, niemieckim, francuskim lub włoskim.Na stronie http://www.kohm.name/markus/texidate.htmlmożna plik sprawdzić automatycznie.

JAK ZWIĘKSZYĆ SZANSE NA POMOCNĄ ODPOWIEDŹ? IIIZADAWANIE PYTAŃ

5. Stwórz minimalny plik (jak? o tym za chwilę).Wyślij go z jasnym opisem problemu, komunikatem o błędziei listą wersji używanych pakietów (polecenie \listfiles

w preambule dokumentu).Nie zapomnij napisać, co i jak zrobiłeś/zrobiłaś do tej poryw celu zidentyfikowania problemu.Jak zadawać inteligentne pytania można przeczytać tu:http://rtfm.bsdzine.org/

JAK ZWIĘKSZYĆ SZANSE NA POMOCNĄ ODPOWIEDŹ? IVZADAWANIE PYTAŃ

6. Szanuj grupowiczów i ich czas.7. Przestrzegaj zasad netykiety.8. Do starannego przygotowania pytania należy również

ortografia i ogólna poprawność językowa Twojego e-maila.

Część II

MINIMALNY PRZYKŁAD – ZASADY

CZYM JEST MINIMALNY PRZYKŁAD?Dlaczego powinien dać się skompilować?Dlaczego musi być mały?

SPOSOBYPrzesunięcie końca

Pojedynczy plikPołączone pliki

UproszczeniaUsunięcie niepotrzebnych pakietówWłasne polecenia i środowiskaŚciskanieUsuwanie grafik

CZYM JEST MINIMALNY PRZYKŁAD? I

Tworzenie minimalnego przykładu – metoda rozpoznawaniai usuwania oraz określania przyczyn jakiegoś zachowania.

Warunki: możliwie krótki kod, gotowy do skompilowania.

DLACZEGO POWINIEN DAĆ SIĘ SKOMPILOWAĆ?CZYM JEST MINIMALNY PRZYKŁAD?

I Żeby pytający nie mógł z niewiedzy usunąć informacji, któremogą się okazać ważne do postawienia diagnozy;

I żeby odpowiadający mógł przenieść i wypróbować ówfragment kodu poprzez „kopiuj i wklej”.

DLACZEGO MUSI BYĆ MAŁY?CZYM JEST MINIMALNY PRZYKŁAD?

I Żeby odpowiadający nie musiał się przedzierać przez długie,nieistotne partie kodu,

I ponieważ w ten sposób ogranicza się źródła błędów,I bo krótkie przykłady dobrze się wysyła na grupę dyskusyjną,I ponieważ przez samo minimalizowanie kodu źródłowego

można znaleźć brakujące nawiasy, błędy składniowe,zapomniane polecenia „przełączające” (np. \bfseries) itp.,

I bo przy małych dokumentach nie traci się zbyt szybkoorientacji.

CZYM JEST MINIMALNY PRZYKŁAD?

Nawet początkujący nie powinni mieć problemu ze stworzeniemtakiego minimalnego przykładu – potrzebna jest tylko odrobinacierpliwości i zdrowego rozsądku.

Najczęściej można zidentyfikować problem samemu i oszczędzićsobie wysyłania pytania na grupę dyskusyjną (np. na ListęGUST-u: gust-l@man.torun.pl).

SPOSOBY I

Uwaga: zawsze przed rozpoczęciem minimalizowania kodu należyzachować oryginał i pracować z kopią, żeby nie stracić jużnapisanego materiału!

SPOSOBY II

Zasada „dziel i (o-)panuj” (niem. teile und (be-)herrsche; polskiodpowiednik dziel i rządź nie oddaje podwójnego znaczenia tejzasady).

Dzielić można na różne sposoby, zależnie od struktury tekstu.

PRZESUNIĘCIE KOŃCA:POJEDYNCZY PLIKSPOSOBY

1. Przesuwanie \end{document} w kierunku początku pliku.(blokowo ku górze, każdorazowo kompilując plik, nieusuwając oryginalnego tekstu!)

2. Brak błędu – koniec szukania cofamy się o jeden krok.3. Usunięcie całego tekstu od \begin{document} do początku

znalezionego bloku tekstu.4. Jeśli po skompilowaniu problem w dalszym ciągu się pojawia

to znaczy, że znajduje się on dokładnie w pozostawionymfragmencie.

PRZESUNIĘCIE KOŃCA:POŁĄCZONE PLIKISPOSOBY

Postępowanie jest analogiczne:

Wykomentowuje się polecenia \input i \include

lub stosuje komendę \includeonly.

UPROSZCZENIASPOSOBY

Po znalezieniu błędnego bloku trzeba starać się uprościć go natyle, żeby problem sprowadzić do jednej linijki.

UPROSZCZENIA:USUNIĘCIE NIEPOTRZEBNYCH PAKIETÓWSPOSOBY

Pakiety mogą się nawzajem zakłócać.

Sprawdzanie przez usuwanie (wykomentowanie) jeden po drugim.1. Zalecana deklaracja pakietów w następującej formie:

\usepackage{amsmath,listings,color

}

2. Zaprocentowujemy kolejne pakiety.3. Brak błędu – koniec szukania cofamy się o jeden krok.

UPROSZCZENIA:WŁASNE POLECENIA I ŚRODOWISKA ISPOSOBY

Zdefiniowane lub zmodyfikowane przez siebie poleceniai środowiska:

I jeśli nie są używane w pozostawionym fragmenciedokumentu, powinny zostać usunięte,

I w przeciwnym wypadku powinny zostać opróżnione, czylialbo przekazywać argumenty danego makra bez „ubierania”ich w dodatkowe funkcje lub nie powinny mieć żadnegodziałania.

UPROSZCZENIA:WŁASNE POLECENIA I ŚRODOWISKA IISPOSOBY

Przykład:\newcommand{\dialog}[2]{\textcolor{red}{%\textbf{#1} powiedzia\l{}:} \textit{#2}}

powinno zostać zamienione na:\newcommand{\dialog}[2]{#1 #2} %tylko argumenty makra

lub na:\newcommand{\dialog}[2]{} %brak jakiegokolwiek dzia\l{}ania

Jeśli błąd jest spowodowany przez własne makro, należy jerównież sprawdzić krok po kroku.

UPROSZCZENIA:ŚCISKANIESPOSOBY

I Przesuwamy koniec, linijka po linijceI Idealnie: zostaje jedna linijka dokumentu, której można się

samemu przyjrzeć lub wysłać ją na grupę dyskusyjną.

UPROSZCZENIASPOSOBY

Inne możliwości:I pakiet comment

I polecenia warunkowe \if

I wykorzystanie wbudowanych możliwości edytora dowykomentowania wielowierszowych obszarów

UPROSZCZENIA:USUWANIE GRAFIKSPOSOBY

Obrazki są problematyczne: nie można ich przesłać na grupę aniumieścić w Internecie, bo mają duże rozmiary i mogą zawieraćpoufne informacje.

Rozwiązanie: zastąpić grafikę prostokątem: \rule

Część III

MINIMALNY PRZYKŁAD – TRZY PRZYKŁADYTWORZENIA

PRZYKŁADYBłąd składniNieoczekiwane zachowanieNiewytłumaczalne zachowanie

BŁĄD SKŁADNI IPRZYKŁADY

Kod:\documentclass[a4paper]{article}\usepackage{amsmath}

\begin{document}\begin{align*}S_1 > S > S_2 \\\Rightarrow S_1 & = \mathrm{e}^{}{x} \\\Rightarrow S_1 & = \mathrm{e}^{}{y} \\\Rightarrow S_1 & = \mathrm{e^{}{x} ↵

\\& = \boxed{\mathrm{e}^{}{z}}

\end{align*}\end{document}

Oczekiwany efekt:

S1 > S > S2

⇒ S1 = ex⇒ S1 = ey⇒ S1 = ex

= ez

BŁĄD SKŁADNI IIPRZYKŁADY

Informacja o błędzie brzmi:Runaway argument?S_1 > S > S_2 \\\Rightarrow S_1 & = \mathrm{e}^{}{x} \\\Rightarrow S_1 & = \mathrm \ETC

! File ended while scanning use of \align*.<inserted text>

\par

BŁĄD SKŁADNI IIIPRZYKŁADY

Powyższe pozwala przypuszczać, że błędu należy szukaćw linijkach 7–9. w związku z tym trzeba wykomentować fragmentśrodowiska align:\documentclass[a4paper]{article}\usepackage{amsmath}

\begin{document}\begin{align*}S_1 > S > S_2 \\%\Rightarrow S_1 & = \mathrm{e}^{}{x} \\%\Rightarrow S_1 & = \mathrm{e}^{}{y} \\%\Rightarrow S_1 & = \mathrm{e^{}{x} \\% & = \boxed{\mathrm{e}^{}{z}}\end{align*}\end{document}

BŁĄD SKŁADNI IVPRZYKŁADY

I Błędu już nie ma usunięto za dużo przywracamystopniowo linijki.

I Od linijki 9 znowu pojawia się błąd należy zaprocentowaćwszystko powyżej aż do \begin{align*}.

I Błąd ciągle jeszcze występuje można usunąćwykomentowane linijki.

BŁĄD SKŁADNI VPRZYKŁADY

\documentclass[a4paper]{article}\usepackage{amsmath}

\begin{document}\begin{align*}\Rightarrow S_1 & = \mathrm{e^{}{x} \\\end{align*}\end{document}

Otrzymany plik jest minimalny.

Brakuje zamykającej klamry po \mathrm{e^{}.(Pomocą służyć mogą dobre edytory, które wyróżniają pasującedo siebie klamry.)

NIEOCZEKIWANE ZACHOWANIE IPRZYKŁADY

Weźmy teraz taki przykład:\documentclass[a4paper]{article}\usepackage{amsmath}\newcommand{\im}{\mathrm{i}}\newcommand{\e}{\mathrm{e}}

\begin{document}\begin{align}f_N(t) = & \frac{A_0}{2} + \sum_{k=1}^{}\infty\left(\frac{1}{2}\left(A_k - \im B_k\right)\e^{}{\im\alpha t} + \frac{1}{2}\left( A_k +\im B_k \right)\e^{}{- \im\alpha t}\right)\\

& \text{mit } B_0=0 \text{ und } \alpha = \omega t\end{align}\end{document}

NIEOCZEKIWANE ZACHOWANIE IIPRZYKŁADY

Oto początek wzoru złożonego przez powyższy kod:

fN(t) =A0

2+ (. . . ) (1)

Tu przeszkadza subiektywnie zbyt mały odstęp między znakiemrówności a ułamkiem (linijka 8).

Kod jest „trochę” nieczytelny.

Ograniczamy się do najistotniejszych informacji.

NIEOCZEKIWANE ZACHOWANIE IIIPRZYKŁADY

Wyczyszczenie własnych makr:\documentclass[a4paper]{article}\usepackage{amsmath}\newcommand{\im}{}\newcommand{\e}{}

\begin{document}\begin{align}f_N(t) = & \frac{A_0}{2} + \sum_{k=1}^{}\infty\left(\frac{1}{2}\left(A_k - \im B_k\right)\e^{}{\im\alpha t} + \frac{1}{2}\left( A_k +\im B_k \right)\e^{}{- \im\alpha t}\right)\\

& \text{mit } B_0=0 \text{ und } \alpha = \omega t\end{align}\end{document}

NIEOCZEKIWANE ZACHOWANIE IVPRZYKŁADY

Pamiętajmy, że nie chodzi tutaj o poprawność matematyki!Przykład wciąż bardzo złożony trzeba go uszczuplić dopoczątku linijki 8:\documentclass[a4paper]{article}\usepackage{amsmath}\newcommand{\im}{}\newcommand{\e}{}

\begin{document}\begin{align}f = & \frac{a}{b}\end{align}\end{document}

Otrzymany przyklad jest już minimalny można go wysłaćna grupę dyskusyjną.

NIEWYTŁUMACZALNE ZACHOWANIE IPRZYKŁADY

Następny przykład korzysta z różnych pakietów, ponieważzawiera tekst, grafikę i matematykę.\documentclass[a4paper,12pt]{scrreprt}\usepackage{graphicx}\usepackage{polski,amsmath,exscale

}\usepackage[latin2]{inputenc}

...

NIEWYTŁUMACZALNE ZACHOWANIE IIPRZYKŁADY

...

\begin{document}To jest tylko testowy tekst, kt\’ory ma pom\’oc wyt\l{}umaczy\’czasady minimalnego przyk\l{}adu nowym i~pocz\k{a}tkuj\acym, kt\’orzypisz\a na GUSTList\k{e}. i~teraz dodajemy sobie obrazek. Chcemysprawdzi\’c, jak zareaguje na niego \LaTeX.

\includegraphics{grafika} i~piszemy dalej obok niego. Niestetyg\’orna kraw\k{e}d\’z obrazka nie wyr\ownuje si\k{e} z~tym tekstem.Trzeba wi\k{e}c szybko stworzy\’c minimalny przyk\lad i~wys\la\’cpytanie na GUSTList\k{e}, dlaczego to tak jest. Ale dopiero podog\l\k{e}bnym przebadaniu tematu przez siebie.\end{document}

NIEWYTŁUMACZALNE ZACHOWANIE IIIPRZYKŁADY

Sprawdzamy:I pakiety (nic to nie daje)

Redukujemy:I pozostałe niepotrzebne dokumenty (w tym opcje klasy),I niestandardową klasę dokumentu, pochodzącą z pakietu

„KOMA-Script” (co również nic nie daje) zastępujemy jąklasą standardową report, która jest dostępna we wszystkichdystrybucjach.

NIEWYTŁUMACZALNE ZACHOWANIE IVPRZYKŁADY

Naprawdę minimalny stan pliku:\documentclass{report}\usepackage{graphicx}

\begin{document}\includegraphics{grafika} Testowy tekst.\end{document}

Ale, ale. . . , to tak naprawdę nie jest minimalny przykład. Trzebajeszcze usunąć grafikę i wykomentować pakiet graphicx.

NIEWYTŁUMACZALNE ZACHOWANIE VPRZYKŁADY

TADAA. . .\documentclass{report}%\usepackage{graphicx}

\begin{document}\rule{3cm}{4cm} Testowy tekst.\end{document}

Teraz już można wysłać przykład na grupę dyskusyjną.

DZIĘKUJĘ ZA UWAGĘ. . .