от Курс за ССОК
Всеки проект, рано или късно, се нуждае от документация. В тази лекция ще разгледаме различни технологии и инструменти за документиране в Линукс.
Документация на приложенията
Помощ на командния ред
Дори приложенията с малко на брой опции изискват документация. Най-лесно това може да се направи като се добави кратко описание на различните опции и техните параметри в кода на самата програма. След като това е направено, чрез извикване на програмата с параметър --help текста ще бъде изведен на екрана.
Стандартната C библиотека използва функцията getopt, за обработка на опциите на командния ред. Помощни страници са налични на:
В езика Python по-често се използва модулът optparse:
#!/usr/bin/env python
from optparse import OptionParser
parser = OptionParser()
parser.add_option("-n", "--name", type="string", dest="name", help="Name of person", default="World")
parser.add_option("", "--repeat", type="int", dest="repeat", help="How many times to repeat", default=1)
parser.add_option("", "--print-footer", action="store_true", dest="print_footer", help="Print header text", default=False)
(options,args) = parser.parse_args()
for i in range(0, options.repeat):
print "Hello %s" % options.name
if options.print_footer:
print "Message was printed %d times" % options.repeat
Python автоматично добавя опцията --help:
$ ./hello-world.py --help
usage: hello-world.py [options]
options:
-h, --help show this help message and exit
-n NAME, --name=NAME Name of person
--repeat=REPEAT How many times to repeat
--print-footer Print header text
Описанието на най-често използваните параметри на програмата е задължително на командния ред. За големи програми или такива при които работата зависи не само от един параметър се налага по-подробен текст. Той се предоставя в помощни страници наречени ръководства (от англ. manual pages).
Помощни страници
Страниците с ръководства се създават чрез използване на форматиращи езици. Те представляват текстови файлове (може компресирани), съдържащи текст и команди за неговото изобразяване. Програмите използвани за работа с тези страници включват функции като търсене, навигация между свързани страници(info), предложения по ключови думи и т.н.
Пример:
-
$ man man ще отвори помощната страница за програмата man, чрез програмата man
-
$ zcat /usr/share/man/man1/man.1.gz ще покаже истинското съдържание на файла
Двете най-често използвани програми/формата са info и man:
Други форматиращи езици
В Линукс се използват редица форматиращи езици за създаване на документация. В списъка по-долу са дадени някои от по известните:
- TeX - създаден от Доналд Кнут
- POD - състемата използвана в езика Perl и модулите към него. Виж perlpod.
- DocBook - XML базиран език за форматиране. Използван в книгоиздателството. Виж publican. Четецът на помощни страници в GNOME, Yelp, отваря директно DocBook XML, info и man страници.
Списъкът съвсем не е изчерпателен, т.к. съществуват много формати и програми за конверсия между тях. Ако не сте сигурни за името пробвайте входен_формат2изходен_формат.
Пример:
man2html
docbook2dvi
docbook2html
docbook2man
docbook2pdf
docbook2ps
docbook2rtf
docbook2tex
docbook2texi
docbook2txt
pdf2dsc
pdf2ps
ps2ascii
ps2epsi
ps2frag
ps2pdf
ps2pdf12
ps2pdf13
ps2pdf14
ps2pdfwr
ps2pk
ps2ps
pod2html
pod2latex
pod2man
pod2text
pod2usage
Документация на изходния код
Съществуват различни решения за генериране на структурирана документация от коментарите в изходния код на програмата:
UML
Макар и рядко използвани в проектите с отворен код UML диаграми могат да се създават чрез програмата Umbrello. Разширен списък с инструменти за създаване на UML можете да намерите на:
http://en.wikipedia.org/wiki/List_of_UML_tools
