i Εγχειρίδιο GTK-Doc
ii Copyright 2000, 2005, 2007-2009 Dan Mueth, Chris Lyttle και Stefan Kost Copyright επισκεφθείτε την σελίδα http://www.gnome.gr/ Για περισσότερες πληροφορίες Χορηγείται άδεια αντιγραφής, διανομής και/ή τροποποίησης του παρόντος εγγράφου υπό τους όρους της έκδοσης 1.1 της Ελεύθερης Άδειας Τεκμηρίωσης GNU (GFDL), ή οποιασδήποτε μεταγενέστερης έκδοσής αυτής από το Ίδρυμα Ελεύθερου Λογισμικού (FSF), χωρίς αμετάβλητα τμήματα, κείμενα εξωφύλλου και κείμενα οπισθοφύλλου. Συμπεριλαμβάνεται αντίγραφο της άδειας. Πολλές από τις ονομασίες που χρησιμοποιούνται από εταιρείες για την διαφοροποίηση των προϊόντων και υπηρεσιών τους έχουν καταχωρισθεί ως εμπορικά σήματα. Σε όποιο σημείο της τεκμηρίωσης GNOME τυχόν εμφανίζονται αυτές οι ονομασίες, και εφόσον τα μέλη του Έργου τεκμηρίωσης GNOME έχουν λάβει γνώση αυτών των εμπορικών σημάτων, οι ονομασίες ή τα αρχικά αυτών θα γράφονται με κεφαλαίους χαρακτήρες.
iii COLLABORATORS TITLE : Εγχειρίδιο GTK-Doc ACTION NAME DATE SIGNATURE WRITTEN BY Chris Lyttle, Dan Mueth, and Stefan Kost May 27, 2009 REVISION HISTORY NUMBER DATE DESCRIPTION NAME 1.11 22 Μαρτίου 2008 Μετάβαση από GNOME doc-utils mal
iv Contents 1 Εισαγωγή 1 1.1 Τι είναι το GTK-Doc;.......................................... 1 1.2 Πώς λειτουργεί το GTK-Doc;..................................... 1 1.3 Λήψη GTK-Doc.............................................. 2 1.3.1 Απαιτήσεις............................................ 2 1.3.2 Εγκατάσταση.......................................... 3 1.4 Περί GTK-Doc.............................................. 3 1.5 Περί του εγχειριδίου.......................................... 3 2 Ξεκινώντας ένα έργο 4 2.1 Δημιουργία ενός σκελετού τεκμηρίωσης.............................. 4 2.2 Ενσωμάτωση στο autoconf...................................... 4 2.3 Ενσωμάτωση στο automake..................................... 5 2.4 Ενσωμάτωση στο autogen...................................... 5 2.5 Παραγωγή της τεκμηρίωσης..................................... 6 2.6 Ενσωμάτωση σε συστήματα ελέγχου εκδόσεων......................... 6 3 Τεκμηρίωση του κώδικα 7 3.1 Σχόλια τεκμηρίωσης.......................................... 7 3.2 Ενότητες τεκμηρίωσης......................................... 8 3.3 Τεκμηρίωση συμβόλων......................................... 9 3.4 Χρήσιμες ετικέτες DocBook...................................... 11 4 Συμπλήρωση επιπλέον αρχείων 13 4.1 Επεξεργασία του αρχείου types................................... 13 4.2 Επεξεργασία κύριου εγγράφου (master).............................. 13 4.3 Επεξεργασία αρχείου ενοτήτων................................... 14 5 Έλεγχος αποτελέσματος 16 6 Συχνές ερωτήσεις 17
v A Άδεια Ελεύθερης Τεκμηρίωσης GNU (GFDL) 18 A.1 0. ΠΡΟΟΙΜΙΟ.............................................. 18 A.2 1. ΙΣΧΥΣ ΚΑΙ ΟΡΙΣΜΟΙ........................................ 18 A.3 2. ΑΚΡΙΒΗ ΑΝΤΙΓΡΑΦΑ........................................ 19 A.4 3. ΑΝΤΙΓΡΑΦΗ ΣΕ ΜΕΓΑΛΕΣ ΠΟΣΟΤΗΤΕΣ........................... 19 A.5 4. ΤΡΟΠΟΠΟΙΗΣΕΙΣ.......................................... 20 A.6 5. ΣΥΝΔΥΑΣΜΟΣ ΕΓΓΡΑΦΩΝ.................................... 21 A.7 6. ΣΥΛΛΟΓΗ ΕΓΓΡΑΦΩΝ....................................... 22 A.8 7. ΣΥΡΡΑΦΗ ΜΕ ΑΝΕΞΑΡΤΗΤΑ ΕΡΓΑ............................... 22 A.9 8. ΜΕΤΑΦΡΑΣΗ............................................. 22 A.109. ΚΑΤΑΡΓΗΣΗ............................................. 23 A.1110. ΜΕΛΛΟΝΤΙΚΕΣ ΑΝΑΘΕΩΡΗΣΕΙΣ ΤΗΣ ΠΑΡΟΥΣΑΣ ΑΔΕΙΑΣ............... 23 A.12Συμπλήρωμα............................................... 23
Abstract Εγχειρίδιο χρήσης του GTK-Doc για προγραμματιστές.
1 / 23 Chapter 1 Εισαγωγή Αυτό το κεφάλαιο αποτελεί μια εισαγωγή στο GTK-Doc. Περιγράφει το GTK-Doc και τον τρόπο χρήσης του. 1.1 Τι είναι το GTK-Doc; Το GTK-Doc χρησιμοποιείται για την τεκμηρίωση κώδικα C. Συνήθως, χρησιμοποιείται για την τεκμηρίωση του δημόσιου API βιβλιοθηκών όπως η GTK+ και η GNOME. Μπορεί όμως να χρησιμοποιηθεί και για την τεκμηρίωση κώδικα εφαρμογών. 1.2 Πώς λειτουργεί το GTK-Doc; Το GTK-Doc χρησιμοποιεί την τεκμηρίωση συναρτήσεων που έχει συμπεριληφθεί στα πηγαία αρχεία (εντός μπλοκ σχολίων με ειδική μορφή), ή την τεκμηρίωση που έχει προστεθεί στα πρότυπα αρχεία που χρησιμοποιεί το GTK-Doc (σημειώστε όμως ότι το GTK-Doc παράγει τεκμηρίωση μόνο για τις συναρτήσεις που δηλώνονται σε αρχεία κεφαλίδας δεν παράγει τεκμηρίωση για στατικές συναρτήσεις). Το GTK-Doc αποτελείται από μια σειρά από σενάρια perl, καθένα από τα οποία είναι υπεύθυνο για διαφορετικό στάδιο της όλης διαδικασίας. Η διαδικασία περιλαμβάνει 5 κύρια στάδια: 1. Συγγραφή τεκμηρίωσης Ο συγγραφέας συμπληρώνει τα πηγαία αρχεία με τεκμηρίωση για όλες τις συναρτήσεις, μακροεντολές, ενώσεις κτλ. (Στο παρελθόν, οι πληροφορίες συμπληρώνονταν σε πρότυπα αρχεία που παράγονταν αυτόματα, αλλά αυτός ο τρόπος δεν συνιστάται πλέον.) 2. Συλλογή πληροφοριών για τον κώδικα Το gtkdoc-scan σαρώνει τα αρχεία κεφαλίδας του κώδικα, αναζητώντας δηλώσεις συναρτήσεων, μακροεντολών, αριθμήσεων, δομών και ενώσεων. Στη συνέχεια, δημιουργεί το αρχείο <module>-decl-list.txt που περιέχει λίστα με όλες τις δηλώσεις, ταξινομημένες ανά ενότητες, ανάλογα με το αρχείο κεφαλίδας από το οποίο προήλθαν. Κατά την πρώτη εκτέλεση, αυτό το αρχείο αντιγράφεται στο <module>-sections.txt. Ο συγγραφέας μπορεί να αλλάξει τη σειρά των ενοτήτων, καθώς και τη σειρά των δηλώσεων σε κάθε ενότητα, προκειμένου η τελική σειρά να ανταποκρίνεται στις επιθυμίες του. Το δεύτερο αρχείο που παράγεται είναι το <module>-decl.txt. Αυτό το αρχείο περιέχει όλες τις δηλώσεις που βρέθηκαν κατά τη σάρωση. Αν θέλετε να εμφανιστούν στην τεκμηρίωση δηλώσεις οι οποίες δε βρέθηκαν κατά τη σάρωση, ή αν θέλετε να αλλάξει η εμφάνιση κάποιων δηλώσεων, μπορείτε να δημιουργήσετε εγγραφές παρόμοιες με αυτές του αρχείου <module>-decl.txt και να τις προσθέσετε στο αρχείο <module>-overrides.txt. Το gtkdoc-scanobj μπορεί επίσης να χρησιμοποιηθεί για να κάνει δυναμική
2 / 23 αναζήτηση σε μια βιβλιοθήκη για ενδεχόμενες υποκλάσεις GtkObject. Αποθηκεύει τις πληροφορίες για τη θέση κάθε αντικειμένου στην ιεραρχία κλάσεων, καθώς και για τα ορίσματα και σήματα GTK που περιέχει. 3. Δημιουργία "πρότυπων" αρχείων Το gtkdoc-mktmpl παράγει μια σειρά από αρχεία στον υποκατάλογο tmpl/, χρησιμοποιώντας τις πληροφορίες που συλλέχθηκαν κατά το πρώτο στάδιο. (Σημειώστε ότι μπορεί να εκτελεστεί περισσότερες από μία φορές. Προσπαθεί να διασφαλίσει ότι δεν χάνεται ποτέ και κανενός είδους τεκμηρίωση.) Note Από την έκδοση 1.9 και μετά, τα πρότυπα αρχεία δεν είναι πλέον απαραίτητα. Σας συνιστούμε να διατηρείτε την τεκμηρίωση στον κώδικα. Έτσι, το gtkdocize υποστηρίζει πλέον την επιλογή --flavour no-tmpl που επιλέγει ένα αρχείο make που δεν χρησιμοποιεί καθόλου πρότυπα. Αν δεν έχετε κάνει ποτέ αλλαγές με το χέρι σε αρχεία προτύπων, παρακαλώ αφαιρέστε τον κατάλογο. 4. Παραγωγή SGML/XML και HTML. Το gtkdoc-mkdb μετατρέπει τα πρότυπα αρχεία σε αρχεία SGML ή XML files και τα τοποθετεί στους υποκαταλόγουςsgml/ ή xml/. Αν ο πηγαίος κώδικας περιέχει τεκμηρίωση συναρτήσεων εντός ειδικών μπλοκ σχολίων,τα σχόλια συγχωνεύονται σε αυτό το στάδιο. Αν δεν υπάρχουν πρότυπα αρχεία, τότε χρησιμοποιούνται μόνο τα έγγραφα που προέκυψαν από τον πηγαίο κώδικα και τα δεδομένα της ενδοσκόπησης. Το gtkdoc-mkhtml μετατρέπει τα αρχεία SGML σε αρχεία HTML που τοποθετούνται στον υποκατάλογο html/. Τα αρχεία στους καταλόγους sgml/, xml/ και html/ αντικαθίστανται αυτόματα. Επομένως, δεν πρέπει να τα αλλάζετε με το χέρι. 5. Διόρθωση παραπομπών μεταξύ εγγράφων Μετά την εγκατάσταση των αρχείων HTML, μπορείτε να εκτελέσετε το gtkdoc-fixxref για να διορθώσετε τυχόν παραπομπές σε διαφορετικά έγγραφα. Για παράδειγμα, η τεκμηρίωση του GTK+ περιέχει πολλές παραπομπές σε τύπους που επεξηγούνται στο εγχειρίδιο του GLib. Όταν ετοιμάζετε πακέτα κώδικα για διανομή, μπορείτε να χρησιμοποιείτε το gtkdoc-rebase για να μετατρέπετε όλους τους εξωτερικούς συνδέσμους σε διαδικτυακούς συνδέσμους. Κατά την εγκατάσταση της τεκμηρίωσης που περιλαμβάνεται στο διανεμηθέντα κώδικα (παράγεται αυτόματα), η ίδια εφαρμογή θα προσπαθήσει να μετατρέψει ξανά τους συνδέσμους σε τοπικούς συνδέσμους (προς τις τοποθεσίες όπου είναι εγκατεστημένη η τεκμηρίωση). 1.3 Λήψη GTK-Doc 1.3.1 Απαιτήσεις Perl v5 - τα βασικά σενάρια είναι γραμμένα σε Perl. DocBook DTD v3.0 - Πρόκειται για την DocBook SGML DTD. http://www.ora.com/davenport Jade v1.1 - Πρόκειται για επεξεργαστή DSSSL που μετατρέπει τη SGML σε διάφορες άλλες μορφές. http://www.jclark.com/jade Modular DocBook Stylesheets Πρόκειται για τον κώδικα DSSSL που απαιτείται για τη μετατροπή από DocBook σε HTML (και ορισμένες άλλες μορφές). Χρησιμοποιείται σε συνδυασμό με το jade. Έχουν γίνει κάποιες μικρές προσαρμογές του κώδικα DSSSL, στο gtk-doc.dsl, για το χρωματισμό κώδικα/δηλώσεων και για την υποστήριξη των καθολικών ευρετηρίων παραπομπών στα παραγόμενα HTML. http://nwalsh.com/docbook/dsssl docbook-to-man - Σε περίπτωση που θέλετε να δημιουργήσετε σελίδες man από το DocBook. Έχουν γίνει κάποιες μικρές προσαρμογές των 'προδιαγραφών μετάφρασης', για να εμφανίζονται με κεφαλαία οι τίτλοι ενοτήτων και να προστίθενται ο τίτλος 'Βιβλιοθήκη GTK' στην αρχή της σελίδας και η ημερομηνία αναθεώρησης στο τέλος της. Βλέπε http://www.ora.com/davenport ΣΗΜΕΙΩΣΗ: Αυτή η δυνατότητα δε λειτουργεί προς το παρόν.
3 / 23 1.3.2 Εγκατάσταση Δεν υπάρχει σταθερή τοποθεσία για την εγκατάσταση των DocBook Modular Stylesheets. Το σενάριο configure του gtk-doc ψάχνει αυτόματα τους τρεις παρακάτω καταλόγους: /usr/lib/sgml/stylesheets/nwalsh-modular (χρησιμοποιείται από το RedHat) /usr/lib/dsssl/stylesheets/docbook (χρησιμοποιείται από το Debian) /usr/share/sgml/docbkdsl (χρησιμοποιείται από το SuSE) Αν τα φύλλα στυλ είναι εγκατεστημένα κάπου αλλού, θα πρέπει να χρησιμοποιήσετε το gtk-doc με την επιλογή: --with-dsssl-dir=<διαδρομη_προσ_ριζικο_καταλογο_φυλλων_στυλ> 1.4 Περί GTK-Doc (ΠΡΟΣ ΔΙΟΡΘΩΣΗ) (Ιστορικό, συγγραφείς, ιστοσελίδες, άδεια, μελλοντικά σχέδια, σύγκριση με άλλα παρόμοια συστήματα.) 1.5 Περί του εγχειριδίου (ΠΡΟΣ ΔΙΟΡΘΩΣΗ) (σε ποιους απευθύνεται, πού θα το βρείτε, άδεια)
4 / 23 Chapter 2 Ξεκινώντας ένα έργο Οι επόμενες ενότητες περιγράφουν τα βήματα που απαιτούνται για να ενσωματώσετε το GTK-Doc στο έργο σας. Υποθέστε ότι εργάζεστε στο έργο 'meep'. Το έργο περιέχει τη βιβλιοθήκη 'libmeep' και την εφαρμογή 'meeper' για τον τελικό χρήστη. 2.1 Δημιουργία ενός σκελετού τεκμηρίωσης Εντός του ριζικού καταλόγου του έργου δημιουργήστε το φάκελο docs/reference (ώστε να μπορείτε να χρησιμοποιήσετε το όνομα docs/help για την τεκμηρίωση του τελικού χρήστη). Συνιστάται να δημιουργήσετε έναν ακόμη υποκατάλογο με το όνομα του πακέτου τεκμηρίωσης. Αυτό δε χρειάζεται για πακέτα που περιλαμβάνουν μόνο μία βιβλιοθήκη. Η δομή θα μπορούσε να έχει ως εξής: Example 2.1 Παράδειγμα δομής καταλόγου meep/ docs/ reference/ libmeep/ meeper/ src/ libmeep/ meeper/ 2.2 Ενσωμάτωση στο autoconf Πολύ απλά! Απλά προσθέτετε μία γραμμή στο σενάριο configure.ac. Example 2.2 Ενσωμάτωση στο autoconf # check for gtk - doc GTK_DOC_CHECK (1.9)
5 / 23 Εκτός του ότι ελέγχει αν είναι διαθέσιμη η απαιτούμενη έκδοση του Gtk-Doc προσθέτει δύο επιλογές ρύθμισης: 1. --with-html-dir=διαδρομη : διαδρομή προς την εγκατεστημένη τεκμηρίωση 2. --enable-gtk-doc : χρήση gtk-doc για την παραγωγή τεκμηρίωσης Important Η προεπιλογή είναι να είναι απενεργοποιημένο το Gtk-Doc! Θυμηθείτε να χρησιμοποιήσετε την επιλογή '--enable-gtk-doc' στην επόμενη εκτέλεση του configure.διαφορετικά εγκαθίσταται η προπαραχθείσα τεκμηρίωση (δυνατότητα χρήσιμη για το χρήστη, αλλά όχι για τον προγραμματιστή). Επίσης, συνιστάται να προσθέσετε την ακόλουθη γραμμή στο σενάριο configure.ac. Επιτρέπει στο gtkdocizeνα αντιγράφει αυτόματα τον ορισμό της μακροεντολής GTK_DOC_CHECK στο έργο σας. Example 2.3 Προετοιμασία για το gtkdocize AC_CONFIG_MACRO_DIR(m4) 2.3 Ενσωμάτωση στο automake Πρώτα αντιγράψτε το Makefile.am από τον υποκατάλογο με τα παραδείγματα των gtkdoc-sources στον κατάλογο της τεκμηρίωσης API του έργου σας (./docs/reference/<package>). Αν έχετε περισσότερα από ένα πακέτα τεκμηρίωσης, επαναλάβετε τη διαδικασία για καθένα από αυτά. Το επόμενο βήμα είναι να τροποποιήσετε τις ρυθμίσεις στο Makefile.am. Πριν από κάθε ρύθμιση υπάρχει ένα σχόλιο που εξηγεί τη χρησιμότητά της. Οι περισσότερες είναι σημαίες που στέλνονται στα αντίστοιχα εργαλεία. Κάθε εργαλείο διαθέτει μια μεταβλητή της μορφής <_ΓΛΥ>_ΠΛΓΣ. Όλα τα εργαλεία υποστηρίζουν την επιλογή --help για την παραγωγή λίστας με τις υποστηριζόμενες παραμέτρους. Μπορείτε, επίσης, να ενεργοποιήσετε το gtk-doc για το distcheckmake target. Απλά προσθέστε τη γραμμή του επόμενου παραδείγματος στο ριζικό Makefile.am: Example 2.4 Ενεργοποίηση του gtk-doc κατά το make distcheck DISTCHECK_CONFIGURE_FLAGS =-- enable -gtk - doc 2.4 Ενσωμάτωση στο autogen Τα περισσότερα έργα διαθέτουν ένα σενάριο autogen.sh για τη δημιουργία υποδομών μετά από το checkout από ένα το σύστημα ελέγχου εκδόσεων (π.χ., cvs). Το Gtk-Doc διαθέτει το εργαλείο gtkdocize, το οποίο μπορεί να χρησιμοποιηθεί για ένα τέτοιο σενάριο. Θα πρέπει να εκτελείται πριν το autoheader, το automake ή το autoconf.
6 / 23 Example 2.5 Εκτέλεση του gtkdocize από το autogen.sh gtkdocize exit 1 Κατά την εκτέλεσή του, το gtkdocize αντιγράφει το gtk-doc.make στο ριζικό κατάλογο του έργου σας (ή στον κατάλογο που ορίζει η επιλογή --docdir). Επίσης, ελέγχει το σενάριο configure για να βρει την κλήση στο GTK_DOC_CHECK. Αρχικά, το gtk-doc δημιουργούσε πρότυπα αρχεία, χρησιμοποιώντας τα αρχεία τεκμηρίωσης που εισήγαγαν οι ίδιοι οι προγραμματιστές. Δυστυχώς, αυτή η προσέγγιση δεν ήταν ιδιαίτερα επιτυχής. Οι τελευταίες εκδόσεις του gtk-doc επιτρέπουν τη λήψη πληροφοριών από τα σχόλια του πηγαίου κώδικα. Από την έκδοση 1.9 και μετά, τα πρότυπα αρχεία δεν είναι πλέον απαραίτητα. Σας συνιστούμε να διατηρείτε την τεκμηρίωση στον κώδικα. Έτσι, το gtkdocize υποστηρίζει πλέον την επιλογή - -flavour no-tmpl που επιλέγει ένα αρχείο make που δεν χρησιμοποιεί καθόλου πρότυπα. Αν δεν έχετε κάνει ποτέ αλλαγές με το χέρι σε αρχεία προτύπων, παρακαλώ αφαιρέστε τον κατάλογο. 2.5 Παραγωγή της τεκμηρίωσης Αφού ολοκληρωθούν τα προηγούμενα βήματα, προχωρήστε στην παραγωγή. Πρώτα, θα πρέπει να εκτελεστεί εκ νέου το autogen.sh. Αν το σενάριο εκτελεί και το configure, προσθέστε την επιλογή --enable-gtk-doc. Διαφορετικά, εκτελέστε εσείς τοconfigure με αυτή την επιλογή. Η πρώτη εκτέλεση του make δημιουργεί μια σειρά από πρόσθετα αρχεία στους καταλόγους της τεκμηρίωσης. Τα σημαντικά είναι τα: <package>.types, <package>-docs.sgml, <package>-sections.txt. Example 2.6 Παραγωγή της τεκμηρίωσης./ autogen.sh --enable -gtk -doc make Τώρα, μπορείτε να εμφανίσετε το docs/reference/<package>/index.html στον περιηγητή σας. Είναι αλήθεια ότι προς το παρόν το αποτέλεσμα είναι μάλλον απογοητευτικό. Μην ανησυχείτε όμως. Στο επόμενο κεφάλαιο θα μάθετε πώς μπορείτε να ζωντανέψετε τις σελίδες σας. 2.6 Ενσωμάτωση σε συστήματα ελέγχου εκδόσεων Ο εμπειρικός κανόνας είναι ότι από τον έλεγχο εκδόσεων πρέπει να περάσουν τα αρχεία που επεξεργαστήκατ εσείς. Συνήθως, πρόκειται για τα αρχεία: <package>.types<package>-docs.sgml<package>-sections. txtmakefile.am
7 / 23 Chapter 3 Τεκμηρίωση του κώδικα Το GTK-Doc χρησιμοποιεί σχόλια με ειδική σύνταξη για την προσθήκη τεκμηρίωσης στον κώδικα. Παράλληλα, ανακαλεί πληροφορίες για τη δομή του έργου σας από άλλες πηγές. Στην επόμενη ενότητα περιέχονται όλες οι λεπτομέρειες για τη σύνταξη αυτών των σχολίων. Τοποθέτηση τεκμηρίωσης Στο παρελθόν, η τεκμηρίωση έπρεπε να συμπληρώνεται σε αρχεία του καταλόγου tmpl. Αυτή η προσέγγιση εμφανίζει το μειονέκτημα ότι οι πληροφορίες δεν ενημερώνονται συχνά, καθώς και το ότι προκύπτουν περιοδικές συγκρούσεις με τα συστήματα ελέγχου εκδόσεων. Για να αποφύγετε αυτά τα προβλήματα, σας προτείνουμε να ενσωματώνετε την τεκμηρίωση στον πηγαίο κώδικα. Αυτή είναι και η μόνη μέθοδος που θα περιγράψουμε σε αυτό το εγχειρίδιο. 3.1 Σχόλια τεκμηρίωσης Ένα σχόλιο πολλαπλών γραμμών που διαθέτει ένα επιπλέον '*' στην αρχή αποτελεί ένα μπλοκ τεκμηρίωσης που λαμβάνεται υπόψη από τα εργαλεία του Gtk-Doc. Example 3.1 Μπλοκ σχολίου Gtk-Doc /** * identifier: * documentation... */ Το 'αναγνωριστικό' είναι μία γραμμή που περιέχει το όνομα του στοιχείου στο οποίο αναφέρεται το σχόλιο. Η σύνταξή του εξαρτάται από τον τύπο του στοιχείου. (ΜΕΛΛΟΝΤΙΚΑ: να προστεθεί πίνακας με τα αναγνωριστικά) Το μπλοκ της 'τεκμηρίωσης' επίσης διαφέρει ανάλογα με τον τύπο συμβόλου. Για τους τύπους συμβόλων που δέχονται παραμέτρους (π.χ. συναρτήσεις και μακροεντολές) προηγείται η περιγραφή των παραμέτρων και ακολουθεί μια κενή γραμμή (μόνο '*'). Ακολουθεί η λεπτομερής περιγραφή. Όλες οι γραμμές (εκτός από τον κώδικα του προγράμματος και τις ενότητες CDATA) που περιέχουν μόνο ένα ' *' (διάστημααστερίσκος) μετατρέπονται σε αλλαγές παραγράφου. Αν δεν επιθυμείτε αλλαγή παραγράφου, χρησιμοποιήσ το ' * ' (διάστημα-αστερίσκος-διάστημα-διάστημα).
8 / 23 Ένα πλεονέκτημα της χρήσης υπερκειμένου αντί για απλό κείμενο είναι η δυνατότητα προσθήκης συνδέσμων. Ωστόσο, η χρήση της σωστής σύνταξης για τη δημιουργία συνδέσμων μπορεί να είναι αρκετά κουραστική διαδικασία. Το Gtk-Doc σας βοηθάει, παρέχοντάς σας μια σειρά από χρήσιμες συντμήσεις. Χρησιμοποιήστε τη γραφή function() για αναφορές σε συναρτήσεις ή μακροεντολές που δέχονται ορίσματα. Χρησιμοποιήστε τη γραφή @param για να αναφερθείτε σε παραμέτρους. Επίσης, χρησιμοποιήστε αυτή τη γραφή για να αναφερθείτε σε παραμέτρους άλλων συναρτήσεων, σχετικών με την περιγραφόμενη. Χρησιμοποιήστε τη γραφή %constant για να αναφερθείτε σε σταθερές, π.χ. %G_TRAVERSE_LEAFS. Χρησιμοποιήστε τη γραφή #symbol για να αναφερθείτε σε άλλους τύπους συμβόλων, π.χ. δομές, αριθμήσεις και μακροεντολές που δε δέχονται ορίσματα. Χρησιμοποιήστε τη γραφή #Object::signal για να αναφερθείτε σε ένα σήμα GObject Χρησιμοποιήστε τη γραφή #Object::property για να αναφερθείτε σε μία ιδιότητα GObject Χρησιμοποιήστε τη γραφή #Struct.field για να αναφερθείτε σε ένα πεδίο μιας δομής. Tip Αν θέλετε να χρησιμοποιήσετε τους ειδικούς χαρακτήρες '()', '@', '%', ή '#' στην τεκμηρίωση, χωρίς να φοβάστε ότι θα τους αλλάξει το gtk-doc, μπορείτε να χρησιμοποιήσετε τις οντότητες XML "(", ")", "@", "%" και "#", αντίστοιχα, ή να χρησιμοποιήσετε την ανάποδη κάθετο '\' ως χαρακτήρα διαφυγής. Το DocBook σας προσφέρει και άλλες δυνατότητες πέρα από τους συνδέσμους. Μπορεί να περιλαμβάνει λίστες, πίνακες και παραδείγματα. Για να επιτρέπεται η χρήση ετικετών SGML/XML στα σχόλια τεκμηρίωσης, θα πρέπει να έχει προστεθεί η επιλογή --sgml-mode στη μεταβλητή MKDB_OPTIONS του Makefile.am. Tip Όπως αναφέρθηκε και προηγουμένως. το Gtk-Doc αναλαμβάνει την τεκμηρίωση του δημόσιου API. Άρα, δεν μπορεί να γραφτεί τεκμηρίωση για στατικά σύμβολα. Παρόλα αυτά, συνιστάται ο σχολιασμός και αυτών των συμβόλων, γιατί βοηθά στην κατανόηση του κώδικα. Σας προτείνουμε λοιπόν να τα σχολιάζετε χρησιμοποιώντας κανονικά σχόλια (χωρίς το δεύτερο '*' στην πρώτη γραμμή). Αν αργότερα χρειαστεί να μετατραπεί η συνάρτηση σε δημόσια, το μόνο που θα πρέπει να γίνει είναι να προστεθεί άλλο ένα '*' στο μπλοκ του σχολίου, και να εισαχθεί το όνομα του συμβόλου στην κατάλληλη θέση του αρχείου ενοτήτων. 3.2 Ενότητες τεκμηρίωσης Κάθε ενότητα της τεκμηρίωσης περιέχει πληροφορίες για μία κλάση ή ένα module. Ως εισαγωγή, μπορείτε να γράψετε ένα μπλοκ σχολίου ενότητας. Η σύντομη αυτή περιγραφή χρησιμοποιείται και για τον πίνακα περιεχομένων.
9 / 23 Example 3.2 Μπλοκ σχολίου ενότητας /** * SECTION: meepapp * @short_description: the application class * @see_also: # MeepSettings * @stability: Stable * @include: meep/ app.h * * The application class handles... */ @short_description Περιγραφή της ενότητας σε μία γραμμή, η οποία θα εμφανίζεται, στη συνέχεια, μετά από τους συνδέσμους του πίνακα περιεχομένων και στην αρχή της σελίδας της ενότητας. @see_also Λίστα συμβόλων σχετικών με αυτή την ενότητα. @stability Άτυπη περιγραφή του επιπέδου σταθερότητας του συγκεκριμένου API. Σας συνιστούμε να χρησιμοποιείται έναν από τους ακόλουθους όρους: Σταθερή - Μια σταθερή διεπαφή επιτρέπει σε τρίτους να αναπτύσσουν εφαρμογές για τις διεπαφές αυτές, να τις δημοσιεύουν και να είναι βέβαιοι ότι οι εφαρμογές θα τρέχουν σε όλες τις ελάσσονες εκδόσεις του προϊόντος (οι οποίες θα είναι μεταγενέστερες της διεπαφής και θα ανήκουν στην ίδια μείζονα έκδοση). Ακόμη και όταν πρόκειται για μείζονες νέες εκδόσεις, οι ασυμβατότητες αναμένεται να είναι σπάνιες και να οφείλονται σε σοβαρούς λόγους. Ασταθής - Ασταθείς είναι οι πειραματικές ή μεταβατικές διεπαφές. Συνήθως χρησιμοποιούνται για να παρέχουν σε τρίτους πρώιμη πρόσβαση σε νέες ή διαρκώς εξελισσόμενες τεχνολογίες, ή ως ενδιάμεσες λύσεις για προβλήματα για τα οποία αναμένεται μια γενικότερη λύση. Δεν υφίσταται καμία εγγύηση συμβατότητας μεταξύ μιας ελάσσονας έκδοσης και της επόμενης. Ιδιωτική - Διεπαφή που μπορεί να χρησιμοποιηθεί εντός της στοίβας του GNOME, αλλά δε διαθέτει τεκμηρίωση που να απευθύνεται στους τελικούς χρήστες. Τέτοιου είδους συναρτήσεις μπορούν να χρησιμοποιούνται μόνο στο πλαίσιο σαφώς καθορισμένων και τεκμηριωμένων διαδικασιών. Εσωτερική - Μια διεπαφή που είναι εσωτερική σε ένα module δεν απαιτεί την ύπαρξη τεκμηρίωσης για τον τελικό χρήστη. Οι συναρτήσεις που δεν περιέχουν τεκμηρίωση θεωρείται ότι είναι εσωτερικές. @include Αρχεία #include που εμφανίζονται στη συνοπτική παρουσίαση των ενοτήτων (λίστα αρχείων που χωρίζονται με κόμματα), αντικαθιστώντας την καθολική τιμή στο αρχείο ενότητας ή στη γραμμή εντολών. Πρόκειται για προαιρετικό στοιχείο. ΠΡΟς ΔΙΟΡΘΩΣΗ @title, προσθέτει τον τίτλο σε νέα αρχεία ενοτήτων, αλλά μάλλον θα πρέπει να καταργηθεί στο μέλλον. Tip Για να μη χρειαστεί να κάνετε εκ νέου μεταγλώττιση μετά από αλλαγές στην τεκμηρίωση, σας προτείνουμε να ενσωματώνετε την τεκμηρίωση των ενοτήτων στο αρχείο του πηγαίου κώδικα, όπου αυτό είναι δυνατό. 3.3 Τεκμηρίωση συμβόλων Κάθε σύμβολο (συνάρτηση, μακροεντολή, δομή, αρίθμηση, σήμα, ιδιότητα) τεκμηριώνεται σε ξεχωριστό μπλοκ. Η καταλληλότερη θέση για τα μπλοκ είναι δίπλα στους ορισμούς των συμβόλων, γιατί
10 / 23 διευκολύνει το έργο συγχρονισμού. Επομένως, η τεκμηρίωση των συναρτήσεων συνήθως βρίσκεται στο αρχείο του πηγαίου κώδικα, ενώ των μακροεντολών, δομών και αριθμήσεων στο αρχείο κεφαλίδας. Example 3.3 Μπλοκ σχολίου συνάρτησης /** * function_name: * @par1: description of parameter 1. These can extend over more than * one line. * @par2: description of parameter 2 * * 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. */ Returns: Παράγραφος που περιγράφει το επιστρεφόμενο αποτέλεσμα. Deprecated: Παράγραφος που ενημερώνει ότι θα πρέπει να σταματήσει η χρήση της συνάρτησης. Η περιγραφή θα πρέπει να παραπέμπει τον αναγνώστη στο νέο API. Since: Από ποια έκδοση του κώδικα είναι διαθέσιμο το API. Το Gtk-doc θεωρεί ότι όλα τα σύμβολα (μακροεντολές, συναρτήσεις, κτλ.) που ξεκινούν με '_' είναι ιδιωτικά και τα μεταχειρίζεται σαν στατικές συναρτήσεις. (ΠΡΟΣ ΔΙΟΡΘΩΣΗ) (σταθερότητα) (glib-enums,...) Example 3.4 Μπλοκ σχολίου ιδιότητας /** * SomeWidget:some - property: * * Here you can document a property. */ g_object_class_install_property ( object_class, PROP_SOME_PROPERTY,...); Example 3.5 Μπλοκ σχολίου σήματος /** * 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[ FOOBARIZE] = g_signal_new (" foobarize",...
11 / 23 Example 3.6 Μπλοκ σχολίου δομής /** * FooWidget: * @bar: some # gboolean * * This is the best widget, ever. */ typedef struct _FooWidget { GtkWidget parent; /*< public >*/ gboolean bar; } FooWidget; 3.4 Χρήσιμες ετικέτες DocBook Ακολουθούν ορισμένες ετικέτες DocBook, ιδιαίτερα χρήσιμες για την τεκμηρίωση του κώδικα. Σύνδεσμος προς άλλη ενότητα της τεκμηρίωσης: <link linkend =" glib -Hash - Tables">Hash Tables </ link > Ο προορισμός είναι το id SGML στο πρώτο στοιχείο της σελίδας στην οποία παραπέμπει ο σύνδεσμος. Για τις περισσότερες σελίδες είναι το ("gtk", "gdk", glib"), ακολουθούμενο από τον τίτλο της σελίδας ("Πίνακες Hash "). Για τα γραφικά συστατικά είναι το όνομα της κλάσης. Τα διαστήματα και τα '_' μετατρέπονται σε '-' για να υπάρχει συμμόρφωση με το SGML. Αναφορά σε εξωτερική συνάρτηση, π.χ. τυποποιημένη συνάρτηση C: <function >... </ function > Συμπερίληψη παραδειγμάτων κώδικα: <example > <title >Using a GHashTable.</ title > <programlisting >... </ programlisting > </example > ή, ενδεχομένως, για πολύ σύντομο κώδικα που δεν χρειάζεται τίτλο: <informalexample > <programlisting >... </ programlisting > </ informalexample >. Στην τελευταία περίπτωση το gtk-doc υποστηρίζει, επίσης, τη σύντμηση: [... ] Συμπερίληψη λιστών με κουκίδες:
12 / 23 <itemizedlist > <listitem > <para >... </para > </ listitem > <listitem > <para >... </para > </ listitem > </ itemizedlist > Συμπερίληψη σημειώσεων που ξεχωρίζουν από το υπόλοιπο κείμενο: <note > <para > Make sure you free the data after use. </para > </note > Αναφορά σε τύπο: <type >unsigned char </ type > Αναφορά σε εξωτερική δομή (που δεν περιγράφεται στην τεκμηρίωση GTK): <structname >XFontStruct </ structname > Αναφορά σε πεδίο μιας δομής: <structfield >len </ structfield > Αναφορά σε όνομα κλάσης. Μία δυνατότητα είναι το : <classname >GtkWidget </ classname >, αλλά μάλλον θα χρησιμοποιήσετε το #GtkWidget (για αυτόματη δημιουργία συνδέσμου προς τη σελίδα GtkWidget, δείτε τις συντμήσεις). Χρήση έντονων χαρακτήρων: <emphasis >This is important </ emphasis > Ονόματα αρχείων: <filename >/ home/ user/ documents </ filename >
13 / 23 Chapter 4 Συμπλήρωση επιπλέον αρχείων Υπάρχουν ορισμένα επιπλέον αρχεία που πρέπει να ενημερώνονται παράλληλα με τα σχόλια εντός του πηγαίου κώδικα: <package>.types, <package>-docs.sgml, <package>-sections.txt. 4.1 Επεξεργασία του αρχείου types Αν η βιβλιοθήκη ή η εφαρμογή σας περιέχει GtkObjects/GObjects, θα θέλετε να εμφανίζονται στην τεκμηρίωση τα σήματα, τα ορίσματα, οι παράμετροι τους, καθώς και η θέση τους στην ιεραρχία. Για να το πετύχετε, απλά καταγράψτε όλες τις συναρτήσεις xxx_get_type μαζί με τα include τους στο αρχείο <package>.types. Example 4.1 Υπόδειγμα αποσπάσματος αρχείου 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. Αν προτιμήσετε αυτή την προσέγγιση, θα πρέπει να μη συμπεριλάβετε το αρχείο types ούτε στη διανομή ούτε στον έλεγχο εκδόσεων. 4.2 Επεξεργασία κύριου εγγράφου (master) Το Gtk-Doc παράγει τεκμηρίωση σε μορφή SGML/XML DocBook. Κατά την επεξεργασία των σχολίων εντός του πηγαίου κώδικα, τα εργαλεία του Gtk-Doc παράγουν μία σελίδα τεκμηρίωσης ανά κλάση ή module, η οποία αποθηκεύεται ως ξεχωριστό αρχείο. Το κύριο έγγραφο συμπεριλαμβάνει αυτά τα αρχεία και τα ταξινομεί. Αν και το Gtk-Doc παράγει αυτόματα ένα πρότυπο κύριο έγγραφο, δεν το τροποποιεί κατά τις επόμενες εκτελέσεις. Αυτό σημαίνει ότι έχετε τη δυνατότητα να αλλάξετε τη δομή της τεκμηρίωσης. Μπορείτε να ομαδοποιήσετε κάποιες σελίδες ή να προσθέσετε νέες. Το Gtk-Doc διαθέτει πλέον μια σουίτα
14 / 23 για δοκιμές, η οποία μπορεί να παράξει εκ νέου το κύριο έγγραφο. Συνιστάται να επαναλαμβάνετε τακτικά αυτή τη διαδικασία, για να διαπιστώνετε αν έχουν προστεθεί νέα στοιχεία. Tip Μη δημιουργείτε νέα έγγραφα για τους οδηγούς εκμάθησης (tutorials). Απλά προσθέστε τους ως επιπλέον κεφάλαια, δηλαδή ενσωματώστε απευθείας τον οδηγό εκμάθησης για μια βιβλιοθήκη στην τεκμηρίωση API. Το πλεονέκτημα είναι ότι έτσι διευκολύνεται η διαδικασία δημιουργίας συνδέσμων από τον οδηγό εκμάθησης προς την τεκμηρίωση των συμβόλων. Επίσης, έτσι καθίσταται πιθανότερη η ενημέρωση του οδηγού μαζί με τη βιβλιοθήκη. Ποιες είναι λοιπόν οι αλλαγές που πρέπει να γίνουν στο κύριο έγγραφο; Διευκρινίζουμε ότι πρόκειται για λίγες μόνο αλλαγές σε ορισμένα placeholders (κείμενα εντός αγκυλών). Example 4.2 Κεφαλίδα κύριου εγγράφου <bookinfo > <title >MODULENAME Reference Manual </ title > <releaseinfo > for MODULENAME [ VERSION] The latest version of this documentation can be found on- line at <ulink role=" online - location" url=" http://[ SERVER]/ MODULENAME/ index. html">http://[ SERVER]/ MODULENAME/</ ulink >. </ releaseinfo > </ bookinfo > <chapter > <title >[ Insert title here]</ title > 4.3 Επεξεργασία αρχείου ενοτήτων Το αρχείο ενοτήτων χρησιμεύει στην οργάνωση της τεκμηρίωσης που παράγεται από το Gtk-Doc. Εδώ διευκρινίζεται σε ποιο module ή κλάση ανήκει κάθε σύμβολο και αποφασίζεται το αν θα είναι δημόσιο ή ιδιωτικό. Το αρχείο ενοτήτων είναι ένα αρχείο απλού κειμένου που χρησιμοποιεί σύνταξη με ετικέτες, παρόμοια με την xml. Οι κενές γραμμές αγνοούνται, ενώ οι γραμμές που ξεκινούν με # αποτελούν σχόλια. Η ετικέτα <FILE>... </FILE> χρησιμποιείται για να δηλώσει το όνομα του αρχείου χωρίς την επέκταση. Για παράδειγμα, το '<FILE>gnome-config</FILE>' σημαίνει ότι οι δηλώσεις των ενοτήτων θα βρίσκονται στο πρότυπο αρχείο tmpl/gnome-config.sgml, το οποίο θα μετατραπεί στο αρχείο Doc- Book SGML sgml/gnome-config.sgml ή DocBook XML xml/gnome-config.xml. (Το όνομα του αρχείου html πηγάζει από το όνομα του module και τον τίτλο της ενότητας, ή από το όνομα της κλάσης του gobject, αλλά με πεζούς χαρακτήρες). Η ετικέτα <TITLE>... </TITLE> χρησιμοποιείται για να ορίσει τους τίτλους των ενοτήτων. Χρησιμεύει μόνο πριν τη δημιουργία των προτύπων, καθώς ο τίτλος που περιέχεται στα αρχεία προτύπων αντικαθιστά αυτούς τους τίτλους. Μπορείτε να ομαδοποιείτε τα στοιχεία των ενοτήτων χρησιμοποιώντας την ετικέτα <SUBSECTION>. Με την τωρινή της μορφή, προσθέτει μία κενή γραμμή μεταξύ υποενοτήτων στη σύνοπτική παρουσίαση. Μπορείτε, επίσης, να χρησιμοποιήσετε την ετικέτα <SUBSECTION Standard> για κλασικές δηλώσεις GObject (π.χ. συναρτήσεις όπως η g_object_get_type και μακροεντολές όπως οι G_OBJECT(), G_IS_OBJECT( κτλ.). Προς το παρόν, αυτές οι δηλώσεις μένουν εκτός τεκμηρίωσης. Τέλος, μπορείτε να χρησιμοποιήσετε την ετικέτα <SUBSECTION Private> για ιδιωτικές δηλώσεις που δεν πρόκειται να εμφανιστούν στην