Wymagania dotyczące składu dokumentacji projektów w L^ATEXu

Grzegorz J. Nalepa gjn@agh.edu.pl

marzec 2007, $Revision: 1.2$

Spis rzeczy

• Wymagania podstawowe
  • Wersja językowa
  
  
• Skład w L^ATEXu
  • Układ dokumentu
  • Styl aghdps
  • Uwagi techniczne
  
  
• Wersja drukowana
• Wersja elektroniczna
• Odbiór dokumentacji

Wymagania podstawowe

Prawidłowo sporządzona dokumentacja stanowi istotną część projektu. Spełnienie przedstawionych dalej wymagań jest warunkiem koniecznym przyjęcia dokumentacji.

Skład

Dokumentacja ma być złożona zgodnie z podanymi w p. 2 wymaganiami.

Bibliografia

Na końcu projektu na być bibliografia, złożona w sposób następujący:

[numer] Pełne_Imię Nazwisko_Autora, \textit{Tytuł}, Wydawnictwo, Miejsce, Rok.

Bibliografia ma być złożona przy pomocy środowiska thebibliography. Należy również podać tłumacza przed wydawnictwem. W przypadku artykułu naukowego podaje się nazwę konferencji/materiałów przed/zamiast wydawnictwa. Przykład:

\bibitem{ansic} Brian W. Kernighan, Dennis M. Ritchie, \textit{Język ANSI C},
                tłum. Danuta i Marek Kruszewscy, WNT, Warszawa 1994.

Jeżeli pozycja bibliograficzna jest artykułem, stroną odnalezioną w Internecie, należy określić: autora, URL i datę ostatniej modyfikacji.

Do bibliografii należy się odwoływać (cytować)! Na przykład \cite{ansic}. W bibliografii należy również podać najważniejsze adresy WWW. Jeżeli pozycja bibliograficzna jest po prostu stroną, serwisem WWW rółnież należy ją umieścić w sposób analogiczny do powyższego i cytować ją, np.:

\bibitem{gnu} Free Software Foundation, \textit{The GNU Operating System},
              \url{www.gnu.org}, 2005.02.27.

WAŻNE aby przy powoływaniu się na stronę w Internecie podać w miarę możliwości datę jej ostatniego uaktulanienia!

Jeżeli korzysta się z projektów kolegów należy je wymienić w bibliografii i zacytować to w odpowiednim miejscu dokumentu.

Kontakt

Na stronie tytułowej mają być podane nazwiska autorów i ich adresy email, które mogą być wykorzystane do konsultacji w sprawach związanych z projektem.

Wersja językowa

Dokumentacja ma być napisana w języku polskim. Przez język polski rozumie się tu poprawny język polski, a nie studencko-informatyczny slang jaki niejednokrotnie można spotkać.

Reguły i słownictwo poprawnego języka polskiego jest określone w słownikach języka polskiego, takich jak: słownik języka polskiego, ortograficzny, frazeologiczny itp. Należy również przestrzegać reguł polskiej interpunkcji, opisanych najczęściej na początku słownika ortograficznego. Trzeba zauwać, że sprawdzenie dokumentu jedynie przy pomocy komputerowego słownika ortograficznego (pisowni) (ang. spell checker) nie wystarczy do spełnienia tych wymagań!

Dokumentacja ma być pisana w stronie biernej i zasadniczo w czasie teraźniejszym. Tak więc nie pisze się ,,zainstalowaliśmy program przy pomocy...'', lecz ,,program instaluje się przy pomocy...''; nie: ,,na stronie XYZ nie znaleźliśmy'', lecz ,,na stronie XYX nie znaleziono''.

Terminy obcojęzyczne pisze się italiką, np. file. W przypadku niejednoznacznego, lub dokonanego przez autorów dokumentu, przekładu terminu obcojęzycznego, należy odpowiednio podać słowo obcojęzyczne, np. ,,stwierdzono, że rozgałęzianie (ang. branching)...''.

W przypadku zmian fleksyjnych końcówek wyrazów czy nazw własnych pochodzących z języków obcych proponuje się odpowiednią polonizacją końcówki, np.: ,,linuksowy'', a nie ,,linuxowy''. Warto przypomnieć, że przymiotniki w języku polskim pisze się z małej litery.

Jeżeli chodzi o tłumaczenie terminów fachowych, to:

1. Należy go unikać, jeżeli istnieje ugruntowane polskie tłumaczenie, np. pisać ,,mysz'' zamiast mouse, ,,jądro'' zamiast kernel, ,,podręcznik-tutorial'', itp.
2. W wyborze tłumaczenia należy kierować się słownikiem frazeologicznym inteligencją i dobrym smakiem; na przykład nie powinno się pisać ,,ściągnąć plik'', lecz ,,skopiować/pobrać plik''.
3. Należy unikać anglicyzmów, również w związkach frazeologicznych, np. nie ,,pod Uniksem'' (po polsku mówi się np. ,,pod stołem''), ale ,,w środowisku systemu Unix''.

Skład w L^ATEXu

Dokumentacja ma być złożona w całości przy pomocy systemu L^ATEX. Należy używać możliwości systemu w wersji L^ATEX2e , tzn. unikać konstrukcji z L^ATEX2.09. Strona z odnośnikami do podręczników tego systemu jest pod adresem http://galaxy.uci.agh.edu.pl/~gjn/dydaktyka. Poza tym należy korzystać z ogólnie dostępnej dokumentacji:

• http://www.latex-project.org
• http://www.gust.org.pl
• http://www.ia.pw.edu.pl/~wujek/tex

Dokumentacja ma być pisana przy pomocy czcionek z kodowaniem ISO-8859-2 (latin2) (tak!, L^ATEX bez problemu je obsługuje, również w systemie z guzikiem ,,start'').

Pisząc, należy odpowiednio używać atrybutów tekstu, np. używać italiki \textit{} dla terminów obcojęzycznych, czy wyróżnienia \emph{} dla ważniejszych pojęć czy nazw. Skład nazw poleceń, plików i innym ma być zgodny z formatem podanym w p. 2.2.

Układ dokumentu

Układ dokumentu ma być ściśle zgodny z szablonem podanym w pliku o nazwie gjn-projekt-skel.tex, dostępnym na stronie WWW. Oczywiście w miarę potrzeb do dokumentu można dodać odpowiednie pakiety czy parametry. Nie należy jednak modyfikować czy usuwać fragmentów szablonu.

Styl aghdps

W składzie należy wykorzystać dostarczony styl aghdps.tex, który należy włączyć do dokumentu przez \input{aghdps}.STYLU NIE WOLNO ZMIENIAĆ!!!

Styl modyfikuje kilka ustawień związanych z wyglądem dokumentu, takich jak marginesy, czy układ strony.

Poza tym styl dostarcza kilku nowych poleceń (patrz 1), których należy używać, pisząc dokument.

Tablica 1: Polecenia stylu aghdps

polecenie	znaczenie	przykład
\textcmd{}	nazwa polecenia wykonywalnego	ps aux
\textfil{}	nazwa pliku	/etc/passwd
\textkey{}	nazwa klawisza	$enter$
\textman{}	nazwa strony podręcznika uniksowego	bash(1)
\textprg{}	nazwa programu, aplikacji, pakietu	Xfig
\textmen{}	opcja w menu programów	File/Open

Dodatkowo, do składu tekstu, który pojawia się na ekranie, np. komunikaty programów, lub który się wpisuje, np. odpowiedzi na komunikaty, a także do składu, poleceń języka, instrukcji należy używać polecenia \verb|tekst|, ew. środowiska verbatim.

Uwagi techniczne

Pliki z grafiką (rysunkami) mają być dostarczane w dwóch formatach: EPS i PDF. Ten pierwszy można uzyskać przez bezpośrednie zapisanie z programy graficznego, np. Xfig, Dia, Inkscape, CorelDraw. Ten drugi można uzyskać, przez konwersję EPS przy pomocy programu epstopdf (ghostscript), lub convert (ImageMagick). Grafikę należy składać z wykorzystaniem pakietu graphicx i dołączać do dokumentu jak poniżej (bez rozszerzenia!).

\begin{figure}[htbp]
  \begin{center}
    \includegraphics[scale=costam]{rysunek}
    \caption{Podpis rysunku}
    \label{fig:etykieta}
  \end{center}
\end{figure}

Jeżeli dokument wykorzystuje rysunki wykonane przez autorów w programach typu Xfig, Dia, Inkscape, CorelDraw, czy innych to należy dostarczyć spakowane pliki źródłowe z tych programów.

Poza tym:

• odnośniki URL należy pisać przy pomocy polecenia \url{odnośnik},
• kod programów powinien być umieszczany w środowsku verbatim, lub składany przy pomocy dodatkowego pakietu listings, dostępnego na serwerach FTP związanych z L^ATEXem, lub z serwera CTAN (http://www.ctan.org),
• fragmenty zawierające dłuższe, kompletne fragmenty kodu programów należy umieszczać w osobnych plikach i włączać przez \input{plik},
• przykłady konwersacji (widok sesji) z programem ma być składana przy pomocy środowiska verbatim,
• jeżeli używa się dodatkowych pakietów L^ATEXa, nie występujących w standardowej dystrybucji, należy je dołączyć w postaci osobnego, oryginalnego pliku do wersji elektronicznej dokumentacji.

Wersja drukowana

Należy koniecznie dostarczyć dokumentację w wersji drukowanej na papierze A4, wydrukowanej dwustronnie.

Jeżeli objętość dokumentacji nie przekracza ok. 20 kartek należy ją tylko zszyć, lub spiąć spinaczem (nie bindować) i dostarczyć w przezroczystej koszulce. Jeżeli objętość jest większa, można bindować.

Dokumentację należy dostarczyć do rąk własnych prowadzącego.

Wersja elektroniczna

Oprócz wersji drukowanej, trzeba koniecznie dostarczyć wersję elektroniczną, która zawiera wszystkie pliki źródłowe, czyli tex,eps,pdf, ew. inne.

Finalną wersję elektroniczną projektu należy dostarczyć w formacie PDF, najlepiej wygenerowaną przez pdflatex. Można też użyć konwersji z PS do PDF.

UWAGA: Nazwa pliku ma zawierać:

• Skrót nazwy przedmiotu,
• Rok,
• Skrócony temat (skrót należy wybrać arbitralnie, ale jednoznacznie).

Przykład dla projektu z Metod Inżynierii Wiedzy, w roku 2006, temat: ,,graficzny edytor diagramów ARD'':

MIW06-Edytor_ARD.tex

W przypadku własnoręcznego tworzenia rysunków w programach typu XFig, Dia, Inkscape, czy Gimp, należy koniecznie dostarczyć pliki źródłowe tych programów: fig,xml,xcf.

Finalna wersja elektroniczna ma być dostarczona do rąk własnych prowadzącego.

Odbiór dokumentacji

Przy oddawaniu dokumentacji należy dostarczyć:

1. ją do rąk własnych prowadzącego,
2. w postaci drukowanej, kartki mają być zszyte (a nie spięte spinaczem!) i włożone do przeźroczystej koszulki,
3. w postaci elektronicznej na płycie CD,
4. płyta ma być koniecznie opisana: Projekt MIW rok, temat, autorzy i dostarczona w papierowej kopercie, która ma być na stałe przyklejona na ostatniej stronie dokumentacji, po bibliografii
5. poprzednie wersje z komentarzami, poprawkami (tylko do wglądu) w celu porównania postępów.

Jeżeli dokumentacja ma braki formalne (np. zły skład) lub błędy językowe, zostanie zwrócona do poprawy.

Nie poprawienie dokumentacji może spowodować obniżenie oceny.

Wykonanie poprawnej dokumentacji (zgodnej z podanymi regułami) może zmienić ocenę z przedmiotu.

About this document ...

Wymagania dotyczące składu dokumentacji projektów w L^ATEXu

This document was generated using the LaTeX2HTML translator Version 2002-2-1 (1.70)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -split 0 GJN-projekt-wymagania.tex

The translation was initiated by Grzegorz J. Nalepa on 2007-03-14