�ݺ�ߣ

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

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.

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? 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}

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)

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.

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?

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. . .

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, ortograﬁa. . .

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)
graﬁcznie: 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).

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.

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 zidentyﬁkowania problemu.
Jak zadawać inteligentne pytania można przeczytać tu:
http://rtfm.bsdzine.org/

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ż
ortograﬁa 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?

SPOSOBY
Przesunięcie końca
Pojedynczy plik
Połączone pliki

Uproszczenia
Usunięcie niepotrzebnych pakietów
Własne polecenia i środowiska
Ściskanie
Usuwanie graﬁk

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.

DLACZEGO POWINIEN DAĆ SIĘ SKOMPILOWAĆ?

Ż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”.

DLACZEGO MUSI BYĆ MAŁY?

Ż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.


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 zidentyﬁkować 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ży
zachować oryginał i pracować z kopią, żeby nie stracić już
napisanego materiału!

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.

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.

PRZESUNIĘCIE KOŃCA:
POŁĄCZONE PLIKI
SPOSOBY

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

UPROSZCZENIA
SPOSOBY

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

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.

UPROSZCZENIA:
WŁASNE POLECENIA I ŚRODOWISKA I
SPOSOBY

Zdeﬁniowane lub zmodyﬁkowane 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.

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.

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ą.

UPROSZCZENIA
SPOSOBY

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

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ć graﬁkę prostokątem: rule

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

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

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

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

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:
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 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*}

BŁĄD SKŁADNI V
PRZYKŁADY

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.)

NIEOCZEKIWANE ZACHOWANIE I
PRZYKŁADY

Weźmy teraz taki przykład:
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}

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)

NIEOCZEKIWANE ZACHOWANIE III
PRZYKŁADY

Wyczyszczenie własnych makr:
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}

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:

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ć

NIEWYTŁUMACZALNE ZACHOWANIE I
PRZYKŁADY

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

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}

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.

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ąć graﬁkę i wykomentować pakiet graphicx.

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ą.

�ݺ�ߣ

Minimalny przykład i inne zasady raportowania problemów z LaTeXem

More Related Content

Minimalny przykład i inne zasady raportowania problemów z LaTeXem