Prezentacja do referatu wygłoszonego w ramach konferencji BachoTeX 2006, który pokazywał, jak w najlepszy sposób przedstawiać m.in. na grupach dyskusyjnych problemy z LaTeXem, żeby w sposób efektywny uzyskać pomoc.

1. MINIMALNY PRZYKŁAD
A
I INNE ZASADY RAPORTOWANIA PROBLEMÓW Z LTEX-EM
Joanna Ludmiła Ryćko
rycko@informatik.hu-berlin.de
BachoTEX 2006
30 kwietnia – 2 maja 2006

2. TYTUŁEM WSTĘPU
Większa część tego referatu powstała na podstawie
przetł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.

3. Część I
ZADAWANIE PYTAŃ

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

5. DLACZEGO WAŻNE JEST STARANNE SFORMUŁOWANIE? I
ZADAWANIE PYTAŃ
Wiem, ze na pytanie "dlaczego nie działa" bardzo trudno
odpowiedziec, i zdaje sobie sprawe ze troche tak zabrzmi moje
pytanie, 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}
makeindexbegin{document}
title{Tytul}issue{Numer wydania}descri{Opis}
author {Jan Kowalski}sklad {Marek Nowak}date{today}
inserttitlepagetableofcontents
input plik1.tex input plik2.tex %oczywiscie to nie sa puste pliki
appendix input dodatek.tex input plik.ind
end{document}

6. DLACZEGO WAŻNE JEST STARANNE SFORMUŁOWANIE? II
ZADAWANIE PYTAŃ
a wychodzi:
LaTex-Result: 0 Error (s), 0 Warning (s), 0 Bad Box (ex), 0 Page (s)

7. DLACZEGO WAŻNE JEST STARANNE SFORMUŁOWANIE? III
ZADAWANIE PYTAŃ
Błędy:
Brak informacji na temat używanych
programów/pakietów/platformy.
Użyta niestandardowa klasa dokumentu wyklucza możliwość
przetestowania pliku przez kogoś z listy dyskusyjnej.
Z powodu włączanych zewnętrznych plików, które nie zostały
załączone nie jest możliwe skompilowanie dokumentu.
Brak kontekstu wystąpienia wspomnianego błędu.

8. DLACZEGO WAŻNE JEST STARANNE SFORMUŁOWANIE? IV
ZADAWANIE PYTAŃ
Temat: pytanie
mam jedno pytanie
czy instalowanie fontow pod Tex-em odbywa sie w ten sam
sposob co pod linuxem?
piusze prace dyplomowa, i pragnieniem promotora jest abym
opisal jak zachowuje sie czcionka TrueType i Adobe Type 1 pod
linuxem. jak odbywa sie konwersja badz rozpoznanie czcionki. czy
mozecie mi pilnie pomoc?

9. DLACZEGO WAŻNE JEST STARANNE SFORMUŁOWANIE? V
ZADAWANIE PYTAŃ
Błędy:
Brak konkretnego tematu: słowo „pytanie” nic nikomu nie
powie.
Słowo „pilnie” w treści.
Niestarannie napisane (brak dużych liter, znaków
przestankowych, literówki).
Autor nie wspomniał, co już wie w tym temacie, czego się już
nauczył, jakie informacje i gdzie znalazł.
Na brak polskich liter przymykamy oko. . .

10. JAK JESZCZE PISAĆ, ŻEBY NIE OTRZYMAĆ ODPOWIEDZI?
ZADAWANIE PYTAŃ
Anonim, brak podpisu imieniem i nazwiskiem.
Ogólnie postawa roszcząca.
Brak konkretów.
Niestaranna stylistyka, gramatyka, ortografia. . .

11. JAK ZWIĘKSZYĆ SZANSE NA POMOCNĄ ODPOWIEDŹ? I
ZADAWANIE PYTAŃ
A
1. Przejrzyj dokumentację LTEX-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.pl
lub w innym znanym Ci języku, np.: po niemiecku
http://www.dante.de/faq/de-tex-faq/
lub po angielsku
http://www.tex.ac.uk/cgi-bin/texfaq2html/
3. Przeszukaj archiwa grup dyskusyjnych dotyczących TEX-a,
np. w Google Groups (http://groups.google.pl).

12. JAK ZWIĘKSZYĆ SZANSE NA POMOCNĄ ODPOWIEDŹ? II
ZADAWANIE PYTAŃ
4. Sprawdź, czy Twój dokument nie zawiera przestarzałych lub
niewskazanych pakietów czy poleceń. Informacje
w 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.html
można plik sprawdzić automatycznie.

13. JAK ZWIĘKSZYĆ SZANSE NA POMOCNĄ ODPOWIEDŹ? III
ZADAWANIE PYTAŃ
5. Stwórz minimalny plik (jak? o tym za chwilę).
Wyślij go z jasnym opisem problemu, komunikatem o błędzie
i listą wersji używanych pakietów (polecenie listfiles
w preambule dokumentu).
Nie zapomnij napisać, co i jak zrobiłeś/zrobiłaś do tej pory
w celu zidentyfikowania problemu.
Jak zadawać inteligentne pytania można przeczytać tu:
http://rtfm.bsdzine.org/

14. JAK ZWIĘKSZYĆ SZANSE NA POMOCNĄ ODPOWIEDŹ? IV
ZADAWANIE 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.

15. Część II
MINIMALNY PRZYKŁAD – ZASADY

16. CZYM JEST MINIMALNY PRZYKŁAD?
Dlaczego powinien dać się skompilować?
Dlaczego musi być mały?
SPOSOBY
Przesunięcie końca
Pojedynczy plik
Połączone pliki
Uproszczenia
Usunięcie niepotrzebnych pakietów
Własne polecenia i środowiska
Ściskanie
Usuwanie grafik

17. CZYM JEST MINIMALNY PRZYKŁAD? I
Tworzenie minimalnego przykładu – metoda rozpoznawania
i usuwania oraz określania przyczyn jakiegoś zachowania.
Warunki: możliwie krótki kod, gotowy do skompilowania.

18. DLACZEGO POWINIEN DAĆ SIĘ SKOMPILOWAĆ?
CZYM JEST MINIMALNY PRZYKŁAD?
Żeby pytający nie mógł z niewiedzy usunąć informacji, które
mogą się okazać ważne do postawienia diagnozy;
żeby odpowiadający mógł przenieść i wypróbować ów
fragment kodu poprzez „kopiuj i wklej”.

19. DLACZEGO MUSI BYĆ MAŁY?
CZYM JEST MINIMALNY PRZYKŁAD?
Żeby odpowiadający nie musiał się przedzierać przez długie,
nieistotne partie kodu,
ponieważ w ten sposób ogranicza się źródła błędów,
bo krótkie przykłady dobrze się wysyła na grupę dyskusyjną,
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.,
bo przy małych dokumentach nie traci się zbyt szybko
orientacji.

20. CZYM JEST MINIMALNY PRZYKŁAD?
Nawet początkujący nie powinni mieć problemu ze stworzeniem
takiego minimalnego przykładu – potrzebna jest tylko odrobina
cierpliwoś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).

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

22. SPOSOBY II
Zasada „dziel i (o-)panuj” (niem. teile und (be-)herrsche; polski
odpowiednik dziel i rządź nie oddaje podwójnego znaczenia tej
zasady).
Dzielić można na różne sposoby, zależnie od struktury tekstu.

23. PRZESUNIĘCIE KOŃCA:
POJEDYNCZY PLIK
SPOSOBY
1. Przesuwanie end{document} w kierunku początku pliku.
(blokowo ku górze, każdorazowo kompilując plik, nie
usuwają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 pozostawionym
fragmencie.

24. PRZESUNIĘCIE KOŃCA:
POŁĄCZONE PLIKI
SPOSOBY
Postępowanie jest analogiczne:
Wykomentowuje się polecenia input i include
lub stosuje komendę includeonly.

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

26. UPROSZCZENIA:
USUNIĘCIE NIEPOTRZEBNYCH PAKIETÓW
SPOSOBY
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.

27. UPROSZCZENIA:
WŁASNE POLECENIA I ŚRODOWISKA I
SPOSOBY
Zdefiniowane lub zmodyfikowane przez siebie polecenia
i środowiska:
jeśli nie są używane w pozostawionym fragmencie
dokumentu, powinny zostać usunięte,
w przeciwnym wypadku powinny zostać opróżnione, czyli
albo przekazywać argumenty danego makra bez „ubierania”
ich w dodatkowe funkcje lub nie powinny mieć żadnego
działania.

28. UPROSZCZENIA:
WŁASNE POLECENIA I ŚRODOWISKA II
SPOSOBY
Przykład:
newcommand{dialog}[2]{textcolor{red}{%
textbf{#1} powiedzial{}:} textit{#2}}
powinno zostać zamienione na:
newcommand{dialog}[2]{#1 #2} %tylko argumenty makra
lub na:
newcommand{dialog}[2]{} %brak jakiegokolwiek dzial{}ania
Jeśli błąd jest spowodowany przez własne makro, należy je
również sprawdzić krok po kroku.

29. UPROSZCZENIA:
ŚCISKANIE
SPOSOBY
Przesuwamy koniec, linijka po linijce
Idealnie: zostaje jedna linijka dokumentu, której można się
samemu przyjrzeć lub wysłać ją na grupę dyskusyjną.

30. UPROSZCZENIA
SPOSOBY
Inne możliwości:
pakiet comment
polecenia warunkowe if
wykorzystanie wbudowanych możliwości edytora do
wykomentowania wielowierszowych obszarów

31. UPROSZCZENIA:
USUWANIE GRAFIK
SPOSOBY
Obrazki są problematyczne: nie można ich przesłać na grupę ani
umieścić w Internecie, bo mają duże rozmiary i mogą zawierać
poufne informacje.
Rozwiązanie: zastąpić grafikę prostokątem: rule

32. Część III
MINIMALNY PRZYKŁAD – TRZY PRZYKŁADY
TWORZENIA

33. PRZYKŁADY
Błąd składni
Nieoczekiwane zachowanie
Niewytłumaczalne zachowanie

34. BŁĄD SKŁADNI I
PRZYKŁADY
Kod:
Oczekiwany efekt:
documentclass[a4paper]{article}
usepackage{amsmath}
S1 > S > S2
⇒ S1 = ex
begin{document}
begin{align*}
S_1 > S > S_2
Rightarrow S_1 &
Rightarrow S_1 &
Rightarrow S_1 &
& =
end{align*}
end{document}
⇒ S1 = ey
= mathrm{e}^{}{x}
= mathrm{e}^{}{y}
= mathrm{e^{}{x} ↵
boxed{mathrm{e}^{}{z}}
⇒ S1 = ex
= ez

35. BŁĄD SKŁADNI II
PRZYKŁ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

36. BŁĄD SKŁADNI III
PRZYKŁ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}

37. BŁĄD SKŁADNI IV
PRZYKŁADY
usunięto za dużo
przywracamy
Od linijki 9 znowu pojawia się błąd
należy zaprocentować
wszystko powyżej aż do
.
Błąd ciągle jeszcze występuje
można usunąć
wykomentowane linijki.
Błędu już nie ma
stopniowo linijki.
begin{align*}

38. BŁĄD SKŁADNI V
PRZYKŁ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ące
do siebie klamry.)

39. NIEOCZEKIWANE ZACHOWANIE I
PRZYKŁ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}^{}
inftyleft(frac{1}{2}left(A_k - im B_kright)
e^{}{imalpha t} + frac{1}{2}left( A_k +
im B_k right)e^{}{- imalpha t}right)
& text{mit } B_0=0 text{ und } alpha = omega t
end{align}
end{document}

40. NIEOCZEKIWANE ZACHOWANIE II
PRZYKŁADY
Oto początek wzoru złożonego przez powyższy kod:
fN (t) =
A0
+ (. . . )
2
Tu przeszkadza subiektywnie zbyt mały odstęp między znakiem
równości a ułamkiem (linijka 8).
Kod jest „trochę” nieczytelny.
Ograniczamy się do najistotniejszych informacji.
(1)

41. NIEOCZEKIWANE ZACHOWANIE III
PRZYKŁ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}^{}
inftyleft(frac{1}{2}left(A_k - im B_kright)
e^{}{imalpha t} + frac{1}{2}left( A_k +
im B_k right)e^{}{- imalpha t}right)
& text{mit } B_0=0 text{ und } alpha = omega t
end{align}
end{document}

42. NIEOCZEKIWANE ZACHOWANIE IV
PRZYKŁADY
Pamiętajmy, że nie chodzi tutaj o poprawność matematyki!
Przykład wciąż bardzo złożony
trzeba go uszczuplić do
począ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
na grupę dyskusyjną.
można go wysłać

43. NIEWYTŁUMACZALNE ZACHOWANIE I
PRZYKŁ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}
...

44. NIEWYTŁUMACZALNE ZACHOWANIE II
PRZYKŁADY
...
begin{document}
To jest tylko testowy tekst, kt’ory ma pom’oc wytl{}umaczy’c
zasady minimalnego przykl{}adu nowym i~poczk{a}tkujacym, kt’orzy
pisza na GUSTListk{e}. i~teraz dodajemy sobie obrazek. Chcemy
sprawdzi’c, jak zareaguje na niego LaTeX.
includegraphics{grafika} i~piszemy dalej obok niego. Niestety
g’orna krawk{e}d’z obrazka nie wyrownuje sik{e} z~tym tekstem.
Trzeba wik{e}c szybko stworzy’c minimalny przyklad i~wysla’c
pytanie na GUSTListk{e}, dlaczego to tak jest. Ale dopiero po
doglk{e}bnym przebadaniu tematu przez siebie.
end{document}

45. NIEWYTŁUMACZALNE ZACHOWANIE III
PRZYKŁADY
Sprawdzamy:
pakiety (nic to nie daje)
Redukujemy:
pozostałe niepotrzebne dokumenty (w tym opcje klasy),
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 wszystkich
dystrybucjach.

46. NIEWYTŁUMACZALNE ZACHOWANIE IV
PRZYKŁ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. Trzeba
jeszcze usunąć grafikę i wykomentować pakiet graphicx.

47. NIEWYTŁUMACZALNE ZACHOWANIE V
PRZYKŁ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ą.

48. DZIĘKUJĘ ZA UWAGĘ. . .