O raportowaniu problemów z LaTeX-em

1. M
LTEX-
A
Joanna Ludmiła Ryćko
rycko@informatik.hu-berlin.de
BachoTEX
kwietnia – maja

2. T
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
Z

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

5. D ?I
Z
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. D ? II
Z
a wychodzi:
LaTex-Result: 0 Error (s), 0 Warning (s), 0 Bad Box (ex), 0 Page (s)

7. D ? III
Z
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. D ? IV
Z
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. D ?V
Z
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. J , ?
Z
Anonim, brak podpisu imieniem i nazwiskiem.
Ogólnie postawa roszcząca.
Brak konkretów.
Niestaranna stylistyka, gramatyka, ortografia. . .

11. J ?I
Z
A
. Przejrzyj dokumentację LTEX-a, dystrybucji i pakietów.
Na wielu systemach wystarczy wpisać:
texdoc <Paketname> (bez rozszerzenia)
graficznie: texdoctk
. 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/
. Przeszukaj archiwa grup dyskusyjnych dotyczących TEX-a,
np. w Google Groups (http://groups.google.pl).

12. J ? II
Z
. 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. J ? III
Z
. 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. J ? IV
Z
. Szanuj grupowiczów i ich czas.
. Przestrzegaj zasad netykiety.
. Do starannego przygotowania pytania należy również
ortografia i ogólna poprawność językowa Twojego e-maila.

15. Część II
M –

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

17. C ?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. D ?
C ?
Ż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. D ?
C ?
Ż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. C ?
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. S I
Uwaga: zawsze przed rozpoczęciem minimalizowania kodu należy
zachować oryginał i pracować z kopią, żeby nie stracić już
napisanego materiału!

22. S 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. P :
P
S
. Przesuwanie end{document} w kierunku początku pliku.
(blokowo ku górze, każdorazowo kompilując plik, nie
usuwając oryginalnego tekstu!)
. Brak błędu – koniec szukania
cofamy się o jeden krok.
. Usunięcie całego tekstu od begin{document} do początku
znalezionego bloku tekstu.
. Jeśli po skompilowaniu problem w dalszym ciągu się pojawia
to znaczy, że znajduje się on dokładnie w pozostawionym
fragmencie.

24. P :
P
S
Postępowanie jest analogiczne:
Wykomentowuje się polecenia input i include
lub stosuje komendę includeonly.

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

26. U :
U
S
Pakiety mogą się nawzajem zakłócać.
Sprawdzanie przez usuwanie (wykomentowanie) jeden po drugim.
. Zalecana deklaracja pakietów w następującej formie:
usepackage{
amsmath,
listings,
color
}
. Zaprocentowujemy kolejne pakiety.
. Brak błędu – koniec szukania
cofamy się o jeden krok.

27. U :
W I
S
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. U :
W II
S
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. U :
Ś
S
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. U
S
Inne możliwości:
pakiet comment
polecenia warunkowe if
wykorzystanie wbudowanych możliwości edytora do
wykomentowania wielowierszowych obszarów

31. U :
U
S
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
M –

33. P
Błąd składni
Nieoczekiwane zachowanie
Niewytłumaczalne zachowanie

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

35. B II
P
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 III
P
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 IV
P
Błędu już nie ma
stopniowo linijki.
usunięto za dużo
przywracamy
Od linijki 9 znowu pojawia się błąd
należy zaprocentować
wszystko powyżej aż do begin{align*}.
Błąd ciągle jeszcze występuje
można usunąć
wykomentowane linijki.

38. B V
P
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. N I
P
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. N II
P
Oto początek wzoru złożonego przez powyższy kod:
A0
fN (t) = + (. . . ) (1)
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.

41. N III
P
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. N IV
P
Pamiętajmy, że nie chodzi tutaj o poprawność matematyki!
Przykład wciąż bardzo złożony
początku linijki 8:
trzeba go uszczuplić do
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. N I
P
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. N II
P
...
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. N III
P
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. N IV
P
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. N V
P
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. D ...