included"> ]> GTK-Doc нұсқаулығы 1.24.1 Әзірлеушілерге арналған GTK-Doc қолдану нұсқаулары бар пайдаланушы нұсқаулығы. Chris Lyttle
chris@wilddev.net
Dan Mueth
d-mueth@uchicago.edu
Stefan Sauer (Kost)
ensonic@users.sf.net
GTK-Doc жобасы
gtk-doc-list@gnome.org
 2000, 2005 Dan Mueth және Chris Lyttle 2007-2019 Stefan Sauer (Kost) Бұл құжатты Free Software Foundation жариялаған GNU Free Documentation License 1.1 нұсқасы немесе кез келген соңғы нұсқасының шарттарына сәйкес, Тұрақты бөлімдерсіз, Алдыңғы мұқаба мәтіндерсіз және Артқы мұқаба мәтіндерсіз көшіруге, таратуға және/немесе өзгертуге рұқсат етіледі. Лицензияның көшірмесі қоса берілген. Компаниялар өздерінің өнімдері мен қызметтерін ерекшелеу үшін пайдаланатын көптеген атаулар сауда белгілері болып табылады. Мұндай атаулар кез келген GNOME құжаттамасында кездескенде және GNOME құжаттама жобасының мүшелеріне сол сауда белгілері туралы мәлім болса, бұл атаулар БАС ӘРІПТЕРМЕН немесе Бас әріппен басталып жазылған. 1.33.0 1 қазан 2020 mc gtk4 нұсқасы 1.32.1 15 тамыз 2019 ss әзірлеу нұсқасы 1.32 15 тамыз 2019 ss шұғыл түзету шығарылымы 1.31 05 тамыз 2019 ss рефакторинг және көбірек тест қамтуы 1.30 08 мамыр 2019 ss көбірек тест қамтуы 1.29 28 тамыз 2018 ss қателерді түзету 1.28 24 наурыз 2018 ss қателерді түзету 1.27 07 желтоқсан 2017 ss python портын дәл баптау 1.26 11 тамыз 2017 ss барлық саймандарды perl/bash-тан python-ға көшіру 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 қателерді түзету, markdown қолдауы, стильді жақсарту 1.19 05 маусым 2013 ss қателерді түзету 1.18 14 қыркүйек 2011 ss қателерді түзету, жылдамдату, markdown қолдауы 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 бүлінген tarball жаңартуы 1.12 18 желтоқсан 2009 sk сайманның жаңа мүмкіндіктері мен қателерді түзету 1.11 16 қараша 2008 mal GNOME doc-utils миграциясы Кіріспе Бұл тарау GTK-Doc-пен таныстырады және оның не екендігі мен қалай қолданылатыны туралы шолу береді. GTK-Doc дегеніміз не? GTK-Doc C кодын құжаттау үшін пайдаланылады. Ол әдетте GLib негізіндегі кітапханалар сияқты кітапханалардың ашық API-ін құжаттау үшін қолданылады, бірақ оны қолданба кодын құжаттау үшін де пайдалануға болады. GTK-Doc қалай жұмыс істейді? GTK-Doc функциялар, макростар, құрылымдар, тізімдер және т.б. сияқты таңбаларды құжаттау үшін бастапқы файлдар ішіне орналастырылған арнайы пішімделген түсініктеме блоктарын оқу арқылы жұмыс істейді (бірақ таңбалардың көптеген түрлері үшін GTK-Doc тек тақырыптық файлдарда жарияланған таңбаларды ғана құжаттайтынын ескеріңіз; мысалы, ол статикалық функциялар үшін нәтиже бермейді). GTK-Doc сонымен қатар құжаттаманы қосуға болатын үлгі файлдарын да оқиды. GTK-Doc бірнеше бағдарламадан тұрады, олардың әрқайсысы процестің әртүрлі қадамын орындайды. Негізгі қадамдар: Құжаттаманы жазу. Автор бастапқы файлдарды әрбір функция, макрос, құрылымдар немесе біріктірулер және т.б. үшін құжаттамамен толтырады. Код туралы ақпаратты жинау. gtkdoc-scan кодтың тақырыптық файлдарын функциялар, макростар, тізімдер, құрылымдар және біріктірулердің декларацияларын іздеп сканерлейді. Ол декларациялар тізімі бар <module>-decl-list.txt файлын жасайды және оларды қай тақырыптық файлда болғанына байланысты бөлімдерге орналастырады. Бірінші іске қосуда бұл файл <module>-sections.txt файлына көшіріледі. Автор соңғы қалаған реттілікке қол жеткізу үшін бөлімдерді және олардың ішіндегі декларациялар ретін қайта реттей алады. Ол жасайтын екінші файл — <module>-decl.txt. Бұл файлда сканер тапқан толық декларациялар болады. Егер қандай да бір себеппен сканер толық декларацияны таба алмаса немесе декларация басқаша көрінуі тиіс болса және кейбір таңбалардың құжаттарда көрінуін қаласаңыз, <module>-decl.txt файлындағыға ұқсас нысандарды <module>-overrides.txt файлына орналастыруға болады. gtkdoc-scangobj сонымен қатар кітапханадан ол экспорттайтын кез келген GObject ішкі кластары туралы динамикалық түрде сұрау үшін пайдаланылуы мүмкін. Ол әрбір объектінің класс иерархиясындағы орны және ол беретін кез келген GObject қасиеттері мен сигналдары туралы ақпаратты сақтайды. gtkdoc-scanobj бұдан былай пайдаланылмауы керек. Ол бұрын GObject әлі GTK ішінде GtkObject болған кезде қажет болған. XML және HTML/PDF жасау. gtkdoc-mkdb үлгі файлдарын xml/ ішкі бумасындағы XML файлдарына айналдырады. Егер бастапқы кодта арнайы түсініктеме блоктарын пайдаланатын таңбаларға арналған құжаттама болса, ол осында біріктіріледі. Егер tmpl файлдары пайдаланылмаса, ол құжаттарды тек бастапқы кодтар мен интроспекция деректерінен оқиды. gtkdoc-mkhtml XML файлдарын html/ ішкі бумасындағы HTML файлдарына айналдырады. Сол сияқты gtkdoc-mkpdf XML файлдарын <package>.pdf деп аталатын PDF құжатына айналдырады. xml/ және html/ бумаларындағы файлдар әрқашан қайта жазылады. Оларды ешқашан тікелей түзетуге болмайды. Құжаттар арасындағы өзара сілтемелерді түзету. HTML файлдарын орнатқаннан кейін, бөлек құжаттар арасындағы кез келген өзара сілтемелерді түзету үшін gtkdoc-fixxref бағдарламасын іске қосуға болады. Мысалы, GTK құжаттамасында GLib нұсқаулығында құжатталған типтерге көптеген өзара сілтемелер бар. Таратуға арналған бастапқы архивті жасау кезінде gtkdoc-rebase барлық сыртқы сілтемелерді веб-сілтемелерге айналдырады. Таратылатын (алдын ала жасалған) құжаттарды орнатқан кезде дәл сол қолданба сілтемелерді жергілікті сілтемелерге (сол құжаттар орнатылған жерге) қайта айналдыруға тырысады. GTK-Doc алу Талаптар python 2/3 - негізгі скрипттер python тілінде жазылған. xsltproc - libxslt-тен алынған xslt процессоры xmlsoft.org/XSLT/ docbook-xsl - docbook xsl стиль кестелері sourceforge.net/projects/docbook/files/docbook-xsl source-highlight, highlight немесе vim біреуі - міндетті емес - мысалдардың синтаксисін жарықтандыру үшін қолданылады GTK-Doc туралы Тарихи тұрғыдан GTK-Doc бастапқы кодтан үлгі файлдарын жасау үшін қолданылған. Бұл үлгі файлдарын әзірлеушілер API құжаттамасын енгізу үшін пайдалана алатын. Бұл тәсіл өте ыңғайсыз болды, өйткені ол жасалған файлдарды нұсқаларды бақылау жүйесінде сақтауды талап етті. GTK-Doc 1.9 нұсқасынан бастап барлық API ақпаратын бастапқы код түсіндірмелеріне орналастыру мүмкін болды, бұл үлгілерді қолдауды қажетсіз етті. 1.26 нұсқасында үлгілерді қолдау мүлдем алынып тасталды. (ТҮЗЕТУ КЕРЕК) (авторлар, веб-беттер, тарату тізімі, лицензия, болашақ жоспарлар, басқа ұқсас жүйелермен салыстыру.) Бұл нұсқаулық туралы (ТҮЗЕТУ КЕРЕК) (кімге арналған, қайдан алуға болады, лицензия) Жобаны баптау Бұл тарауда GTK-Doc-ты жобаңызға біріктіру үшін қажетті қадамдар сипатталған. GTK-Doc-ты жобаға біріктіру келесі қадамдарды қамтиды: Бума құрылымын дайындау және GTK-Doc құжаттамаңыз үшін қажетті конфигурация файлдарын жасау (Құжаттама қаңқасын баптау қараңыз). GTK-Doc саймандарын пайдаланып құжаттамаңызды құрастыру үшін құрастыру жүйесін реттеу. Бірнеше құрастыру жүйелеріне қолдау көрсетіледі, бұл нұсқаулықта біз GTK-Doc-ты Autotools, CMake және жай Makefiles жүйелерімен қалай біріктіруге болатынын сипаттаймыз. GTK-Doc арнайы файлдарын нұсқаларды бақылау жүйесіне қосу және қай файлдарды елемеу керектігін шешу (Нұсқаларды бақылау жүйелерімен біріктіру қараңыз). Келесі бөлімдерде біз 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-пен біріктіру GTK-Doc-ты autotools-қа негізделген құрастыру жүйесіне біріктіру келесі қадамдарды талап етеді: gtkdocize бағдарламасы configure скриптінен бұрын бір рет іске қосылғанына көз жеткізіңіз. Егер autogen.sh скрипті болса, оны GTK-Doc-ты тексеру үшін реттеп, gtkdocize шақыруын қосыңыз. gtkdocize бағдарламасының негізгі мақсаты — gtk-doc.make Makefile файлын және gtk-doc.m4 макрос анықтамасы файлын жобаға көшіру немесе сілтеу арқылы құрастыру жүйесіне қолжетімді ету. Жасалған configure скрипті арқылы GTK-Doc конфигурациясын жасауға мүмкіндік беру үшін құрастыру жүйесінде GTK-Doc-ты іске қосатын configure.ac файлына қажетті autoconf макростарын қосыңыз. Басқалармен қатар, бұл configure скриптімен --enable-gtk-doc опциясын тіркейді. Жобаңыздағы әрбір қолданба немесе кітапхана үшін automake скриптін жасаңыз. Осы құжаттамада пайдаланылған мысалда бұл қадам meeper және libmeep екеуіне де қатысты. Келесі бөлімдерде біз жоғарыдағы қадамдарды кері ретпен орындаймыз. Біз automake скрипттерінен бастап, configure.ac және autogen.sh файлдарына қарай жүреміз. Содан кейін құрастыру жүйесінде Gtk-Doc-ты қалай іске қосуды және құжаттаманы қалай құрастыруды көрсетеміз. Automake-пен біріктіру Алдымен examples ішкі бумасындағы Makefile.am файлын gtkdoc-sources ішінен жобаңыздың анықтамалық құжаттама бумасына (мысалы, docs/reference/<package>) көшіріңіз. Жергілікті көшірмесі мына жерде қолжетімді болуы керек: /usr/share/doc/gtk-doc-tools/examples/Makefile.am. Егер сізде бірнеше десте болса, мұны әрқайсысы үшін қайталаңыз. Әрбір Makefile.am файлын configure.ac ішіндегі AC_CONFIG_FILES макросына қосуды ұмытпаңыз. docs/reference/libmeep/Makefile.am үшін AC_CONFIG_FILES ішіне docs/reference/libmeep/Makefile жазбасын қосу керек болады. <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). GTK-Doc сіздің API құжаттамаңызды іздейтін бастапқы код бумасының орнын көрсету үшін қолданылады. Бұл әдетте DOC_SOURCE_DIR=$(top_srcdir)/src немесе сол буманың ішкі бумасы болады. және тәуелділіктер үшін қолданылады. Әрбір опция файл маскасын (file-glob) қабылдайды (мысалы, HFILE_GLOB=$(top_srcdir)/src/*.c). Сәйкес келетін файлдардың кез келгені өзгерсе, құжаттама қайта құрастырылады. API құжаттамасын сканерлеу кезінде DOC_SOURCE_DIR ішінде табылмаған қосымша тақырыптық файлдарды қосуға мүмкіндік береді (мысалы, EXTRA_HFILES=$(top_srcdir}/contrib/extra.h). API құжаттамасын сканерлеу кезінде елемейтін тақырыптық файлдарды немесе бумаларды көрсетуге мүмкіндік береді. Файлдың немесе буманың негізгі атын пайдаланыңыз (мысалы, IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder). жасалған құжаттаманың html/ бумасына көшірілетін сурет файлдарын көрсетуге мүмкіндік береді. Егер сіздің API құжаттамаңызға қандай да бір суреттер кірсе, оларды осы опцияға қосу керек (мысалы, 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). #GtkWidget сияқты gtk-doc қысқартулары жазылатын файлдарды көрсетуге мүмкіндік береді (мысалы, expand_content_files=running.xml). Autoconf-пен біріктіру autoconf жүйесімен біріктіру өте оңай және бір міндетті қадамды және қосымша міндетті емес (бірақ ұсынылатын) қадамды қамтиды. Бірінші қадам — configure.ac скриптіне GTK_DOC_CHECK макросын қосу. Бұл GTK-Doc-ты іске қосу үшін бірнеше конфигурация опцияларын тіркейді және gtkdocize үшін әдепкі аргументтерді орнатуға мүмкіндік береді. GTK_DOC_CHECK макросының шегініссіз екеніне көз жеткізіңіз. Макрос жолдың басынан басталуы керек және бос орыннан басталмауы керек. Екінші қадам — configure.ac файлына AC_CONFIG_MACRO_DIR(m4) қосу. Бұл міндетті емес, бірақ gtkdocize бағдарламасына GTK_DOC_CHECK макросы бар макрос анықтамасын (мысалы, gtk-doc.m4) жобаңыздың макрос бумасына автоматты түрде көшіруге көмектеседі. Бұлсыз GTK_DOC_CHECK макросы табылмауы мүмкін және сізге aclocal сайманына макрос анықтамасы файлының қайда екенін нақты көрсету керек болады. Autoconf-пен минималды біріктіру # ұсынылады: m4 бумасын орнату AC_CONFIG_MACRO_DIR(m4) # міндетті емес: configure-де gtk-doc тіркеу GTK_DOC_CHECK([1.28]) Жоғарыдағы мысал жұмыс істейді, бірақ ол барлық әзірлеушілерден gtk-doc орнатылған болуын талап етеді. Жақсырақ жол — келесі мысалда көрсетілгендей құжаттаманы құрастыруды міндетті емес ету: Міндетті емес gtk-doc тәуелділігімен біріктіру m4_ifdef([GTK_DOC_CHECK], [ # ұсынылады: m4 бумасын орнату AC_CONFIG_MACRO_DIR(m4) # міндетті емес: configure-де gtk-doc тіркеу GTK_DOC_CHECK([1.28]) ],[ AM_CONDITIONAL([ENABLE_GTK_DOC], false) ]) Бірінші аргумент конфигурация кезінде Gtk-Doc нұсқасын тексеру үшін қолданылады. 2-ші, міндетті емес аргументті gtkdocize пайдаланады. GTK_DOC_CHECK макросы сонымен қатар бірнеше конфигурация ауыстырып-қосқыштарын қосады: --with-html-dir=PATH : орнатылған құжаттардың жолы --enable-gtk-doc : құжаттаманы құрастыру үшін gtk-doc пайдалану [әдепкі=жоқ] --enable-gtk-doc-html : құжаттаманы html пішімінде құрастыру [әдепкі=иә] --enable-gtk-doc-pdf : құжаттаманы pdf пішімінде құрастыру [әдепкі=жоқ] GTK-Doc әдепкі бойынша сөндірулі! Келесі configure іске қосу кезінде опциясын беруді ұмытпаңыз. Әйтпесе, алдын ала жасалған құжаттама орнатылады (бұл пайдаланушылар үшін тиімді, бірақ әзірлеушілер үшін емес). configure.ac файлына барлық өзгерістер енгізілгеннен кейін, configure файлын жаңартыңыз. Мұны autogen.sh файлын қайта іске қосу арқылы жасауға болады. Autogen-мен біріктіру Көптеген жобаларда жоба нұсқаларды бақылау жүйесінен (мысалы, git немесе svn) алынғаннан кейін құрастыру инфрақұрылымын баптау үшін autogen.sh скрипті болады. GTK-Doc құрамында Gtk-Doc үшін қажетті файлдарды бастапқы код бумасына көшіру үшін қолданылатын 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 макросындағы 2-ші параметр. Сонымен қатар, қосымша аргументтерді gtkdocize скриптіне GTKDOCIZE_FLAGS орта айнымалысы арқылы немесе autogen.sh ішінде тікелей gtkdocize-ға көрсету арқылы беруге болады. GTK-Doc-ты құрастыру жүйесінен орындау Алдыңғы қадамдардан кейін құрастыруды іске қосатын уақыт келді. Алдымен 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 файлына бағыттай аласыз. Осы бастапқы баптаумен сіз тек өте қарапайым құжатты көресіз. Келесі тарау сізге арнайы түсіндірме блоктары арқылы кодыңыздан API құжаттамасын қалай қосу керектігін үйретеді. Одан кейінгі тарау қосымша файлдармен таныстырады және құжаттама файлдарына қосымша тараулар мен бөлімдерді қосу үшін негізгі үлгіні қалай түзету керектігін көрсетеді. CMake құрастыру жүйелерімен біріктіру GTK-Doc енді GtkDocConfig.cmake модулін (және тиісті GtkDocConfigVersion.cmake модулін) ұсынады. Бұл CMakeLists.txt файлында орнатуға болатын gtk_doc_add_module командасын береді. Келесі мысалда осы команданы қалай пайдалану керектігі көрсетілген. GTK-Doc-ты CMake-тен пайдалану мысалы find_package(GtkDoc 1.25 REQUIRED) # doc-libmeep мақсатын жасау. gtk_doc_add_module( libmeep ${CMAKE_SOURCE_DIR}/libmeep XML meep-docs.xml LIBRARIES libmeep ) # Әдепкі мақсаттың бөлігі ретінде doc-libmeep құрастыру. Бұлсыз, сізге # құжаттарды құрастыру үшін `make doc-libmeep` сияқты команданы қолмен іске қосу керек болар еді. add_custom_target(documentation ALL DEPENDS doc-libmeep) # Құжаттарды орнату. (Бұл CMAKE_INSTALL_DOCDIR айнымалысын дұрыс орнату үшін # GNUInstallDirs CMake модулін пайдаланып жатырсыз деп есептейді). install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html DESTINATION ${CMAKE_INSTALL_DOCDIR}) Жай makefile немесе басқа құрастыру жүйелерімен біріктіру Егер біреу automake-ті, демек gtk-doc.mak файлын пайдаланғысы келмесе, жеке makefile файлдарында (немесе басқа құрастыру саймандарында) gtkdoc саймандарын дұрыс ретпен шақыруы керек болады. Құжаттаманы құрастыру қадамдары 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 файлдары да. Кодты құжаттау GTK-Doc кодты құжаттау үшін арнайы синтаксисі бар бастапқы код түсіндірмелерін пайдаланады. Әрі қарай, ол басқа дереккөздерден жобаңыздың құрылымы туралы ақпаратты алады. Келесі бөлімде түсіндірмелер синтаксисі туралы барлық ақпаратты таба аласыз. GTK-Doc сканері C тақырыптық файлдарының көпшілігін жақсы өңдей алады. Егер сканерден ерекше жағдайға ұқсайтын ескертулер алсаңыз, GTK-Doc-қа оларды өткізіп жіберу туралы нұсқау беруге болады. GTK-Doc түсіндірме блогы #ifndef __GTK_DOC_IGNORE__ /* талданбайтын код осында */ #endif Шектеулер Ескеріңіз, GTK-Doc #ifndef(__GTK_DOC_IGNORE__) форматын қолдайды, бірақ #if !defined(__GTK_DOC_IGNORE__) немесе басқа тіркесімдерді қолдамайды. Құжаттама түсіндірмелері Қосымша '*' таңбасынан басталатын көпжолды түсіндірме GTK-Doc саймандарымен өңделетін құжаттама блогын білдіреді. GTK-Doc түсіндірме блогы /** * идентификатор: * құжаттама ... */ 'Идентификатор' — бұл түсіндірмеге қатысты элементтің атауы бар бір жол. Синтаксис элементке байланысты аздап ерекшеленеді. (ЖАСАУ КЕРЕК: идентификаторларды көрсететін кестені қосу) 'Құжаттама' блогы да әрбір таңба түрі үшін әртүрлі болады. Функциялар немесе макростар сияқты параметрлерді алатын таңба түрлерінде алдымен параметр сипаттамасы, содан кейін бос жол келеді (тек '*'). Одан кейін егжей-тегжейлі сипаттама келеді. Тек ' *' (бос орын-жұлдызша) таңбасынан тұратын барлық жолдар (бағдарлама тізімдері мен CDATA бөлімдерінен тыс) абзац үзілімдеріне айналдырылады. Егер абзац үзілімін қаламасаңыз, оны ' * ' (бос орын-жұлдызша-бос орын-бос орын) етіп өзгертіңіз. Бұл алдын ала пішімделген мәтінде (код тізімдерінде) пайдалы. Кодты құжаттау кезінде екі аспектіні сипаттаңыз: Ол не: Класс немесе функция атауы басқа ортадан келген адамдар үшін кейде жаңылыстыруы мүмкін. Ол не істейді: Жалпы қолдану тәсілдері туралы айтыңыз. Оны басқа API-мен байланыстырыңыз. Гипермәтіннің жай мәтіннен бір артықшылығы — құжатта сілтемелердің болуы. Сілтеме үшін дұрыс белгіні жазу жалықтыруы мүмкін. GTK-Doc бірнеше пайдалы қысқартуларды ұсыну арқылы көмекке келеді. Аргументтерді алатын функцияларға немесе макростарға сілтеме жасау үшін функция() пайдаланыңыз. Параметрлерге сілтеме жасау үшін @параметр пайдаланыңыз. Мұны сипатталып жатқан функцияға қатысты басқа функциялардың параметрлеріне сілтеме жасағанда да пайдаланыңыз. Константаға сілтеме жасау үшін %константа пайдаланыңыз, мысалы, %G_TRAVERSE_LEAFS. Аргументтерді алмайтын құрылымдар, тізімдер және макростар сияқты таңбалардың басқа түрлеріне сілтеме жасау үшін #таңба пайдаланыңыз. GObject сигналына сілтеме жасау үшін #Объект::сигнал пайдаланыңыз. GObject қасиетіне сілтеме жасау үшін #Объект:қасиет пайдаланыңыз. Құрылым ішіндегі өріске сілтеме жасау үшін #Құрылым.өріс және vmethod-қа сілтеме жасау үшін #GObjectClass.foo_bar() пайдаланыңыз. Егер құжаттамаңызда GTK-Doc оларды өзгертпей, '<', '>', '()', '@', '%', немесе '#' арнайы таңбаларын пайдалану қажет болса, тиісінше "&lt;", "&gt;", "&lpar;", "&rpar;", "&commat;", "&percnt;" және "&num;" XML нысандарын пайдалануға болады немесе оларды кері қиғаш сызықпен '\' экрандауға болады. DocBook тек сілтемелерден де көп нәрсені істей алады. Сонымен қатар тізімдер, мысалдар, тақырыптар және суреттер болуы мүмкін. 1.20 нұсқасынан бастап, Markdown деп аталатын негізгі мәтінді пішімдеу синтаксисінің ішкі жиынын пайдалану ұсынылады. Ескі GTK-Doc нұсқаларында Markdown қамтитын кез келген құжаттама сол қалпында көрсетіледі. Мысалы, тізім элементтері сызықшадан басталатын жолдар ретінде көрінеді. Қазір markdown-ға басымдық берілсе де, екеуін де араластыруға болады. Мұндағы бір шектеу — markdown ішінде docbook xml пайдалануға болады, бірақ docbook xml ішінде markdown-ға қолдау көрсетілмейді. Ескі GTK-Doc шығарылымдарында, егер сізге қосымша пішімдеуді қолдау қажет болса, Makefile.am ішіндегі MKDB_OPTIONS айнымалысына (немесе ) қосу арқылы түсіндірмелер ішінде docbook XML тегтерін пайдалануды қосуыңыз керек болар еді. Markdown пайдаланатын GTK-Doc түсіндірме блогы /** * идентификатор: * * құжаттама абзацы ... * * # Ішкі тақырып # * * ## Екінші ішкі тақырып * * # Сілтеме якорі бар ішкі тақырып # {#heading-two} * * көбірек құжаттама: * * - тізім элементі 1 * * Тізім элементінің ішіндегі абзац. * * - тізім element 2 * * 1. нөмірленген тізім элементі * * 2. басқа нөмірленген тізім элементі * * Басқа абзац. [GNOME веб-сайтына сілтеме](http://www.gnome.org/) * * ![кірістірілген сурет](plot-result.png) * * [Жоғарыдағы тақырып якоріне сілтеме][heading-two] * * C тіліндегі мысал: * |[<!-- language="C" --> * GtkWidget *label = gtk_label_new ("Gorgeous!"); * ]| */ Қандай markdown тегтеріне қолдау көрсетілетіні туралы көбірек мысалдарды GTK құжаттамасының Markdown синтаксисі анықтамалығынан табуға болады. Бұған дейін айтылғандай, GTK-Doc ашық API құжаттауға арналған. Сондықтан статикалық таңбалар үшін құжаттама жазу мүмкін емес. Соған қарамастан, ол таңбаларға да түсіндірме берген дұрыс. Бұл басқа әзірлеушілерге кодыңызды түсінуге көмектеседі. Сондықтан біз оларды қалыпты түсіндірмелерді пайдаланып сипаттауды ұсынамыз (бірінші жолда екінші '*' таңбасынсыз). Егер кейінірек функцияны ашық ету қажет болса, түсіндірме блогына тағы бір '*' қосып, бөлімдер файлының ішіндегі тиісті жерге таңба атын енгізу жеткілікті. Бөлімдерді құжаттау Құжаттаманың әрбір бөлімінде бір класс немесе модуль туралы ақпарат болады. Компонентті таныстыру үшін бөлім блогын жазуға болады. Қысқаша сипаттама мазмұн кестесінде де қолданылады. Барлық @өрістер міндетті емес. Бөлім түсіндірме блогы /** * SECTION:meepapp * @short_description: қолданба класы * @title: Meep қолданбасы * @section_id: * @see_also: #MeepSettings * @stability: Stable * @include: meep/app.h * @image: application.png * * Қолданба класы ... өңдейді */ SECTION:<аты> Аты бөлім құжаттамасын <package>-sections.txt файлындағы тиісті бөлікке байланыстырады. Мұнда берілген ат <package>-sections.txt файлындағы <FILE> тегіне сәйкес келуі керек. @short_description Бөлімнің бір жолдық сипаттамасы, ол кейінірек мазмұн кестесіндегі сілтемелерден кейін және бөлім бетінің жоғарғы жағында пайда болады. @title Бөлім тақырыбы әдепкі бойынша SECTION декларациясындағы <аты> болады. Оны @title өрісімен алмастыруға болады. @section_id Тақырыпты бөлім идентификаторы ретінде пайдалануды алмастырады. GObjects үшін <title> бөлім идентификаторы (section_id) ретінде қолданылады, ал басқа бөлімдер үшін ол <MODULE>-<title> болады. @see_also Осы бөлімге қатысты таңбалар тізімі. @stability Бұл API ие болатын тұрақтылық деңгейінің бейресми сипаттамасы. Біз мына терминдердің бірін пайдалануды ұсынамыз: Тұрақты (Stable) — Тұрақты интерфейстің мақсаты — кез келген үшінші тараптарға осы интерфейстерге арналған қолданбаларды әзірлеуге, оларды шығаруға және олардың өнімнің барлық кіші шығарылымдарында (интерфейс енгізілген нұсқадан кейін және сол негізгі нұсқа ішінде) жұмыс істейтініне сенімді болуға мүмкіндік беру. Тіпті негізгі шығарылымда да үйлесімсіз өзгерістер сирек болады деп күтіледі және олардың күшті негіздемесі болуы керек. Тұрақты емес (Unstable) — Тұрақты емес интерфейстер эксперименттік немесе өтпелі болып табылады. Олар әдетте сыртқы әзірлеушілерге жаңа немесе тез өзгеретін технологияға ерте қол жеткізуге мүмкіндік беру үшін немесе жалпы шешім күтілетін мәселеге аралық шешім ұсыну үшін пайдаланылады. Бір кіші шығарылымнан екіншісіне бастапқы кодтың немесе бинарлық файлдың үйлесімділігі туралы ешқандай уәде берілмейді. Жеке (Private) — GNOME жиынтығының өзінде қолдануға болатын, бірақ соңғы пайдаланушылар үшін құжатталмаған интерфейс. Мұндай функциялар тек көрсетілген және құжатталған тәсілдермен ғана пайдаланылуы керек. Ішкі (Internal) — Модульге тән және соңғы пайдаланушы құжаттамасын қажет етпейтін интерфейс. Құжатталмаған функциялар Ішкі деп есептеледі. @include Бөлім синопсисінде (үтірмен ажыратылған тізім) көрсетілетін #include файлдары, бөлім файлынан немесе командалық жолдан алынған глобалды мәнді алмастырады. Бұл элемент міндетті емес. @image Осы бөлімнің анықтамалық бетінің жоғарғы жағында көрсетілетін сурет. Бұл көбінесе кластың көрнекі көрінісін немесе оның басқа кластармен байланысын сипаттайтын қандай да бір диаграмма болады. Бұл элемент міндетті емес. Құжат өзгерістерінен кейін қажетсіз қайта құрастыруды болдырмау үшін, бөлім құжаттарын мүмкіндігінше c-бастапқы кодына орналастырыңыз. Таңбаларды құжаттау Әрбір таңба (функция, макрос, құрылым, тізім, сигнал және қасиет) жеке блокта құжатталады. Блокты таңбалардың анықтамасына жақын орналастырған дұрыс, сонда оларды синхрондау оңай болады. Осылайша, функциялар әдетте c-бастапқы кодында, ал макростар, құрылымдар мен тізімдер тақырыптық файлда құжатталады. Жалпы тегтер API-дың қашан енгізілгенін немесе қашан ескіргенін көрсету үшін барлық құжаттама элементтеріне нұсқа туралы ақпаратты қосуға болады. Нұсқа тегтері Бастап: Кодтың қай нұсқасынан бастап API қолжетімді екендігі туралы сипаттама. Ескірген: Бұл функцияны бұдан былай қолдануға болмайтынын білдіретін абзац. Сипаттама оқырманды жаңа API-ға бағыттауы керек. Сондай-ақ жобаның барлық болашақ кіші шығарылымдары үшін API тұрақтылығына кепілдік берілгенін көрсету үшін барлық құжаттама элементтеріне тұрақтылық туралы ақпаратты қосуға болады. Барлық құжаттама элементтері үшін әдепкі тұрақтылық деңгейін gtkdoc-mkdb бағдарламасына төмендегі мәндердің бірімен аргументін беру арқылы орнатуға болады. Тұрақтылық тегтері Тұрақтылығы: Тұрақты Элементті тұрақты ретте белгілеңіз. Бұл жобаның барлық болашақ кіші шығарылымдары үшін тұрақты болып қалуына кепілдік берілген ашық API интерфейстеріне арналған. Тұрақтылығы: Тұрақты емес Элементті тұрақты емес ретте белгілеңіз. Бұл тұрақтандырылғанға дейін алдын ала қарау ретінде шығарылатын ашық API интерфейстеріне арналған. Тұрақтылығы: Жеке Элементті жеке ретте белгілеңіз. Бұл бір-бірімен тығыз байланысты модульдер арқылы пайдаланылуы мүмкін, бірақ кез келген үшінші тараптар үшін емес интерфейстерге арналған. Жалпы тегтер /** * 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 арқылы тілдік байланыстарды жасау үшін қолданылады. Қолдау көрсетілетін тегтердің егжей-тегжейлі тізімін GObject Introspection құжаттамасынан табуға болады. Аннотациялар /** * foo_get_bar: (аннотация) * @foo: (аннотация): кейбір foo * * @foo-дың bar-ын алады. * * Қайтарады: (аннотация): @foo-дың bar-ы */ ... /** * foo_set_bar_using_the_frobnicator: (аннотация) (тағы бір аннотация) * (және тағы бір аннотация) * @foo: (аннотация) (тағы бір аннотация): кейбір foo * * @foo-да bar-ды орнатады. */ Функция түсіндірме блогы Келесілерді ұмытпаңыз: Қайтарылған объектілерді, тізімдерді, жолдарды және т.б. босату/сілтемесін жою/босату (free/unref/release) қажеттігін құжаттаңыз. Параметрлердің NULL болуы мүмкін-болмауын және егер солай болса не болатынын құжаттаңыз. Қажет болған жағдайда қызықты алдын ала шарттар мен кейінгі шарттарды атап өтіңіз. Gtk-doc '_' таңбасынан басталатын барлық таңбаларды (макростар, функциялар) жеке деп есептейді. Олар статикалық функциялар ретінде қарастырылады. Функция түсіндірме блогы /** * функция_аты: * @par1: 1-параметрдің сипаттамасы. Ол бірнеше жолға созылуы * мүмкін. * @par2: 2-параметрдің сипаттамасы * @...: %NULL-мен аяқталатын bar-лар тізімі * * Функцияның сипаттамасы осында жазылады. Параметрлерге сілтеме жасау үшін @par1 * пайдалануға болады, сонда олар нәтижеде ерекшеленеді. Сондай-ақ константалар * үшін %константа, функциялар үшін функция_аты2() және басқа декларацияларға * сілтемелер (олар басқа жерде құжатталған болуы мүмкін) үшін #GtkWidget пайдалана аласыз. * * Қайтарады: бүтін сан. * * Бастап: 2.2 * Ескірген: 2.18: Оның орнына басқа_функция() пайдаланыңыз. */ Функция тегтері Қайтарады: Қайтарылған нәтижені сипаттайтын абзац. @...: Егер функцияда айнымалы аргументтер болса, осы тегті пайдалану керек (@Varargs: тарихи себептермен де жұмыс істейді). Қасиет түсіндірме блогы Қасиет түсіндірме блогы /** * SomeWidget:some-property: * * Мұнда сіз қасиетті құжаттай аласыз. */ g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...); Сигнал түсіндірме блогы Келесілерді ұмытпаңыз: Сигналдың қашан таратылатынын және оның басқа сигналдардан бұрын немесе кейін таратылатынын құжаттаңыз. Сигнал өңдеушісінде қолданба не істей алатынын құжаттаңыз. Сигнал түсіндірме блогы /** * FooWidget::foobarized: * @widget: сигналды алған виджет * @foo: кейбір foo * @bar: кейбір bar * * ::foobarized сигналы біреу @widget-ті foobarize жасауға тырысқан сайын таратылады. */ 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" болса, ол автоматты түрде жеке деп есептеледі және оны түсіндірме блогында атап өтудің қажеті жоқ. Құрылым түсіндірме блоктарын GObjects және GObjectClasses үшін де пайдалануға болады. Егер класта vmethod-тар болса (оларды осылай құжаттауға болады), оған түсіндірме блогын қосқан жөн. GObject-тың өзі үшін тиісті бөлім құжаттарын пайдалануға болады, егер данада ашық өрістер болса, дана құрылымы үшін жеке блоктың болуы пайдалы болар еді. Мұндағы бір кемшілік — бұл бір атаумен екі индекс жазбасын жасайды (құрылым және бөлім). Тізім (enum) түсіндірме блогы Тізім (enum) түсіндірме блогы /** * Something: * @SOMETHING_FOO: something foo * @SOMETHING_BAR: something bar * * Нәрсені көрсету үшін қолданылатын тізім мәндері. */ typedef enum { SOMETHING_FOO, SOMETHING_BAR, /*< private >*/ SOMETHING_COUNT } Something; Жасқырғыңыз келетін жеке тізім мәндерінің алдында /*< private >*/ пайдаланыңыз. Керісінше әрекет үшін /*< public >*/ пайдаланыңыз. Бағдарламаның ішкі құжаттамасы Бағдарламаларды және олардың командалық жол интерфейсін ішкі құжаттама арқылы құжаттай аласыз. Тегтер PROGRAM Бағдарлама құжаттамасының басталуын анықтайды. @short_description: Бағдарламаның қысқаша сипаттамасын анықтайды. (Міндетті емес) @synopsis: Бағдарлама қабылдай алатын аргументтерді немесе аргументтер тізімін анықтайды. (Міндетті емес) @see_also: Нұсқаулық бетінің "Сондай-ақ қараңыз" бөлімі. (Міндетті емес) @arg: Бағдарламаға берілетін аргумент(тер) және олардың сипаттамасы. (Міндетті емес) Сипаттамасы: Бағдарламаның толығырақ сипаттамасы. Қайтарады: Бағдарлама қандай мән(дер) қайтаратынын көрсетіңіз. (Міндетті емес) Бағдарлама құжаттамасының мысалы. Бағдарлама құжаттамасының блогы /** * PROGRAM:test-program * @short_description: Тесттік бағдарлама * @synopsis: test-program [*ОПЦИЯЛАР*...] --arg1 *арг* *ФАЙЛ* * @see_also: test(1) * @--arg1 *арг*: arg1 мәнін *арг* етіп орнату * @--arg2 *арг*: arg2 мәнін *арг* етіп орнату * @-v, --version: Нұсқа нөмірін басып шығару * @-h, --help: Көмек хабарын басып шығару * * Бағдарламаның толық сипаттамасы. * * Қайтарады: Сәтті болғанда нөл, сәтсіз болғанда нөл емес мән */ int main(int argc, char *argv[]) { return 0; } Пайдалы DocBook тегтері Мұнда кодты құжаттау кезінде ең пайдалы DocBook тегтері берілген. GTK құжаттарындағы басқа бөлімге сілтеме жасау үшін: <link linkend="glib-Hash-Tables">Хэш-кестелер</link> linkend — сілтеме жасағыңыз келетін беттің жоғарғы элементіндегі SGML/XML идентификаторы. Көптеген беттер үшін бұл қазіргі уақытта бөлім ("gtk", "gdk", "glib"), содан кейін бет тақырыбы ("Хэш-кестелер"). Виджеттер үшін бұл жай ғана класс атауы. SGML/XML талаптарына сәйкес келу үшін бос орындар мен астын сызу таңбалары '-' таңбасына айналдырылады. Сыртқы функцияға сілтеме жасау үшін, мысалы, стандартты C функциясы: <function>...</function> Код мысалын қосу үшін: <example> <title>GHashTable пайдалану.</title> <programlisting language="C"> ... </programlisting> </example> немесе тақырыпты қажет етпейтін өте қысқа код фрагменттері үшін: <informalexample> <programlisting language="C"> ... </programlisting> </informalexample> Екі жағдайда да language атрибуты міндетті емес және синтаксисті жарықтандыру қозғалтқышына (html нәтижесі үшін pygments) нұсқау ретінде қолданылады. Соңғысы үшін GTK-Doc қысқартуды да қолдайды: |[<!-- language="C" --> ... ]| Таңбаланған тізімдерді қосу үшін: <itemizedlist> <listitem> <para> ... </para> </listitem> <listitem> <para> ... </para> </listitem> </itemizedlist> Мәтіннен ерекшеленіп тұратын ескертуді қосу үшін: <note> <para> Пайдаланғаннан кейін деректерді босатуды ұмытпаңыз. </para> </note> Түрге (type) сілтеме жасау үшін: <type>unsigned char</type> Сыртқы құрылымға сілтеме жасау үшін (GTK құжаттарында сипатталмаған): <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. Түрлер (types) файлын түзету Егер сіздің кітапханаңызда немесе қолданбаңызда GObjects болса, олардың сигналдары, аргументтері/параметрлері және иерархиядағы орны құжаттамада көрсетілгенін қалайсыз. Сізге тек xxx_get_type функцияларын олардың include файлымен бірге <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 GTK-Doc 1.8 нұсқасынан бастап gtkdoc-scan бұл тізімді сіз үшін жасай алады. Тек Makefile.am ішіндегі SCAN_OPTIONS айнымалысына "--rebuild-types" қосыңыз. Егер сіз осы тәсілді пайдалансаңыз, types файлын таратпауыңыз немесе оны нұсқаларды бақылау жүйесінде сақтамауыңыз керек. Негізгі құжатты түзету 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> Бұған қоса, түсіндірме түрінде бірнеше опциялық элементтер жасалады. Сіз оларды қарап шығып, қалауыңызша іске қоса аласыз. Негізгі құжаттағы міндетті емес бөлік <!-- gobject introspection аннотацияларын пайдаланған кезде мұны іске қосыңыз <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> --> Соңында, жаңа бөлім енгізген сайын оны қосу керек. gtkdoc-check сайманы әлі құжатқа енгізілмеген жаңадан жасалған xml файлдары туралы еске салып отырады. Жасалған бөлімдерді қосу <chapter> <title>менің кітапханам</title> <xi:include href="xml/object.xml"/> ... Бөлім файлын түзету Бөлім файлы GTK-Doc шығаратын құжаттаманы ұйымдастыру үшін қолданылады. Мұнда қай таңба қай модульге немесе класқа жататыны көрсетіледі және көрінуі (ашық немесе жеке) басқарылады. Бөлім файлы — бөлімдерді ажырататын тегтері бар жай мәтіндік файл. Бос жолдар еленбейді және '#' таңбасынан басталатын жолдар түсіндірме жолдары ретінде қарастырылады. Тегтер файлды xml сияқты етіп көрсеткенімен, ол 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 үлгі файлында шығарылуына әкеледі, ол xml/gnome-config.sgml DocBook XML файлына немесе xml/gnome-config.xml DocBook XML файлына айналдырылады. (HTML файлының аты модуль атына және бөлім тақырыбына негізделеді немесе GObjects үшін ол кіші әріптерге айналдырылған GObjects класс атына негізделеді). <TITLE> ... </TITLE> тегі бөлім тақырыбын көрсету үшін қолданылады. Ол тек үлгілер (егер пайдаланылса) бастапқыда жасалғанға дейін ғана пайдалы, өйткені үлгі файлында орнатылған тақырып оны алмастырады. Сондай-ақ, егер бастапқы кодтарда SECTION түсіндірмесі пайдаланылса, бұл ескірген болып саналады. Элементтерді бөлімде <SUBSECTION> тегі арқылы топтастыруға болады. Қазіргі уақытта ол синопсис бөліміндегі ішкі бөлімдер арасында бос жолды шығарады. Стандартты GObject декларациялары (мысалы, g_object_get_type сияқты функциялар және G_OBJECT(), G_IS_OBJECT() және т.б. сияқты макростар) үшін <SUBSECTION Standard> пайдалануға болады. Қазіргі уақытта олар құжаттамадан тыс қалады. Сондай-ақ шығарылмайтын жеке декларациялар үшін <SUBSECTION Private> пайдалануға болады (бұл пайдаланылмаған декларациялар туралы ескерту хабарламаларын болдырмаудың ыңғайлы жолы). Егер кітапханаңызда объект иерархиясында және іске асырылған немесе талап етілетін интерфейстер тізімінде көрінуін қаламайтын жеке түрлер болса, оларды Private ішкі бөліміне қосыңыз. GObject және GObjectClass сияқты құрылымдарды public немесе Standard бөліміне орналастыру олардың ашық жазбаларының (айнымалылар, vmethod-тар) болуына байланысты. Синопсис бөлімдерінде көрсетілетін #include файлдарын көрсету үшін <INCLUDE> ... </INCLUDE> де пайдалануға болады. Онда бұрыштық жақшасыз, үтірмен ажыратылған #include файлдарының тізімі болады. Егер оны кез келген бөлімнен тыс орнатсаңыз, ол файлдың соңына дейін барлық бөлімдер үшін әрекет етеді. Егер оны бөлім ішінде орнатсаңыз, ол тек сол бөлімге ғана қатысты болады. Нәтижені бақылау GTK-Doc іске қосылуы құжаттама бумасында есеп файлдарын жасайды. Жасалған файлдар келесідей аталады: <package>-undocumented.txt, <package>-undeclared.txt және <package>-unused.txt. Бұлардың барлығы оңай қарауға және өңдеуге болатын жай мәтіндік файлдар. <package>-undocumented.txt файлы құжаттаманың қамтылуы туралы жиынтықпен басталады. Төменде бос жолдармен бөлінген екі бөлім бар. Бірінші бөлімде құжатталмаған немесе толық емес таңбалар тізімі берілген. Екінші бөлімде бөлім құжаттары үшін дәл солай жасалған. Толық емес жазбалар — бұл құжаттамасы бар, бірақ, мысалы, жаңа параметр қосылған жазбалар. <package>-undeclared.txt файлы <package>-sections.txt файлында берілген, бірақ бастапқы кодтарда табылмаған таңбаларды тізімдейді. Олардың жойылғанын немесе қате жазылғанын тексеріңіз. <package>-unused.txt файлы GTK-Doc сканері құжаттамасын тапқан, бірақ оны қайда қою керектігін білмейтін таңбалардың атауларын тізімдейді. Бұл таңба әлі <package>-sections.txt файлына қосылмағанын білдіреді. Makefile.am ішіне жолын қосыңыз немесе іске қосыңыз. Егер кем дегенде GTK-Doc 1.9 орнатылған болса, бұл make check іске қосу кезінде дұрыстық тексерулерін орындайды. Сондай-ақ бастапқы код сканері шығарған файлдарды қарауға болады: <package>-decl-list.txt және <package>-decl.txt. Біріншісін бөлім файлымен салыстыруға болады, егер ол қолмен сақталса. Екіншісі тақырыптық файлдардағы барлық декларацияларды тізімдейді. Егер таңба жетіспесе, осы файлда оның бар-жоғын тексеруге болады. Егер жоба GObject негізінде болса, объект сканері шығарған файлдарды да қарауға болады: <package>.args.txt, <package>.hierarchy.txt, <package>.interfaces.txt, <package>.prerequisites.txt және <package>.signals.txt. Егер олардың кез келгенінде таңбалар жетіспесе, GTK-Doc-ты GTK_DOC_KEEP_INTERMEDIATE=1 make арқылы іске қосып, одан әрі талдау үшін аралық сканер файлын сақтауын сұрауға болады. Құжаттаманы заманауи ету GTK-Doc біраз уақыттан бері бар. Бұл бөлімде біз жаңа мүмкіндіктерді олардың қолжетімді болған нұсқасымен бірге тізімдейміз. GTK-Doc 1.9 sgml орнына xml пайдаланған кезде, негізгі құжатты <package>-docs.xml деп атауға болады. Бұл нұсқа Makefile.am ішіндегі параметрін қолдайды. Бұл іске қосылғанда, <package>-sections.txt автоматты түрде жасалады және оны нұсқаларды бақылау жүйесінен алып тастауға болады. Бұл тек өте тұрақты құрылымы бар жобалар үшін жақсы жұмыс істейді (мысалы, әрбір .{c,h} жұбы жаңа бөлім жасайды). Егер сіз жобаны соған жақын ұйымдастырсаңыз, қолмен сақталатын бөлім файлын жаңарту meld <package>-decl-list.txt <package>-sections.txt іске қосу сияқты оңай болуы мүмкін. 1.8 нұсқасы tmpl ішіндегі жеке файлдардың орнына бастапқы кодтардағы бөлімдерді құжаттау синтаксисін енгізді. Бұл нұсқа configure.ac ішінде пайдалану арқылы бүкіл құжат модулін қосымша tmpl құрастыру қадамын мүлдем пайдаланбауға ауыстыру опцияларын қосады. Егер сізде нұсқаларды бақылау жүйесіне енгізілген tmpl болмаса және әлі ауыспаған болсаңыз, жай ғана configure.ac файлына жалаушаны қосыңыз, болды. GTK-Doc 1.10 Бұл нұсқа Makefile.am ішіндегі параметрін қолдайды. Бұл іске қосылғанда, <package>.types автоматты түрде жасалады және оны нұсқаларды бақылау жүйесінен алып тастауға болады. Бұл мүмкіндікті пайдаланған кезде шартты түрде құрастырылатын код үшін Makefile.am ішінде IGNORE_HFILES параметрін де орнату маңызды. GTK-Doc 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 GTK-Doc 1.20 1.18 нұсқасы кейбір бастапқы markdown қолдауын әкелді. Құжат түсіндірмелерінде markdown пайдалану docbook xml жазуға қарағанда ыңғайлырақ. Бұл нұсқа оны айтарлықтай жақсартады және көптеген стильдерді қосады. Түсіндірме синтаксисін түсіндіретін бөлімде барлық мәліметтер бар. GTK-Doc 1.25 Осы нұсқамен бірге келетін makefile файлдары xml/gtkdocentities.ent мекенжайында нысан (entity) файлын жасайды, онда мысалы, package_name және package_version нысандары болады. Нұсқа нөмірін қолмен жазбау үшін оны негізгі xml файлында пайдалануға болады. Төменде нысан файлының негізгі үлгіге қалай қосылатыны және нысандардың қалай қолданылатыны көрсетілген мысал берілген. Нысандарды барлық жасалған файлдарда да пайдалануға болады, GTK-Doc жасалған xml файлдарында бірдей xml тақырыптамасын пайдаланады. Алдын ала жасалған нысандарды (entities) пайдалану <?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; анықтамалық нұсқаулығы</title> <releaseinfo> &package_string; үшін. Бұл құжаттаманың соңғы нұсқасын желіде мына жерден табуға болады: <ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>. </releaseinfo> </bookinfo> Басқа интерфейстерді құжаттау Осы уақытқа дейін біз GTK-Doc-ты кодтың API-ын құжаттау үшін пайдаланып келдік. Келесі бөлімдерде саймандарды басқа интерфейстерді құжаттау үшін қалай пайдалануға болатыны туралы ұсыныстар берілген. Командалық жол опциялары және man беттері Docbook refentry үшін де man беттерін жасауға болатындықтан, оны осы мақсатта пайдалану жақсы идея болып көрінеді. Осылайша интерфейс анықтамалықтың бір бөлігі болады және сіз man-бетті тегін аласыз. Сайманды құжаттау Әр сайман үшін бір refentry файлын жасаңыз. Біздің мысалымызға сүйене отырып, біз оны meep/docs/reference/meeper/meep.xml деп атар едік. Қолданылуы тиіс xml тегтері үшін xml ішкі бумасындағы жасалған файлды, сондай-ақ glib ішіндегі мысалдарды қарауға болады. Қосымша configure тексеруін қосу Қосымша configure тексерулері AC_ARG_ENABLE(man, [AC_HELP_STRING([--enable-man], [man беттерін Docbook-тан қайта жасау [әдепкі=жоқ]])],enable_man=yes, enable_man=no) AC_PATH_PROG([XSLTPROC], [xsltproc]) AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno) Қосымша makefile ережелерін қосу Қосымша configure тексерулері 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 DBus интерфейстері (ТҮЗЕТУ КЕРЕК: 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 дана құрылымының аты) қалыпты бөлімнің бөлігі болып табыла ма (оны Standard немесе Private ішкі бөлімдеріне қоймаңыз). Таңбалар индексі жоқ. <package>-docs.{xml,sgml} файлында жасалған индексті xi:include арқылы қосатын индекс бар ма? Таңбалар өздерінің құжаттама бөліміне сілтемеленбеген. Құжат түсіндірмесінде дұрыс белгілер (#, % немесе ()) қолданылған ба? gtkdoc-fixxref шешілмейтін xref-тер туралы ескертетінін тексеріңіз. Жаңа класс құжаттарда көрінбейді. Жаңа бет <package>-docs.{xml,sgml} ішінен xi:include арқылы қосылған ба. Жаңа таңба құжаттарда көрінбейді. Құжат түсіндірмесі дұрыс пішімделген бе? Түсіндірменің басындағы емле қателерін тексеріңіз. gtkdoc-fixxref шешілмейтін xref-тер туралы ескертетінін тексеріңіз. Таңба <package>-sections.txt файлындағы ашық ішкі бөлімде дұрыс тізімделгенін тексеріңіз. Класс иерархиясында түр (type) жетіспейді. Егер түр <package>.hierarchy ішінде тізімделген, бірақ xml/tree_index.sgml ішінде болмаса, түрдің <package>-sections.txt файлында дұрыс орналастырылғанын қайта тексеріңіз. Егер түр данасы (мысалы, GtkWidget) тізімделмесе немесе байқаусызда жеке ретінде белгіленсе, ол көрсетілмейді. Мен барлық gobject аннотациялары үшін foldoc сілтемелерін аламын. xml/annotation-glossary.xml файлы <package>-docs.{xml,sgml} ішінен xi:include арқылы қосылғанын тексеріңіз. Параметр бастапқы кодтың түсіндірме блогында сипатталған, бірақ ол жоқ Тақырыптағы прототипте бастапқы кодтағыдан басқа параметр атауларының бар-жоғын тексеріңіз. шектеулі linkend үшін бірнеше "ID" бар: XYZ XYZ таңбасы <package>-sections.txt файлында екі рет кездеседі. para ішінде '' атаулар кеңістігіндегі typename элементі кездесті, бірақ ешбір үлгі сәйкес келмеді. gtk-doc-қа қатысты саймандар GtkDocPlugin — trac сайтына API құжаттарын қосатын және trac іздеуімен біріктіретін Trac GTK-Doc біріктіру плагині. Gtkdoc-depscan — ең төменгі қажетті нұсқаны анықтау үшін пайдаланылған API-ды API-дағы since тегтеріне қарсы тексеретін сайман (gtk-doc бөлігі). 1.1 нұсқасы, наурыз 2000 2000Free Software Foundation, Inc.
Free Software Foundation, Inc. 51 Franklin Street, Suite 330, Boston, MA 02110-1301 USA
Осы лицензиялық құжаттың сөзбе-сөз көшірмелерін көшіруге және таратуға барлығына рұқсат етіледі, бірақ оны өзгертуге жол берілмейді. GNU еркін құжаттама лицензиясы 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 енгізу пішімі, жалпыға қолжетімді DTD пайдаланатын SGML немесе XML және адамның өзгертуіне арналған стандартқа сәйкес келетін қарапайым HTML жатады. Күңгірт пішімдерге PostScript, PDF, тек меншікті мәтіндік процессорлармен оқуға және түзетуге болатын меншікті пішімдер, DTD және/немесе өңдеу саймандары жалпыға бірдей қолжетімді емес SGML немесе XML, сондай-ақ кейбір мәтіндік процессорлар тек шығару мақсатында жасаған машинамен жасалған 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: A 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. B 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. D 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. G 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. M Delete any section entitled Endorsements. Such a section may not be included in the Modified Version. N 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. Қосымша Осы Лицензияны өзіңіз жазған құжатта пайдалану үшін құжатқа Лицензияның көшірмесін енгізіңіз және титулдық беттен кейін бірден келесі авторлық құқық және лицензиялық ескертулерді қойыңыз:
Copyright ЖЫЛ СІЗДІҢ АТЫҢЫЗ. 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.