included"> ]> Упутство за ГТК-док 1.24.1 Корисничко упутство за програмере са упутствима за употребу ГТК-дока. Крис Лајтл
chris@wilddev.net
Ден Мует
d-mueth@uchicago.edu
Штефан Зауер (Кост)
ensonic@users.sf.net
Пројекат ГТК-док
gtk-doc-list@gnome.org
 2000, 2005 Ден Мует и Крис Лајтл 2007-2019 Штефан Зауер (Кост) Дозвољено је умножавање, дељење и/или мењање овог документа под условима ГНУ-ове лиценце за слободну документацију, верзије 1.1 или било које новије верзије коју објави Задужбина слободног софтвера без непроменљивих одељака, без текста на насловној страни и без текста на задњој страни. Примерак лиценце је укључен. Многи називи које компаније користе да би разликовале своје производе и услуге су заштићени као робне марке. На местима где се ти називи појављују у било којој Гномовој документацији, а чланови Гномовог пројекта документације су обавештени о тим робним маркама, називи су штампани великим словима или са почетним великим словом. 1.33.0 1. окт 2020. mc издање за гтк4 1.32.1 15. авг 2019. ss развојно издање 1.32 15. авг 2019. ss издање са хитном исправком 1.31 5. авг 2019. ss прераде кода и већа покривеност тестовима 1.30 8. мај 2019. ss већа покривеност тестовима 1.29 28. авг 2018. ss исправке грешака 1.28 24. мар 2018. ss исправке грешака 1.27 7. дец 2017. ss фино подешавање преноса на пајтон 1.26 11. авг 2017. ss пренос свих алата са перла/баша на пајтон 1.25 21. март 2016. ss исправке грешака, чишћење тестова 1.24 29. мај 2015. ss исправка грешке 1.23 17. мај 2015. ss исправка грешке 1.22 07. мај 2015. ss исправке грешака, одбацивање застарелих могућности 1.21 17. јул 2014. ss исправке грешака, одбацивање застарелих могућности 1.20 16. фебруар 2014. ss исправке грешака, подршка за маркдаун, побољшања стила 1.19 05. јун 2013. ss исправке грешака 1.18 14. септембар 2011. ss исправке грешака, убрзања, подршка за маркдаун 1.17 26. фебруар 2011. sk хитно ажурирање исправке грешке 1.16 14. јануар 2011. sk исправке грешака, побољшања распореда 1.15 21. мај 2010. sk исправке грешака и регресија 1.14 28. март 2010. sk исправке грешака и побољшања учинка 1.13 18. децембар 2009. sk ажурирање оштећене тар архиве 1.12 18. децембар 2009. sk нове могућности алата и исправке грешака 1.11 16. новембар 2008. mal прелазак на Гномове алатке документације Увод Ово поглавље уводи ГТК-док и даје преглед шта је он и како се користи. Шта је ГТК-док? ГТК-док се користи за документовање Ц кода. Обично се користи за документовање јавног АПИ-ја библиотека, као што су библиотеке засноване на ГЛиб-у, али се такође може користити за документовање кода програма. Како ГТК-док ради? ГТК-док ради тако што чита посебно обликоване блокове коментара постављене унутар изворних датотека ради документовања симбола као што су функције, макрои, структуре, набрајања итд. (иако имајте у виду да ће за већину врста симбола ГТК-док документовати само симболе који су објављени у датотекама заглавља; на пример, неће произвести излаз за статичке функције). ГТК-док такође чита датотеке шаблона где се документација такође може додати. ГТК-Док се састоји од низа програма, од којих сваки обавља различит корак у процесу. Главни кораци су: Писање документације. Аутор попуњава изворне датотеке документацијом за сваку функцију, макро, структуру или унију, итд. Прикупљање података о коду. gtkdoc-scan прегледа датотеке заглавља кода тражећи декларације функција, макроа, набрајања, структура и унија. Прави датотеку <module>-decl-list.txt која садржи списак декларација, смештајући их у одељке према томе у којој се датотеци заглавља налазе. При првом покретању ова датотека се копира у <module>-sections.txt. Аутор може преуредити одељке и редослед декларација унутар њих како би добио коначни жељени поредак. Друга датотека коју генерише је <module>-decl.txt. Ова датотека садржи потпуне декларације које је пронашао прегледач. Ако из неког разлога желите да се неки симболи појаве у документацији, а прегледач не може да пронађе потпуну декларацију или би декларација требало да изгледа другачије, можете поставити ставке сличне онима у <module>-decl.txt у <module>-overrides.txt. gtkdoc-scangobj се такође може користити за динамички упит библиотеци о свим подкласама Г-објекта (GObject) које она извози. Сачуваће податке о положају сваког објекта у хијерархији класа и о свим својствима и сигналима Г-објекта које пружа. gtkdoc-scanobj више не би требало користити. Био је потребан у прошлости када је GObject још увек био GtkObject унутар ГТК-а. Стварање XML-а и HTML-а/PDF-а. gtkdoc-mkdb претвара датотеке шаблона у XML датотеке у xml/ поддиректоријуму. Ако изворни код садржи документацију за симболе, користећи посебне блокове коментара, она се овде стапа. Ако се не користе tmpl датотеке, он само чита документацију из извора и података интроспекције. gtkdoc-mkhtml претвара XML датотеке у HTML датотеке у html/ поддиректоријуму. Исто тако gtkdoc-mkpdf претвара XML датотеке у PDF документ под називом <package>.pdf. Датотеке у xml/ и html/ директоријумима се увек преписују. Никада их не треба директно уређивати. Исправљање унакрсних референци између докумената. Након инсталирања HTML датотека, може се покренути gtkdoc-fixxref ради исправљања унакрсних референци између засебних докумената. На пример, ГТК документација садржи многе унакрсне референце на врсте документоване у ГЛиб (GLib) приручнику. Приликом прављења изворне архиве (tarball) за дистрибуцију, gtkdoc-rebase претвара све спољне везе у веб-везе. Приликом инсталирања дистрибуиране (унапред генерисане) документације, исти програм ће покушати да врати везе на локалне везе (тамо где је та документација инсталирана). Набављање ГТК-Дока Захтеви пајтон 2/3 — главне скрипте су написане у пајтону. xsltproc — XSLT процесор из libxslt-а xmlsoft.org/XSLT/ docbook-xsl — DocBook XSL стилски листови sourceforge.net/projects/docbook/files/docbook-xsl Један од source-highlight, highlight или vim — опционо — користи се за истицање синтаксе у примерима О ГТК-Доку Историјски гледано, ГТК-Док је коришћен за генерисање датотека шаблона из изворног кода. Ове датотеке шаблона су програмери могли користити за унос АПИ документације. Овај приступ је био прилично незгодан јер је захтевао чување генерисаних датотека под контролом верзија. Од верзије ГТК-Док 1.9 постало је могуће поставити све АПИ податке у изворне коментаре, што је подршку за шаблоне учинило застарелом. У верзији 1.26 подршка за шаблоне је уклоњена. (ПОПРАВИМЕ) (аутори, веб странице, дописна листа, лиценца, будући планови, поређење са другим сличним системима.) О овом приручнику (ПОПРАВИМЕ) (коме је намењен, где га можете набавити, лиценца) Подешавање пројекта Ово поглавље описује кораке који су неопходни за интегрисање Гтк-документације (GTK-Doc) у ваш пројекат. Интеграција Гтк-документације у пројекат укључује следеће кораке: Припрема структуре директоријума и стварање потребних датотека подешавања за вашу Гтк-документацију (погледајте Постављање скелета документације). Прилагођавање система изградње за изградњу ваше документације помоћу алата Гтк-документације. Подржано је више система изградње, у овом приручнику описујемо како да интегришете Гтк-документацију са Ауто-алатима (Autotools), Ц-мејком (CMake) и обичним Мејк-датотекама (Makefiles). Додавање датотека специфичних за Гтк-документацију у систем за управљање верзијама и одлучивање о томе које датотеке треба занемарити (погледајте Интеграција са системима за управљање верзијама). Следећи одељци претпостављају да радимо на пројекту под називом meep. Овај пројекат садржи два пакета (или модула), библиотеку под називом libmeep и апликацију за крајњег корисника под називом meeper. Постављање скелета документације Уобичајена конвенција је да се документација постави у фасциклу под називом docs унутар главног директоријума вашег пројекта. Обично разликујемо референтну документацију намењену програмерима и кориснички приручник намењен крајњим корисницима. Опет, конвенција је да постоје посебне фасцикле за оба. Обично референтну документацију стављамо у фасциклу под називом reference, а кориснички приручник у фасциклу под називом help. Према горе наведеној конвенцији, документација за наш пакет libmeep била би постављена у: docs/reference/libmeep. За пакете са само једном библиотеком или апликацијом, документација би се такође могла поставити директно у docs/reference. Није обавезно користити горе наведену конвенцију, али ако изаберете другачију структуру директоријума, морате прилагодити подешавања вашег система изградње како би одговарала вашој структури директоријума. У следећим одељцима претпоставићемо структуру директоријума за наш пројекат meep који користи горе наведене конвенције. Пример структуре директоријума пројекта <emphasis>meep</emphasis> meep/ docs/ reference/ # референтна документација libmeep/ meeper/ help/ # опционо: кориснички приручник meeper/ src/ libmeep/ meeper/ Интеграција са Ауто-алатима (Autotools) Интеграција Гтк-документације у систем изградње заснован на Ауто-алатима захтева следеће кораке: Осигурајте да се gtkdocize покрене једном пре скрипте configure. Ако је присутна скрипта autogen.sh, прилагодите је тако да проверава Гтк-документацију и додајте позив за gtkdocize. Главна сврха програма gtkdocize је да учини gtk-doc.make Мејк-датотеку и gtk-doc.m4 датотеку дефиниције макроа доступним систему изградње, било копирањем или повезивањем у пројекат. Додајте неопходне autoconf макрое у configure.ac да бисте омогућили ГТК-док у вашем систему изградње и омогућили подешавање ГТК-дока путем генерисане configure скрипте. Између осталих, региструје опцију --enable-gtk-doc код configure скрипте. Направите automake скрипту за сваки програм или библиотеку у вашем пројекту. У примеру који се користи у овој документацији, овај корак се односи и на meeper и на libmeep. У следећим одељцима, извршићемо горе наведене кораке обрнутим редоследом. Почињемо са automake скриптама и настављамо до configure.ac и autogen.sh. Затим показујемо како да омогућите Гтк-док у систему изградње и како да изградите документацију. Интеграција са аутомејком Прво копирајте Makefile.am из поддиректоријума examples са gtkdoc-sources у директоријум референтне документације вашег пројекта (нпр. docs/reference/<package>). Локална копија би требало да буде доступна под нпр. /usr/share/doc/gtk-doc-tools/examples/Makefile.am. Ако имате више пакета, поновите ово за сваки од њих. Не заборавите да додате сваки Makefile.am у AC_CONFIG_FILES макро у configure.ac. За docs/reference/libmeep/Makefile.am мораћете да додате унос docs/reference/libmeep/Makefile у AC_CONFIG_FILES. Пример структуре директоријума са <filename>Makefiles.am</filename> meep/ docs/ reference/ # референтна документација libmeep/ Makefile.am meeper/ Makefile.am help/ # опционално: корисничко упутство meeper/ src/ libmeep/ meeper/ Затим треба да прилагодите копиране датотеке Makefile и обезбедите вредности за различите параметре у сваком Makefile.am. Сва подешавања имају коментар изнад који описује њихову сврху и како да их прилагодите. Већина подешавања се користи за достављање додатних опција одговарајућим алатима на које се односе. Сваки алат има променљиву облика (нпр. алат gtkdoc-mkhtml има опцију под називом MKHTML_OPTIONS). Сви алати подржавају за исписивање подржаних опција. Следећи списак објашњава најрелевантније опције. Погледајте пример Makefile.am за додатне опције. се користи за навођење назива пакета који се документује (нпр. meeper или libmeep). се користи за навођење путање изворног директоријума у којем ГТК-док тражи вашу АПИ документацију. Ово ће обично бити DOC_SOURCE_DIR=$(top_srcdir)/src или поддиректоријум тог директоријума. и се користе за зависности. Свака опција узима шаблон датотека (нпр. HFILE_GLOB=$(top_srcdir)/src/*.c). Документација ће бити поново изграђена ако се било која од подударних датотека промени. омогућава навођење додатних датотека заглавља које треба укључити приликом скенирања АПИ документације, а које се не налазе под DOC_SOURCE_DIR (нпр. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h). омогућава навођење датотека заглавља или директоријума које треба занемарити приликом скенирања АПИ документације. Користите основни назив датотеке или директоријума (нпр. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder). омогућава навођење датотека слика које ће бити копиране у html/ директоријум генерисане документације. Ако ваша АПИ документација укључује било какве слике, оне морају бити додате у ову опцију (нпр. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png). омогућава навођење додатних датотека које су укључене у $(DOC_MAIN_SGML_FILE) (нпр. content_files=running.xml building.xml changes-2.0.xml). омогућава навођење датотека у којима се gtk-doc скраћенице као што је #GtkWidget проширују (нпр. expand_content_files=running.xml). Интеграција са autoconf-ом Интеграција са autoconf-ом је врло једноставна и укључује један обавезан корак и додатни опциони (али препоручени) корак. Први корак је додавање GTK_DOC_CHECK макроа у вашу configure.ac скрипту. Ово региструје неколико опција подешавања за омогућавање ГТК-Документације и омогућава вам да поставите подразумеване аргументе за gtkdocize. Уверите се да GTK_DOC_CHECK макро није увучен. Макро мора почети на почетку реда и не би требало да почиње празнином. Други корак је додавање AC_CONFIG_MACRO_DIR(m4) у ваш configure.ac. Ово није обавезно, али помаже gtkdocize-у да аутоматски копира дефиницију макроа (нпр. gtk-doc.m4) која садржи GTK_DOC_CHECK макро у директоријум макроа вашег пројекта. Без овога, макро GTK_DOC_CHECK можда неће бити пронађен и морали бисте експлицитно рећи алату aclocal где да пронађе датотеку дефиниције макроа. Минимална интеграција са autoconf-ом # препоручено: поставите m4 директоријум AC_CONFIG_MACRO_DIR(m4) # опционо: региструјте gtk-doc у configure GTK_DOC_CHECK([1.28]) Горњи пример ради, али ће захтевати да сви програмери имају инсталиран gtk-doc. Бољи начин је да изградња документације буде опциона као што је приказано у следећем примеру: Интеграција са опционом gtk-doc зависношћу m4_ifdef([GTK_DOC_CHECK], [ # препоручено: поставите m4 директоријум AC_CONFIG_MACRO_DIR(m4) # опционо: региструјте gtk-doc у configure GTK_DOC_CHECK([1.28]) ],[ AM_CONDITIONAL([ENABLE_GTK_DOC], false) ]) Први аргумент се користи за проверу издања Гтк-Документације у време подешавања. Други, опциони аргумент користи gtkdocize. Макро GTK_DOC_CHECK такође додаје неколико прекидача подешавања: --with-html-dir=ПУТАЊА : путања до инсталиране документације --enable-gtk-doc : користи gtk-doc за изградњу документације [подразумевано=no] --enable-gtk-doc-html : изгради документацију у html формату [подразумевано=yes] --enable-gtk-doc-pdf : изгради документацију у pdf формату [подразумевано=no] ГТК-Документација је онемогућена по дефолту! Не заборавите да проследите опцију следећем покретању configure скрипте. У супротном се инсталира унапред генерисана документација (што има смисла за кориснике, али не и за програмере). Након што су све измене у configure.ac направљене, ажурирајте configure датотеку. Ово се може урадити поновним покретањем autogen.sh. Интеграција са autogen-ом Већина пројеката ће имати autogen.sh скрипту за подешавање инфраструктуре изградње након што је пројекат преузет из система за контролу верзија (као што су git или svn). ГТК-Документација долази са скриптом званом gtkdocize која се може користити за копирање неопходних датотека потребних Гтк-Документацији у изворни директоријум. Требало би да се покрене пре autoreconf, autoheader, automake или autoconf програма. Покретање gtkdocize-а из autogen.sh gtkdocize || exit 1 Условно покрените gtkdocize из autogen.sh GTKDOCIZE=$(which gtkdocize 2>/dev/null) if test $? -ne 0; then echo "Није пронађена подршка за gtk-doc. Не можете изградити документацију." else $GTKDOCIZE || exit 1 fi Када се покрене gtkdocize, он копира gtk-doc.make у корен вашег пројекта (или било који директоријум наведен опцијом ). gtkdocize проверава вашу configure.ac скрипту за макро GTK_DOC_CHECK. Макро GTK_DOC_CHECK се може користити за прослеђивање додатних аргумената скрипти gtkdocize преко другог параметра у макроу GTK_DOC_CHECK. Алтернативно, додатни аргументи се такође могу проследити програму gtkdocize преко променљиве окружења GTKDOCIZE_FLAGS, или директним навођењем у autogen.sh. Извршавање ГТК-документације из система за изградњу Након претходних корака, време је за покретање изградње. Прво морамо поново покренути autogen.sh. Ако ова скрипта покреће configure уместо вас, тада јој проследите опцију . У супротном, ручно покрените configure са овом опцијом након тога. Прво покретање наредбе make генерише неколико додатних датотека у директоријумима документације. Важне су: <package>.types, <package>-docs.xml (раније .sgml), <package>-sections.txt. Покретање изградње документације ./autogen.sh --enable-gtk-doc make Сада можете усмерити свој веб прегледач на docs/reference/<package>/index.html. Са овим почетним подешавањем видећете само врло једноставан документ. Следеће поглавље ће вас научити како да додате АПИ документацију у свој код путем посебних блокова коментара. Поглавље након тога уводи додатне датотеке и показује како да уредите главни шаблон да бисте додали додатна поглавља и одељке својим датотекама документације. Интеграција са CMake системима за изградњу ГТК-документација сада пружа GtkDocConfig.cmake модул (и одговарајући GtkDocConfigVersion.cmake модул). Ово омогућава наредбу gtk_doc_add_module коју можете поставити у своју CMakeLists.txt датотеку. Следећи пример показује како се користи ова наредба. Пример коришћења ГТК-документације из CMake-а find_package(GtkDoc 1.25 REQUIRED) # Create the doc-libmeep target. gtk_doc_add_module( libmeep ${CMAKE_SOURCE_DIR}/libmeep XML meep-docs.xml LIBRARIES libmeep ) # Build doc-libmeep as part of the default target. Without this, you would # have to explicitly run something like `make doc-libmeep` to build the docs. add_custom_target(documentation ALL DEPENDS doc-libmeep) # Install the docs. (This assumes you're using the GNUInstallDirs CMake module # to set the CMAKE_INSTALL_DOCDIR variable correctly). install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html DESTINATION ${CMAKE_INSTALL_DOCDIR}) Интеграција са обичним make-датотекама или другим системима за изградњу У случају да неко не жели да користи automake, а самим тим ни gtk-doc.mak, мораће да позове gtkdoc алате у исправном редоследу у сопственим make-датотекама (или другим алатима за изградњу). Кораци изградње документације DOC_MODULE=meep // извори су измењени gtkdoc-scan --module=$(DOC_MODULE) <source-dir> gtkdoc-scangobj --module=$(DOC_MODULE) gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<source-dir> // xml датотеке су измењене mkdir html cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html Требаће погледати у Makefile.am и gtk-doc.mak како бисте одабрали потребне додатне опције. Интеграција са системима за управљање верзијама Као опште правило, датотеке које уређујете треба да буду под контролом верзија. За типичне пројекте то су следеће датотеке: <package>.types, <package>-docs.xml (раније .sgml), <package>-sections.txt, Makefile.am. Датотеке у директоријумима xml/ и html/ не би требало да буду под контролом верзија. Исто важи и за било коју од .stamp датотека. Документовање кода ГТК-Док користи коментаре у изворном коду са посебном синтаксом за документацију кода. Такође, он преузима информације о структури вашег пројекта из других извора. У следећем одељку наћи ћете све информације о синтакси коментара. Скенер ГТК-Дока може добро да обради већину Ц заглавља. У случају добијања упозорења од скенера која изгледају као посебан случај, можете наговестити ГТК-Доку да их прескочи. ГТК-Док блок коментара #ifndef __GTK_DOC_IGNORE__ /* код који се не може рашчланити је овде */ #endif Ограничења Имајте на уму да ГТК-Док подржава #ifndef(__GTK_DOC_IGNORE__) али не и #if !defined(__GTK_DOC_IGNORE__) или друге комбинације. Коментари документације Вишередни коментар који почиње са додатним знаком „*“ означава блок документације који ће обрадити алати ГТК-Дока. ГТК-Док блок коментара /** * идентификатор: * документација ... */ „Идентификатор“ је један ред са називом ставке на коју се коментар односи. Синтакса се мало разликује у зависности од ставке. (ДА СЕ УРАДИ: додати табелу која приказује идентификаторе) Блок „документација“ је такође различит за сваку врсту симбола. Врсте симбола који примају параметре, као што су функције или макрои, имају прво опис параметара након чега следи празан ред (само „*“). Затим следи детаљан опис. Сви редови (изван програмских спискова и CDATA одељака) који садрже само „ *“ (размак-звездица) претварају се у преломе пасуса. Ако не желите прелом пасуса, промените то у „ * “ (размак-звездица-размак-размак). Ово је корисно у преформатираном тексту (спискови кода). Приликом документовања кода, опишите два аспекта: Шта је то: Назив класе или функције понекад може бити обмањујући за људе који долазе из другачијег окружења. Шта ради: Реците нешто о уобичајеним употребама. Ставите га у однос са другим АПИ-јем. Једна предност хипертекста над обичним текстом је могућност поседовања веза у документу. Писање исправног означавања за везу може бити заморно. Гтк-Док прискаче у помоћ пружајући неколико корисних скраћеница. Користите function() за упућивање на функције или макрое који примају аргументе. Користите @param за упућивање на параметре. Такође користите ово када упућујете на параметре других функција, који су повезани са оном која се описује. Користите %constant за упућивање на константу, нпр. %G_TRAVERSE_LEAFS. Користите #symbol за упућивање на друге врсте симбола, нпр. структуре и набрајања и макрое који не примају аргументе. Користите #Object::signal за упућивање на Г-објектни сигнал. Користите #Object:property за упућивање на Г-објектно својство. Користите #Struct.field за упућивање на поље унутар структуре и #GObjectClass.foo_bar() за упућивање на виртуелну методу. Ако треба да користите посебне знакове „<“, „>“, „()“, „@“, „%“ или „#“ у вашој документацији а да их Гтк-Док не промени, можете користити ИксМЛ ентитете „&lt;“, „&gt;“, „&lpar;“, „&rpar;“, „&commat;“, „&percnt;“ и „&num;“ респективно или их заштитити контра косом цртом „\“. ДокБук може учинити више од самих веза. Такође се могу имати спискови, примери, заглавља и слике. Од верзије 1.20, пожељан начин је коришћење подскупа основне синтаксе форматирања текста званог Маркдаун. На старијим верзијама Гтк-Дока свака документација која укључује Маркдаун биће исцртана онако како јесте. На пример, ставке списка ће се појавити као редови који почињу цртицом. Иако се маркдаун сада преферира, могу се мешати оба. Једно ограничење овде је да се може користити докбук иксмл унутар маркдауна, али маркдаун унутар докбук иксмла није подржан. У старијим издањима Гтк-Дока, ако вам је потребна подршка за додатно форматирање, морали бисте да омогућите коришћење докбук ИксМЛ ознака унутар док-коментара постављањем (или ) у променљиву MKDB_OPTIONS унутар Makefile.am. Гтк-Док блок коментара који користи Маркдаун /** * identifier: * * documentation paragraph ... * * # Sub Heading # * * ## Second Sub Heading * * # Sub Heading With a Link Anchor # {#heading-two} * * more documentation: * * - list item 1 * * Paragraph inside a list item. * * - list item 2 * * 1. numbered list item * * 2. another numbered list item * * Another paragraph. [A Link to the GNOME Website](http://www.gnome.org/) * * ![an inline image](plot-result.png) * * [A link to the heading anchor above][heading-two] * * A C-language example: * |[<!-- language="C" --> * GtkWidget *label = gtk_label_new ("Gorgeous!"); * ]| */ Више примера о томе које су маркдаун ознаке подржане можете пронаћи у Референцама синтаксе Маркдауна за ГТК документацију. Као што је већ раније поменуто, Гтк-Док је за документовање јавног АПИ-ја. Стога се не може писати документација за статичке симболе. Ипак, добро је коментарисати и те симболе. Ово помаже другим програмерима да разумеју ваш код. Због тога препоручујемо да их коментаришете користећи обичне коментаре (без друге звездице „*“ у првом реду). Ако касније функција треба да постане јавна, све што треба да урадите је да додате још једну звездицу „*“ у блок коментара и уметнете име симбола на право место унутар датотеке одељака. Документовање одељака Сваки одељак документације садржи информације о једној класи или модулу. За увођење компоненте може се написати блок одељка. Кратак опис се такође користи унутар садржаја. Сва @поља су опционална. Блок коментара одељка /** * SECTION:meepapp * @short_description: the application class * @title: Meep application * @section_id: * @see_also: #MeepSettings * @stability: Stable * @include: meep/app.h * @image: application.png * * The application class handles ... */ SECTION:<назив> Назив повезује документацију одељка са одговарајућим делом у датотеци <package>-sections.txt. Овде дати назив треба да се поклапа са ознаком <FILE> у датотеци <package>-sections.txt. @кратак_опис Опис одељка у једном реду, који ће се касније појавити након веза у садржају и на врху странице одељка. @наслов Наслов одељка је подразумевано <назив> из декларације SECTION. Може се преписати пољем @title. @ид_одељка Преписује употребу наслова као идентификатора одељка. За Г-објекте (GObjects) се <title> користи као ид_одељка (section_id), а за остале одељке то је <MODULE>-<title>. @види_такође Списак симбола који су повезани са овим одељком. @стабилност Неформални опис нивоа стабилности који овај АПИ има. Препоручујемо употребу једног од ових термина: Стабилно — Намера стабилног прочеља је да омогући произвољним трећим странама да развијају програме за ова прочеља, да их објављују и да буду сигурни да ће радити на свим мањим издањима производа (након оног у којем је прочеље уведено, и унутар истог главног издања). Чак и код главног издања, очекује се да ће некомпатибилне измене бити ретке и да ће имати јака оправдања. Нестабилно — Нестабилна прочеља су експериментална или прелазна. Обично се користе да би се спољним програмерима омогућио рани приступ новој технологији или технологији која се брзо мења, или да би се пружило привремено решење за проблем за који се предвиђа општије решење. Не дају се никакве тврдње о изворној или бинарној компатибилности између два мања издања. Приватно — Прочеље које се може користити унутар самог Гномовог стека, али које није документовано за крајње кориснике. Такве функције треба користити само на наведене и документоване начине. Унутрашње — Прочеље које је унутрашње за модул и не захтева документацију за крајње кориснике. За функције које нису документоване претпоставља се да су унутрашње. @укључи Датотеке #include које се приказују у сижеу одељка (списак раздвојен зарезима), што преписује општу вредност из датотеке одељка или линије наредби. Ова ставка је опциона. @слика Слика која се приказује на врху референтне странице за овај одељак. Ово ће често бити нека врста дијаграма који илуструје визуелни изглед класе или дијаграм њеног односа са другим класама. Ова ставка је опциона. Да бисте избегли непотребно поновно превођење након измена у документацији, ставите документацију одељака у Ц изворни код где год је то могуће. Документовање симбола Сваки симбол (функција, макро, структура, набрајање, сигнал и својство) је документован у засебном блоку. Блок је најбоље поставити близу дефиниције симбола како би се лако одржавали усклађеним. Тако се функције обично документују у Ц изворном коду, а макрои, структуре и набрајања у датотеци заглавља. Опште ознаке Можете додати податке о верзионисању свим елементима документације како бисте назначили када је АПИ уведен или када је постао застарео. Ознаке верзионисања Од: Опис од ког издања кода је АПИ доступан. Застарело: Пасус који означава да ову функцију више не би требало користити. Опис би требало да упути читаоца на нови АПИ. Такође можете додати податке о стабилности свим елементима документације како бисте назначили да ли је стабилност АПИ-ја загарантована за њих за сва будућа мања издања пројекта. Подразумевани ниво стабилности за све елементе документације може се поставити прослеђивањем аргумента програму gtkdoc-mkdb са једном од вредности испод. Ознаке стабилности Стабилност: Стабилно Означите елемент као стабилан. Ово је за јавне АПИ-је за које је загарантовано да ће остати стабилни за сва будућа мања издања пројекта. Стабилност: Нестабилно Означите елемент као нестабилан. Ово је за јавне АПИ-је који су објављени као преглед пре него што буду стабилизовани. Стабилност: Приватно Означите елемент као приватан. Ово је за прочеља која могу користити тесно повезани модули, али не и произвољна трећа лица. Опште ознаке /** * foo_get_bar: * @foo: неки foo * * Добавља @foo-ов bar. * * Враћа: @foo-ов bar * * Од: 2.6 * Застарело: 2.12: Користите foo_baz_get_bar() уместо овога. */ Bar * foo_get_bar(Foo *foo) { ... Забелешке Блокови документације могу да садрже ознаке забелешки. Ове ознаке ће бити исцртане са облачићима који описују њихово значење. Ознаке користи Гобјект испитивање (GObject Introspection) за стварање везивања за језике. Детаљан списак подржаних ознака можете пронаћи у документацији Гобјект испитивања. Забелешке /** * foo_get_bar: (annotation) * @foo: (annotation): some foo * * Retrieves @foo's bar. * * Returns: (annotation): @foo's bar */ ... /** * foo_set_bar_using_the_frobnicator: (annotation) (another annotation) * (and another annotation) * @foo: (annotation) (another annotation): some foo * * Sets bar on @foo. */ Блок коментара функције Запамтите да: Документујте да ли враћени објекти, спискови, ниске, итд, треба да буду ослобођени/отпуштени. Документујте да ли параметри могу бити NULL, и шта се дешава ако јесу. Спомените занимљиве предуслове и постуслове где је то прикладно. Гтк-док претпоставља да су сви симболи (макрои, функције) који почињу са „_“ приватни. Они се третирају као статичке функције. Блок коментара функције /** * function_name: * @par1: description of parameter 1. These can extend over more than * one line. * @par2: description of parameter 2 * @...: a %NULL-terminated list of bars * * The function description goes here. You can use @par1 to refer to parameters * so that they are highlighted in the output. You can also use %constant * for constants, function_name2() for functions and #GtkWidget for links to * other declarations (which may be documented elsewhere). * * Returns: an integer. * * Since: 2.2 * Deprecated: 2.18: Use other_function() instead. */ Ознаке функције Враћа: Пасус који описује враћени резултат. @...: У случају да функција има варијабилне аргументе, треба да користите ову ознаку (@Varargs: такође ради из историјских разлога). Блок коментара својства Блок коментара својства /** * SomeWidget:some-property: * * Here you can document a property. */ g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...); Блок коментара сигнала Запамтите да: Документујте када се сигнал емитује и да ли се емитује пре или после других сигнала. Документујте шта би апликација могла да уради у руковаоцу сигналом. Блок коментара сигнала /** * FooWidget::foobarized: * @widget: the widget that received the signal * @foo: some foo * @bar: some bar * * The ::foobarized signal is emitted each time someone tries to foobarize @widget. */ foo_signals[FOOBARIZED] = g_signal_new ("foobarized", ... Блок примедбе структуре Блок примедбе структуре /** * FooWidget: * @bar: неки #gboolean * * Ово је најбољи елемент, икада. */ typedef struct _FooWidget { GtkWidget parent_instance; gboolean bar; } FooWidget; Користите /*< private >*/ пре приватних поља структуре која желите да сакријете. Користите /*< public >*/ за обрнуто понашање. Ако је прво поље „g_iface“, „parent_instance“ или „parent_class“, оно ће се сматрати приватним аутоматски и не мора се наводити у блоку примедбе. Блокови примедби структуре се такође могу користити за Г-објекте и Г-класе објеката. Обично је добра идеја додати блок примедбе за класу, ако има в-методе (јер се тако могу документовати). За сам Г-објекат може се користити документација повезаног одељка, а посебан блок за саму инстанцу структуре би био користан ако инстанца има јавна поља. Једна мана овде је што ово ствара два уноса индекса истог назива (структура и одељак). Блок примедбе набрајања Блок примедбе набрајања /** * Something: * @SOMETHING_FOO: нешто foo * @SOMETHING_BAR: нешто bar * * Вредности набрајања које се користе за ствар, да би се навела ствар. */ typedef enum { SOMETHING_FOO, SOMETHING_BAR, /*< private >*/ SOMETHING_COUNT } Something; Користите /*< private >*/ пре приватних вредности набрајања које желите да сакријете. Користите /*< public >*/ за обрнуто понашање. Унутрашња документација програма Можете документовати програме и њихово прочеље линије наредби користећи унутрашњу документацију. Ознаке ПРОГРАМ Дефинише почетак документације програма. @short_description: Дефинише кратак опис програма. (Опционо) @synopsis: Дефинише аргументе, или списак аргумената које програм може да прими. (Опционо) @see_also: Одељак „Такође погледајте“ страница упутства. (Опционо) @arg: Аргумент(и) прослеђени програму и њихов опис. (Опционо) Опис: Дужи опис програма. Враћа: Наведите вредност(и) коју програм враћа. (Опционо) Пример документације програма. Блок документације програма /** * PROGRAM:test-program * @short_description: Тест програм * @synopsis: test-program [*ОПЦИЈЕ*...] --arg1 *арг* *ДАТОТЕКА* * @see_also: test(1) * @--arg1 *арг*: постави арг1 на *арг* * @--arg2 *арг*: постави арг2 на *арг* * @-v, --version: Штампај број издања * @-h, --help: Штампај поруку помоћи * * Дуги опис програма. * * Returns: Нула у случају успеха, не-нула у случају неуспеха */ int main(int argc, char *argv[]) { return 0; } Корисне ДокБук ознаке Ево неких ДокБук ознака које су најкорисније приликом документовања кода. За повезивање са другим одељком у ГТК документацији: <link linkend="glib-Hash-Tables">Хеш табеле</link> „linkend“ је СГМЛ/ИксМЛ ид на горњој ставци странице са којом желите да се повежете. За већину страница ово је тренутно део („gtk“, „gdk“, „glib“), а затим наслов странице („Хеш табеле“). За елементе то је само назив класе. Размаци и доње црте се претварају у „-“ да би били у складу са СГМЛ/ИксМЛ-ом. За упућивање на спољну функцију, нпр. стандардну Ц функцију: <function>...</function> За укључивање примера кода: <example> <title>Коришћење ГХешТабеле.</title> <programlisting language="C"> ... </programlisting> </example> или можда ово, за веома кратке делове кода којима није потребан наслов: <informalexample> <programlisting language="C"> ... </programlisting> </informalexample> У оба случаја, атрибут језика је опционо и користи се као савет покретачу за истицање синтаксе (pygments за хтмл излаз). За ово друго ГТК-Док такође подржава скраћеницу: |[<!-- language="C" --> ... ]| За укључивање спискова са набрајањем: <itemizedlist> <listitem> <para> ... </para> </listitem> <listitem> <para> ... </para> </listitem> </itemizedlist> За укључивање напомене која се издваја из текста: <note> <para> Обавезно ослободите податке након употребе. </para> </note> За упућивање на врсту: <type>unsigned char</type> За упућивање на спољну структуру (не ону описану у ГТК документацији): <structname>XFontStruct</structname> За упућивање на поље структуре: <structfield>len</structfield> За упућивање на назив класе, могли бисмо евентуално користити: <classname>GtkWidget</classname> али ћете вероватно користити #GtkWidget уместо тога (за аутоматско прављење везе ка GtkWidget страници — погледајте скраћенице). За истицање текста: <emphasis>Ово је важно</emphasis> За називе датотека користите: <filename>/home/user/documents</filename> За упућивање на тастере користите: <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo> Попуњавање додатних датотека Постоји неколико додатних датотека које треба одржавати заједно са напоменама у изворном коду: <package>.types, <package>-docs.xml (раније .sgml), <package>-sections.txt. Уређивање датотеке врста Ако ваша библиотека или програм укључује GObjects, желите да њихови сигнали, аргументи/параметри и положај у хијерархији буду приказани у документацији. Све што треба да урадите јесте да наведете xxx_get_type функције заједно са њиховим укључивањем унутар <package>.types датотеке. Пример <package>.types датотеке #include <gtk/gtk.h> gtk_accel_label_get_type gtk_adjustment_get_type gtk_alignment_get_type gtk_arrow_get_type Од ГТК-Дока 1.8 gtkdoc-scan може направити овај списак за вас. Само додајте „--rebuild-types“ у SCAN_OPTIONS у Makefile.am. Ако користите овај приступ, не би требало да дистрибуирате датотеку врста нити да је држите под управљањем верзијама. Уређивање главног документа GTK-Doc производи документацију у DocBook SGML/XML формату. Приликом обраде унутрашњих коментара изворног кода, GTK-Doc алати генеришу једну страницу документације по класи или модулу као засебну датотеку. Главни документ их укључује и поставља у одређени редослед. Иако GTK-Doc прави шаблон главног документа за вас, каснија покретања га неће поново мењати. То значи да можете слободно структурирати документацију. То укључује груписање страница и додавање додатних страница. GTK-Doc сада има пакет за тестирање, где се такође главни документ поново прави из почетка. Добра је идеја с времена на време погледати ово како бисте видели да ли су тамо уведене неке нове корисне ствари. Не правите водиче као посебне документе. Само пишите додатна поглавља. Предност директног уграђивања водича за вашу библиотеку у API документацију је та што је лако повезати водич са документацијом симбола. Осим тога, веће су шансе да ће водич бити ажуриран заједно са библиотеком. Дакле, шта су ствари које треба променити унутар главног документа? За почетак, то је само мало. Тамо постоје неки чувари места (текст у квадратним заградама) о којима треба да се побринете. Заглавље главног документа <bookinfo> <title>Референтни приручник за MODULENAME</title> <releaseinfo> за MODULENAME [VERSION] Најновије издање ове документације можете наћи на мрежи на <ulink role="online-location" url="http://[SERVER]/MODULENAME/index.html">http://[SERVER]/MODULENAME/</ulink>. </releaseinfo> </bookinfo> <chapter> <title>[Овде уметните наслов]</title> Поред тога, неколико елемената опција је направљено у облику коментара. Можете их прегледати и омогућити их како желите. Опциони део у главном документу <!-- омогућите ово када користите забелешке Гобјектног испитивања <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> --> На крају, потребно је да додате нови одељак кад год га уведете. Алат gtkdoc-check ће вас подсетити на новогенерисане xml датотеке које још нису укључене у документацију. Укључивање генерисаних одељака <chapter> <title>my library</title> <xi:include href="xml/object.xml"/> ... Уређивање датотеке одељака Датотека одељака се користи за организовање излаза документације коју генерише GTK-Doc. Овде се наводи који симбол припада ком модулу или класи и контролише се видљивост (јавна или приватна). Датотека одељака је обична текстуална датотека са ознакама које разграничавају одељке. Празни редови се занемарују, а редови који почињу са „#“ се третирају као коментари. Иако ознаке чине да датотека изгледа као xml, она то није. Молимо вас да не затварате ознаке као што је <SUBSECTION>. Укључивање генерисаних одељака <INCLUDE>libmeep/meep.h</INCLUDE> <SECTION> <FILE>meepapp</FILE> <TITLE>MeepApp</TITLE> MeepApp <SUBSECTION Standard> MEEP_APP ... MeepAppClass meep_app_get_type </SECTION> Ознака <FILE> ... </FILE> се користи за навођење назива датотеке, без икаквог суфикса. На пример, коришћење „<FILE>gnome-config</FILE>“ ће довести до тога да декларације одељака буду исписане у датотеци шаблона tmpl/gnome-config.sgml, која ће бити претворена у DocBook XML датотеку xml/gnome-config.sgml или DocBook XML датотеку xml/gnome-config.xml. (Назив HTML датотеке се заснива на називу модула и наслову одељка, или за GObjects се заснива на називу класе GObjects претвореном у мала слова). Ознака <TITLE> ... </TITLE> се користи за навођење наслова одељка. Корисна је само пре него што се шаблони (ако се користе) иницијално направе, пошто наслов постављен у датотеци шаблона преписује овај. Такође, ако се користи коментар SECTION у изворима, ово је застарело. Можете груписати ставке у одељку коришћењем ознаке <SUBSECTION>. Тренутно она исписује празну линију између пододељака у одељку сижеа. Такође можете користити <SUBSECTION Standard> за стандардне GObject декларације (нпр. функције као што је g_object_get_type и макрое као што су G_OBJECT(), G_IS_OBJECT() итд.). Тренутно су оне изостављене из документације. Такође можете користити <SUBSECTION Private> за приватне декларације које неће бити исписане (то је згодан начин да избегнете поруке упозорења о некоришћеним декларацијама). Ако ваша библиотека садржи приватне типове за које не желите да се појаве у хијерархији објеката и списку примењених или потребних прочеља, додајте их у пододељак Private. Да ли ћете поставити GObject и GObjectClass налик структурама у јавни или Standard одељак зависи од тога да ли имају јавне уносе (променљиве, виртуелне методе). Такође можете користити <INCLUDE> ... </INCLUDE> да наведете #include датотеке које су приказане у одељцима сижеа. Садржи списак #include датотека раздвојених зарезом, без угаоних заграда. Ако га поставите изван било ког одељка, он дејствује на све одељке до краја датотеке. Ако га поставите унутар одељка, примењује се само на тај одељак. Управљање резултатом Покретање ГТК-дока ствара датотеке извештаја унутар директоријума документације. Створене датотеке се зову: <package>-undocumented.txt, <package>-undeclared.txt и <package>-unused.txt. Све су то обичне текстуалне датотеке које се могу лако прегледати и накнадно обрадити. Датотека <package>-undocumented.txt почиње са сажетком покривености документације. Испод су два одељка раздвојена празним линијама. Први одељак набраја недокументоване или непотпуне симболе. Други одељак чини исто за документацију одељака. Непотпуни уноси су они који имају документацију, али где је нпр. додат нови параметар. Датотека <package>-undeclared.txt набраја симболе наведене у <package>-sections.txt али који нису пронађени у изворима. Проверите да ли су уклоњени или им је назив погрешно написан. Датотека <package>-unused.txt набраја називе симбола за које је прегледач ГТК-дока пронашао документацију, али не зна где да је постави. То значи да симбол још увек није додат у датотеку <package>-sections.txt. Омогућите или додајте линију у Makefile.am. Ако је инсталиран барем ГТК-док 1.9, ово ће покренути провере исправности током покретања make check. Може се погледати и у датотеке које је створио прегледач изворног кода: <package>-decl-list.txt и <package>-decl.txt. Прва се може упоредити са датотеком одељака ако се она ручно одржава. Друга набраја све декларације из заглавља. Ако симбол недостаје, може се проверити да ли га ова датотека садржи. Ако је пројекат заснован на Гобјекту, може се погледати и у датотеке које је створио прегледач објеката: <package>.args.txt, <package>.hierarchy.txt, <package>.interfaces.txt, <package>.prerequisites.txt и <package>.signals.txt. Ако у било којој од њих недостају симболи, можете затражити од ГТК-дока да задржи међу-датотеку прегледача за даљу анализу, тако што ћете га покренути као GTK_DOC_KEEP_INTERMEDIATE=1 make. Осавремењивање документације ГТК-док постоји већ неко време. У овом одељку набрајамо нове могућности заједно са издањем од ког су доступне. ГТК-док 1.9 Када се користи иксМЛ уместо СГМЛ-а, главни документ се заправо може именовати <package>-docs.xml. Ово издање подржава у Makefile.am. Када је ово омогућено, <package>-sections.txt се самостално ствара и може се уклонити из система за управљање верзијама. Ово лепо ради само за пројекте који имају врло правилну структуру (нпр. сваки пар .{c,h} ће створити нови одељак). Ако се пројекат организује приближно томе, освежавање ручно одржаване датотеке одељака може бити једноставно као покретање meld <package>-decl-list.txt <package>-sections.txt. Издање 1.8 је већ увело синтаксу за документовање одељака у изворима уместо у засебним датотекама под tmpl. Ово издање додаје опције за пребацивање целог модула документације тако да уопште не користи додатни корак изградње „tmpl“, коришћењем у configure.ac. Ако немате tmpl унешен у ваш систем за управљање верзијама и још нисте пребацили, само додајте заставицу у configure.ac и готови сте. ГТК-док 1.10 Ово издање подржава у Makefile.am. Када је ово омогућено, <package>.types се самостално ствара и може се уклонити из система за управљање верзијама. Када користите ову могућност, важно је такође подесити IGNORE_HFILES у Makefile.am за код који се гради условно. ГТК-док 1.16 Ово издање укључује нови алат под називом gtkdoc-check. Овај алат може да покрене скуп провера исправности ваше документације. Омогућава се додавањем ових линија на крај датотеке Makefile.am. Омогући gtkdoc-check if ENABLE_GTK_DOC TESTS_ENVIRONMENT = \ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir) TESTS = $(GTKDOC_CHECK) endif ГТК-Док 1.20 Издање 1.18 је донело почетну подршку за маркдаун. Коришћење маркдауна у напоменама кода је мање нападно од писања docbook xml-а. Ово издање значајно побољшава ово и додаје много више стилова. Одељак који објашњава синтаксу напомена садржи све детаље. ГТК-Док 1.25 Датотеке управљања градњом (makefiles) испоручене уз ово издање стварају датотеку ставки у xml/gtkdocentities.ent, која садржи ставке за нпр. package_name и package_version. Ово можете користити нпр. у главној xml датотеци како бисте избегли ручно уписивање броја издања. Испод је пример који показује како се датотека ставки укључује у главни шаблон и како се ставке користе. Ставке се такође могу користити у свим створеним датотекама, ГТК-Док ће користити исто xml заглавље у створеним xml датотекама. Коришћење унапред створених ставки <?xml version="1.0"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'"> <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent"> %gtkdocentities; ]> <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> <bookinfo> <title>&package_name; Reference Manual</title> <releaseinfo> for &package_string;. The latest version of this documentation can be found on-line at <ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>. </releaseinfo> </bookinfo> Документовање других прочеља До сада смо користили ГТК-Док за документовање АПИ-ја кода. Следећи одељци садржи предлоге како се алати могу користити и за документовање других прочеља. Опције линије наредби и man странице Како се могу стварати man странице и за docbook refentry, чини се као добра идеја користити га у ту сврху. На тај начин је прочеље део референце и man страница се добија бесплатно. Документовање алата Направите једну refentry датотеку по алату. Пратећи наш пример назвали бисмо је meep/docs/reference/meeper/meep.xml. За xml ознаке које треба користити можете погледати створену датотеку у xml пододељку као и примере нпр. у glib-у. Додавање додатне провере подешавања Додатне провере подешавања AC_ARG_ENABLE(man, [AC_HELP_STRING([--enable-man], [regenerate man pages from Docbook [default=no]])],enable_man=yes, enable_man=no) AC_PATH_PROG([XSLTPROC], [xsltproc]) AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno) Додавање додатних правила датотеке управљања градњом Додатне провере подешавања man_MANS = \ meeper.1 if ENABLE_GTK_DOC if ENABLE_MAN %.1 : %.xml @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $< endif endif BUILT_EXTRA_DIST = $(man_MANS) EXTRA_DIST += meep.xml Д-сабирничка прочеља (ПОПРАВИМЕ: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus) Често постављана питања Питање Одговори Нема хијерархије разреда. Функција објеката xxx_get_type() није унета у датотеку <package>.types. И даље нема хијерархије разреда. Недостајуће или погрешно именовање у датотеци <package>-sections.txt (погледајте објашњење). Проклетство, и даље немам хијерархију разреда. Да ли је име објекта (име примерка структуре, нпр. GtkWidget) део нормалног одељка (не стављајте ово у Стандардне или Приватне пододељке). Нема индекса симбола. Да ли <package>-docs.{xml,sgml} садржи индекс који xi:include-ује генерисани индекс? Симболи нису повезани са својим одељком документације. Да ли коментар документације користи исправно означавање (додато #,% или ())? Проверите да ли gtkdoc-fixxref упозорава на нерешиве унакрсне референце (xrefs). Нови разред се не појављује у документацији. Да ли је нова страница xi:included из <package>-docs.{xml,sgml}. Нови симбол се не појављује у документацији. Да ли је коментар документације правилно обликован. Проверите да ли има правописних грешака на почетку коментара. Проверите да ли gtkdoc-fixxref упозорава на нерешиве унакрсне референце (xrefs). Проверите да ли је симбол исправно наведен у <package>-sections.txt у јавном пододељку. Врста недостаје у хијерархији разреда. Ако је врста наведена у <package>.hierarchy али не и у xml/tree_index.sgml, онда двапут проверите да ли је врста исправно постављена у <package>-sections.txt. Ако примерак врсте (нпр. GtkWidget) није наведен или је случајно означен као приватан, неће бити приказан. Добијам foldoc везе за све gobject забелешке. Проверите да ли је xml/annotation-glossary.xml xi:included из <package>-docs.{xml,sgml}. Параметар је описан у блоку коментара изворног кода али не постоји Проверите да ли прототип у заглављу има другачије називе параметара него у извору. више „ID-ова“ за везу ограничења: XYZ Симбол XYZ се појављује два пута у датотеци <package>-sections.txt. Елемент „typename“ у именском простору „“ је наишао у пасусу (para), али се ниједан шаблон не подудара. Алати повезани са gtk-doc-ом GtkDocPlugin — Trac GTK-Doc прикључак за интеграцију, који додаје API документацију на trac веб сајт и интегрише се са trac претрагом. Gtkdoc-depscan — алат (део gtk-doc-а) за проверу коришћеног API-ја у односу на ознаке „since“ у API-ју како би се одредило најмање потребно издање. Издање 1.1, март 2000. 2000Free Software Foundation, Inc.
Free Software Foundation, Inc. 51 Franklin Street, Suite 330, Boston, MA 02110-1301 USA
Свакоме је дозвољено да умножава и расподељује дословне примерке овог документа лиценце, али његово мењање није дозвољено. ГНУ-ова Лиценца за слободну документацију 0. ПРЕАМБУЛА The purpose of this License is to make a manual, textbook, or other written document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of copyleft, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. Ову лиценцу смо осмислили како бисмо је користили за упутства за слободан софтвер, јер је слободном софтверу потребна слободна документација: слободан програм треба да иде уз упутства која пружају исте слободе као и сам софтвер. Али ова лиценца није ограничена на упутства за софтвер; може се користити за било који текстуални рад, без обзира на предметну материју или на то да ли је објављен као штампана књига. Ову лиценцу препоручујемо првенствено за радове чија је сврха подучавање или референца. 1. ПРИМЕЊИВОСТ И ДЕФИНИЦИЈЕ This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The Document, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as you. A Modified Version of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A Secondary Section is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The Invariant Sections are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. The Cover Texts are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Transparent copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not Transparent is called Opaque. Примери погодних формата за провидне примерке укључују обичан ASCII без означавања, Texinfo улазни формат, LaTeX улазни формат, SGML или XML који користе јавно доступан DTD, и једноставан HTML усклађен са стандардима дизајниран за људску измену. Непрозирни формати укључују PostScript, PDF, власничке формате који се могу читати и уређивати само помоћу власничких процесора текста, SGML или XML за које DTD и/или алати за обраду нису опште доступни, и машински генерисан HTML који производе неки процесори текста само за потребе излаза. The Title Page means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, Title Page means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. 2. ДОСЛОВНО УМНОЖАВАЊЕ You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. Такође можете позајмљивати примерке, под истим горе наведеним условима, и можете јавно приказивати примерке. 3. УМНОЖАВАЊЕ У ВЕЋЕМ БРОЈУ If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. Ако су захтевани текстови за било који омот превише обимни да би стали читко, треба да ставите прве наведене (колико год разумно стане) на сам омот, а остатак наставите на суседним страницама. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. ИЗМЕНЕ You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: А Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. Б List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five). C State on the Title Page the name of the publisher of the Modified Version, as the publisher. Н Preserve all the copyright notices of the Document. E Додајте одговарајућу напомену о ауторским правима за ваше измене поред осталих напомена о ауторским правима. F Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. и Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. H Укључите неизмењен примерак ове лиценце. I Preserve the section entitled History, and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled History in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the History section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K In any section entitled Acknowledgements or Dedications, preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. ц Delete any section entitled Endorsements. Such a section may not be included in the Modified Version. Н Do not retitle any existing section as Endorsements or to conflict in title with any Invariant Section. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section entitled Endorsements, provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version . 5. КОМБИНОВАЊЕ ДОКУМЕНАТА You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections entitled History in the various original documents, forming one section entitled History; likewise combine any sections entitled Acknowledgements, and any sections entitled Dedications. You must delete all sections entitled Endorsements. 6. ЗБИРКЕ ДОКУМЕНАТА You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. Можете издвојити појединачни документ из такве збирке и дистрибуисати га појединачно под овом лиценцом, под условом да уметнете примерак ове лиценце у издвојени документ и да се у свим осталим погледима придржавате ове лиценце у вези са дословним умножавањем тог документа. 7. СПАЈАЊЕ СА НЕЗАВИСНИМ РАДОВИМА A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an aggregate, and this License does not apply to the other self-contained works thus compiled with the Document , on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate. 8. ПРЕВОД Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail. 9. ПРЕСТАНАК ВАЖЕЊА You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 10. БУДУЋЕ РЕВИЗИЈЕ ОВЕ ЛИЦЕНЦЕ The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License or any later version applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. Додатак Да бисте користили ову лиценцу у документу који сте написали, укључите примерак лиценце у документ и ставите следећа обавештења о ауторским правима и лиценци одмах након насловне стране:
Ауторска права ГОДИНА ВАШЕ ИМЕ. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled GNU Free Documentation License.
If you have no Invariant Sections, write with no Invariant Sections instead of saying which ones are invariant. If you have no Front-Cover Texts, write no Front-Cover Texts instead of Front-Cover Texts being LIST; likewise for Back-Cover Texts. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.