Upload
joanna-ludmila-rycko
View
1.899
Download
5
Embed Size (px)
DESCRIPTION
O raportowaniu problemów z LaTeX-em
Citation preview
MINIMALNY PRZYKŁADI INNE ZASADY RAPORTOWANIA PROBLEMÓW Z LATEX-EM
Joanna Ludmiła Ryć[email protected]
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: [email protected]).
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Ę. . .