Πώς λειτουργεί το GTK-Doc;
Το GTK-Doc χρησιμοποιεί την τεκμηρίωση συναρτήσεων που έχει συμπεριληφθεί στα πηγαία αρχεία (εντός μπλοκ σχολίων με ειδική μορφή), ή την τεκμηρίωση που έχει προστεθεί στα πρότυπα αρχεία που χρησιμοποιεί το GTK-Doc (σημειώστε όμως ότι το GTK-Doc παράγει τεκμηρίωση μόνο για τις συναρτήσεις που δηλώνονται σε αρχεία κεφαλίδας· δεν παράγει τεκμηρίωση για στατικές συναρτήσεις).
Το GTK-Doc αποτελείται από μια σειρά δέσμης ενεργειών perl, καθένα από τα οποία είναι υπεύθυνο για διαφορετικό στάδιο της όλης διαδικασίας.
Η διαδικασία περιλαμβάνει 5 κύρια στάδια:
-
Συγγραφή της τεκμηρίωσης Ο συγγραφέας συμπληρώνει τα πηγαία αρχεία με τεκμηρίωση για όλες τις συναρτήσεις, μακροεντολές, ενώσεις κτλ. (Στο παρελθόν, οι πληροφορίες συμπληρώνονταν σε πρότυπα αρχεία που παράγονταν αυτόματα, αλλά αυτός ο τρόπος δεν συνιστάται πλέον.)
-
Συλλέγοντας πληροφορίες για τον κώδικα. Το gtkdoc-scan σαρώνει τα αρχεία κεφαλίδων του κώδικα ψάχνοντας για δηλώσεις συναρτήσεων, μακροεντολές, enums, δομές και ενώσεις. Δημιουργεί το αρχείο <module>-decl-list.txt που περιέχει μια λίστα με τις δηλώσεις, και τις τοποθετεί σε ενότητες αναλόγως με το αρχείο κεφαλίδας στο οποίο βρίσκονται. Από την πρώτη εκτέλεση του προγράμματος το αρχείο αντιγράφεται στο <module>-sections.txt. Ο συγγραφέας μπορεί να τακτοποιεί τις ενότητες και τη σειρά των δηλώσεων, για να παραγάγει το επιθυμητό τελικό αποτέλεσμα. Το δεύτερο αρχείο δημιουργεί το <module>-decl.txt. Το αρχείο αυτό περιέχει τις πλήρεις δηλώσεις που βρέθηκαν από τον σαρωτή.Αν για κάποιο λόγο θέλετε μερικά σύμβολα να εμφανίζονται στην τεκμηρίωση, όπου η πλήρης δήλωση δεν μπορεί να βρεθεί από τον σαρωτή, ή πρέπει να εμφανίζεται διαφορετικά, μπορεί κάποιος να τοποθετήσει οντότητες παρόμοιες με αυτές <module>-decl.txt στο αρχείο <module>-overrides.txt.
Το gtkdoc-scanobj μπορεί επίσης να χρησιμοποιηθεί για να κάνει δυναμική αναζήτηση σε μια βιβλιοθήκη για ενδεχόμενες υποκλάσεις GObject. Αποθηκεύει τις πληροφορίες για τη θέση κάθε αντικειμένου στην ιεραρχία κλάσεων καθώς και για τις ιδιότητες και σήματα GObject που περιέχει.
Το gtkdoc-scanobj δεν πρέπει να χρησιμοποιείται πλέον. Χρειαζόταν στο παρελθόν όταν το GObject ήταν ακόμα GtkObject μέσα στη gtk+.
-
Δημιουργία του XML και του HTML/PDF. Το gtkdoc-mkdb μετατρέπει τα αρχεία προτύπων σε αρχεία XML στον υποκατάλογο xml/. Αν ο πηγαίος κώδικας περιέχει τεκμηρίωση συναρτήσεων, χρησιμοποιώντας τις ειδικές ομάδες σχολίων, συγχωνεύεται εδώ. Αν δεν υπάρχουν χρησιμοποιούμενα αρχεία tmpl, διαβάζει μόνο έγγραφα από τα δεδομένα πηγών και αυτοελέγχου.
Το gtkdoc-mkhtml μετατρέπει τα αρχεία XML σε αρχεία HTML στον υποκατάλογο html/. Ομοίως, το gtkdoc-mkpdf μετατρέπει τα αρχεία XML σε ένα έγγραφο PDF που ονομάζεται <package>.pdf.
Τα αρχεία στους καταλόγους xml/ και html/ αντικαθίστανται πάντα. Επομένως, δεν πρέπει να τα επεξεργάζεστε απευθείας.
-
Διόρθωση διασταυρούμενων παραπομπών μεταξύ εγγράφων Μετά την εγκατάσταση των αρχείων HTML, μπορείτε να εκτελέσετε το gtkdoc-fixxref για να διορθώσετε τυχόν διασταυρούμενες παραπομπές σε διαφορετικά έγγραφα. Για παράδειγμα, η τεκμηρίωση του GTK+ περιέχει πολλές παραπομπές σε τύπους που επεξηγούνται στο εγχειρίδιο του GLib. Όταν ετοιμάζετε πακέτα κώδικα για διανομή, μπορείτε να χρησιμοποιείτε το gtkdoc-rebase για να μετατρέπετε όλους τους εξωτερικούς συνδέσμους σε διαδικτυακούς συνδέσμους. Κατά την εγκατάσταση της τεκμηρίωσης που περιλαμβάνεται στον διανεμηθέντα κώδικα (παράγεται αυτόματα), η ίδια εφαρμογή θα προσπαθήσει να μετατρέψει ξανά τους συνδέσμους σε τοπικούς συνδέσμους (προς τις τοποθεσίες όπου είναι εγκατεστημένη η τεκμηρίωση).