Πώς λειτουργεί το 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 μπορεί επίσης να χρησιμοποιηθεί για να κάνει δυναμική αναζήτηση σε μια βιβλιοθήκη για ενδεχόμενες υποκλάσεις GtkObject. Αποθηκεύει τις πληροφορίες για τη θέση κάθε αντικειμένου στην ιεραρχία κλάσεων, καθώς και για τα ορίσματα και σήματα GTK που περιέχει.

  3. Δημιουργία "πρότυπων" αρχείων Το gtkdoc-mktmpl παράγει μια σειρά από αρχεία στον υποκατάλογο tmpl/, χρησιμοποιώντας τις πληροφορίες που συλλέχθηκαν κατά το πρώτο στάδιο. (Σημειώστε ότι μπορεί να εκτελεστεί περισσότερες από μία φορές. Προσπαθεί να διασφαλίσει ότι δεν χάνεται ποτέ και κανενός είδους τεκμηρίωση.)

    Από την έκδοση 1.9 και μετά, τα πρότυπα αρχεία δεν είναι πλέον απαραίτητα. Σας συνιστούμε να διατηρείτε την τεκμηρίωση στον κώδικα. Το gtkdocize υποστηρίζει πλέον την επιλογή --flavour no-tmpl η οποία επιλέγει ένα αρχείο makefile που δεν χρησιμοποιεί καθόλου πρότυπα tmpl. Αν δεν έχετε κάνει ποτέ αλλαγές με το χέρι σε αρχεία προτύπων tmpl, παρακαλώ αφαιρέστε τον κατάλογο (π.χ. από ένα σύστημα ελέγχου εκδόσεων).

  4. Παραγωγή SGML/XML και HTML/PDF. Το gtkdoc-mkdb μετατρέπει τα αρχεία προτύπων tmpl σε αρχεία SGML ή XML και τα τοποθετεί στους υποκαταλόγουςsgml/ ή xml/. Αν ο πηγαίος κώδικας περιέχει τεκμηρίωση συναρτήσεων εντός ειδικών μπλοκ σχολίων, τα σχόλια συγχωνεύονται σε αυτό το στάδιο. Αν δεν υπάρχουν αρχεία προτύπων tmpl, τότε χρησιμοποιούνται μόνο τα έγγραφα που προέκυψαν από τον πηγαίο κώδικα και τα δεδομένα της ενδοσκόπησης. Σας συνιστούμε να χρησιμοποιήσετε το βιβλίο τεκμηρίωσης XML.

    Το gtkdoc-mkhtml μετατρέπει τα αρχεία SGML/XML σε αρχεία HTML που τοποθετούνται στον υποκατάλογο html/. Ομοίως το gtkdoc-mkpdf μετατρέπει τα αρχεία SGML/XML σε ένα αρχείο PDF που ονομάζεται <package>.pdf.

    Τα αρχεία στους καταλόγους sgml/, xml/ και html/ αντικαθίστανται αυτόματα. Επομένως, δεν πρέπει να τα αλλάζετε με το χέρι.

  5. Διόρθωση παραπομπών μεταξύ εγγράφων Μετά την εγκατάσταση των αρχείων HTML, μπορείτε να εκτελέσετε το gtkdoc-fixxref για να διορθώσετε τυχόν παραπομπές σε διαφορετικά έγγραφα. Για παράδειγμα, η τεκμηρίωση του GTK+ περιέχει πολλές παραπομπές σε τύπους που επεξηγούνται στο εγχειρίδιο του GLib. Όταν ετοιμάζετε πακέτα κώδικα για διανομή, μπορείτε να χρησιμοποιείτε το gtkdoc-rebase για να μετατρέπετε όλους τους εξωτερικούς συνδέσμους σε διαδικτυακούς συνδέσμους. Κατά την εγκατάσταση της τεκμηρίωσης που περιλαμβάνεται στο διανεμηθέντα κώδικα (παράγεται αυτόματα), η ίδια εφαρμογή θα προσπαθήσει να μετατρέψει ξανά τους συνδέσμους σε τοπικούς συνδέσμους (προς τις τοποθεσίες όπου είναι εγκατεστημένη η τεκμηρίωση).