Καπελώνης Κωστής kkapelon _AT_ freemail.gr(mailto:kkapelonSPAM@SUXfreemail.gr) Ιουλ 2002
Σε αυτό το άρθρο γίνεται μία εισαγωγή στο επίσημο εργαλείο για documentation της GNU, το σύστημα Texinfo. Απευθύνεται σε προγραμματιστές που έχουν τελειώσει την κατασκευή μιας εφαρμογής κονσόλας και επιθυμούν να ενσωματώσουν βοήθεια σε αυτή.
1. Εισαγωγή
2. Οι επιλογές σας
3. Το texinfo από την μεριά του χρήστη.
4. texinfo vs manpages
5. Η φιλοσοφία του texinfo
6. To πιο απλό Texinfo αρχείο
7. Ένα μεγαλύτερο έγγραφο
8. Συγγραφή του κυρίως κειμένου.
9. Emacs shortcuts
10. Επίλογος
Δεν νομίζω ότι χρειάζεται να επαναλάβω ρήσεις για το Documentation και το sex. Μεγάλα παιδιά είστε, οπότε ξέρετε ότι μεγάλο βάρος στην ποιότητα και την ευχρηστία μιας εφαρμογής, έχει ΚΑΙ η βοήθεια/τεκμηρίωση που την συνοδεύει.
Δυστυχώς αρκετές φορές η βοήθεια ενός προγράμματος παραμελείται από τους προγραμματιστές της. Όλοι μας έχουμε συναντήσει προγράμματα που ενώ ήταν λειτουργικά και μπορούσαν να εκπληρώσουν το σκοπό τους, είχαν ελλιπές ή ακόμα και μηδαμινό documentation.
Ειδικά στον χώρο του ανοιχτού λογισμικού (open source) τα πράγματα δεν είναι πολύ καλά. Άπειρες επιλογές με περίεργα ονόματα σε γραφικά προγράμματα, ή undocumented παράμετροι σε προγράμματα κονσόλας (command line arguments) είναι καθημερινό φαινόμενο. Δεν μου αρέσει να ενεργοποιώ επιλογές που απλά είδα στο δίκτυο ή άκουσα από φίλους ότι "έτσι λειτουργεί". Οι μέρες του voodoo πρέπει να μείνουν επιτέλους στην ιστορία.
Τώρα θα πούνε μερικοί, "σιγά ρε φίλε! Use the source, Luke!". Μα καλά είμαστε σοβαροί; Είμαστε στο 2000+ και θα πρέπει να ανοίξω τον πηγαίο κώδικα του προγράμματος για να δω τι κάνει;Δεν το δέχομαι αυτό. Καλή εφαρμογή = καλός κώδικας + καλή τεκμηρίωση.
Γράφω λοιπόν αυτό το άρθρο έτσι ώστε όταν τελειώσετε το προγραμματιστικό σας αριστούργημα, με την τέλεια δομημένη εσωτερική αρχιτεκτονική, την ταχύτατη μεταφορά πληροφορίας ανάμεσα στα διάφορα μέρη του, τις βελτιστοποιημένες στο έπακρο εσωτερικές ρουτίνες και τις πολύπλοκες δομές δεδομένων,όταν πιστέψετε ότι έχετε βάλει τάξη στο χάος ;-), όταν νιώσετε ένας μικρός θεός και βιώσετε το θαύμα της δημιουργίας, να μην ξεχάσετε και τον παράγοντα τεκμηρίωση.
Αν η εφαρμογή που γράφετε έχει γραφικό μέρος και ανήκει σε κάποιο από τα δύο γνωστά περιβάλλοντα εφαρμογών (desktop environments), δεν χρειάζεται να συνεχίσετε την ανάγνωση. Απλά δείτε τις αντίστοιχες σελίδες που εξηγούν πως πρέπει να είναι το documentation της εφαρμογής σας. Λογικά θα πρέπει να γράψετε ένα αρχείο SGML Docbook το οποίο θα πρέπει να έχει μια συγκεκριμένη μορφή.
Αν η εφαρμογή σας είναι απλά γραφική και δεν υπάρχει "σωστός" τρόπος για την εισαγωγή βοήθειας, προτιμήστε το δοκιμασμένο Latex. Βάζετε το output σε html στο site του προγράμματος για online αναζήτηση, ενώ μαζί με το ίδιο το πρόγραμμα ενσωματώνετε τα ps και pdf αρχεία. Αυτό είναι απλά μία πρόταση. Είναι στην κρίση σας να επιλέξετε.
Εδώ θα μιλήσουμε για την περίπτωση όπου το πρόγραμμα σας δεν έχει γραφικό περιβάλλον, αλλά εκτελείται σε περιβάλλον γραμμής εντολών. Αν είναι πολύ απλό στην χρήση, και με λίγες παραμέτρους τα πράγματα είναι εύκολα. Απλά βάλτε στο -h/--help του να εμφανίζεται κάθε δυνατή παράμετρος με μία μικρή εξήγηση. Σε αυτήν την περίπτωση μπορείτε να ακολουθήσετε και το GNU style για τις παραμέτρους όπου κάθε μία έχει ένα σύντομο όνομα για τους έμπειρους χρήστες (πχ -b) και ένα πιο μεγάλο για τους αρχάριους (πχ --buffer-size).
Αν όμως δεν ισχύει κάτι τέτοιο οφείλετε να δώσετε ξεχωριστό documentation. Αυτό θα βοηθήσει τόσο τους έμπειρους χρήστες όταν θα θελήσουν να "ξεζουμίσουν" το πρόγραμμα σας, αλλά και τους αρχάριους που αρέσκονται στο να βρίσκουν κάπου "μαζεμένη" την βοήθεια ενός προγράμματος.
Ας δούμε ένα παράδειγμα. Έστω ότι θέλετε να μάθετε τα πάντα για το GNU flex.
Αρχικά μπορείτε να ανοίξετε ένα τερματικό στο pc σας και να δώσετε "info flex" [εικόνα][1]. Πατώντας το πλήκτρο space μπορείτε να διαβάσετε όλο το manual από την αρχή μέχρι το τέλος. Με τα πλήκτρα (p)revious, (n)ext kai (u)p μπορείτε να περιπλανηθείτε στους κόμβους του. Μπορείτε επίσης να φορτώσετε τον Emacs 21+ και με Ctrl-h i ή από το μενού "Help->manuals->Browse manuals with info" να δείτε όλα τα manuals που έχετε στο σύστημα σας σε texinfo format (το ίδιο γίνεται και αν γράψετε σκέτο "info" στην γραμμή εντολών). Μόλις πάτε στο manual του flex ισχύουν τα ίδια keyboard shortcuts. Επίσης έχετε όμορφα κουμπιά στην toolbar, ενώ μπορείτε να κάνετε και μεσαίο κλικ στα links που βλέπετε [εικόνα][2].
Αν επιθυμείτε κάτι πιο συμβατικό μπείτε στο gnu.org (manuals section)[3] όπου μπορείτε είτε να κατεβάσετε ολόκληρο το manual σε Postscript μορφή σε Postscript μορφή[4] για να το τυπώσετε ή μπορείτε να το διαβάσετε Online σε απλή και γρήγορη HTML μορφή[5]
3: http://www.gnu.org/manual/manual.html
4: http://www.gnu.org/manual/flex-2.5.4/ps/flex.ps.gz
5: http://www.gnu.org/manual/flex-2.5.4/html_node/flex_toc.html
Τέλος ακόμα και αν έχετε GNOME η KDE βάζοντας info://foo στην γραμμή διεύθυνσης, μπορείτε να δείτε τα infopages της εφαρμογής foo. (Αν και νομίζω ότι στις τελευταίες εκδόσεις KDE και GNOME υπάρχει στο help ξεχωριστή επιλογή "browse info pages" όπου βρίσκονται όλα τα manuals του συστήματος.)
Τώρα πια θα πρέπει να έχετε αναγνωρίσει την άνεση που προσφέρει το texinfo. Browsing σε κονσόλα χρήσιμο για τους servers σας, ενσωμάτωση με τον emacs, γνώριμη html μορφή και υψηλής ποιότητας manual έτοιμο για εκτύπωση. Ταχύτητα, ευχρηστία και συμβατότητα. Και όπως προφανώς καταλάβατε τα πάντα βγαίνουν από ένα αρχείο που γράφετε μία φορά και μετά με τα διάφορα εργαλεία το μετατρέπετε σε ότι μορφή θέλετε.
Λυπάμαι που θα απογοητεύσω όλους τους hard-core unixάδες, αλλά το επίσημο documentation format σύμφωνα με την GNU είναι το texinfo και όχι οι manpages. Μία manpage είναι αρκετή για μικρά προγράμματα, από κάποιο σημείο και μετά όμως τα πράγματα δυσκολεύουν.
Το γεγονός ότι μία manpage στερείται δομής, την κάνει δύσχρηστη. Πόσες φορές δεν έχετε εκνευρισθεί όταν ψάχνετε μία παράμετρο σε μία manpage και έχετε βρει όλες τις άλλες εκτός από αυτήν που χρειάζεστε;Κατά την γνώμη μου μία manpage πρέπει να έχει απλά μια μικρή περιγραφή του προγράμματος.
Έτσι σήμερα είναι δυνατόν να βρείτε προγράμματα που διαθέτουν infopages αλλά όχι manpages. Άλλες φορές μάλιστα υπάρχει manpage η οποία όμως απλά αναφέρει "see the info pages for the full documentation" η κάτι παρόμοιο.
Μπορεί λοιπόν οι manpages να ήταν αρκετές το 1980, σήμερα όμως έχετε την δυνατότητα να έχετε και δομημένο και εύκολα αναγνώσιμο documentation,οπότε γιατί να μην το χρησιμοποιήσετε;
Το texinfo ως σύστημα βασίζεται πάνω στο Tex/Latex. Γράφετε ένα απλό αρχείο κειμένου lala.texi με ειδική σύνταξη (τα @-commands) και μετά με την εντολή texi2foo παίρνετε το lala.foo όπου foo μέχρι τώρα μπορεί να είναι html/dvi/pdf. Υπάρχει και εντολή makeinfo με διάφορες παραμέτρους για την παραγωγή των info αρχείων.
Αυτό όμως δεν πρέπει να σας φοβίζει αν δεν γνωρίζετε το Latex. (Αν και κάποια στιγμή πρέπει να μάθετε και Latex :-). Το Texinfo είναι ένα επίπεδο πιο πάνω από το Latex. Αυτό σημαίνει ότι αποκρύπτει από εσάς τα \verylongandcomplicatedLatexdirectives και σας επιτρέπει να γράψετε το κείμενο σας με μικρά @commands δηλαδή εντολές/keywords που απλά ξεκινάνε με το @. Τα @commands είναι όλα documented στο manual του texinfo το οποίο είναι γραμμένο επίσης σε (μαντέψτε!) texinfo. Έτσι υπάρχει το @chapter, @section ,@code, @itemize με απλά και κατανοητά ονόματα. Αν μάλιστα χρησιμοποιείτε emacs θα βρείτε ότι η συγγραφή texinfo αρχείων με το αντίστοιχο mode είναι πραγματικά πολύ εύκολη.
H μαγεία είναι ότι μπορείτε να χρησιμοποιήσετε ακόμα τις εντολές του Latex αν το επιθυμείτε (κυρίως για τα εκτυπώσιμα outputs). Μάλιστα μπορείτε να γράψετε διαφορετικά τμήματα για την περίπτωση που το texinfo αρχείο μετάφράζεται σε tex, html ή info. (Περίπου σαν τα #ifdef του C-preprocessor).
Παρόλο που το texinfo διαθέτει την εντολή @image για την εισαγωγή εικόνων σε ένα έγγραφο, δεν θα πρέπει να την χρησιμοποιήσετε (στην αρχή τουλάχιστον). Και αυτό γιατί η εικόνα δεν θα φαίνεται στο info output του αρχείου σας οπότε "χάνεται" η συμβατότητα του texinfo, για την οποία το διαλέξατε. Δηλαδή το texinfo τεχνικά μπορεί να χειριστεί εικόνες (αφού μπορεί το Latex).
Ας ξεκινήσουμε με το πιο μικρό texinfo αρχείο(σχεδόν). Στον αγαπημένο σας editor γράψτε τα παρακάτω: (σε emacs και gvim θα έχετε και syntax highlighting)
\input texinfo @setfilename example.texi @settitle example @bye
Αφού το αποθηκεύσετε με όνομα sample.texi δοκιμάστε με τις εντολές texi2dvi,texi2html,texi2pdf και makeinfo να το μετατρέψετε στα αντίστοιχα format. (To dvi αρχείο μπορείτε να το δείτε με την εντολή xdvi. Τα dvi αρχεία είναι μια ενδιάμεση μορφή του tex.Μπορείτε να τα κάνετε Postscript με την εντολή dvips). Τo .info αρχείο μπορείτε να το δείτε με την εντολή info ./example.info.
H πρώτη γραμμή είναι η μοναδική εντολή σε ένα texinfo αρχείο που δεν ξεκινάει με @. Και αυτό γιατί φορτώνει το texinfo.tex το οποίο περιέχει τα defines/macros που ενεργοποιούν τις ίδιες τις @-εντολές. Η επόμενη γραμμή ορίζει το όνομα του αρχείου που γράφετε (το οποίο προφανώς θα πρέπει να είναι ίδιο με του αρχείου που την περιέχει).
Η @settitle δίνει έναν γενικό τίτλο στο manual σας, και η τελευταία εντολή δείχνει που σταματάει η επεξεργασία (processing) του κειμένου. Οτιδήποτε μετά το @bye αγνοείται από το Texinfo.
Παρατηρείστε αυτό που ανέφερα παραπάνω σχετικά με την απλότητα του Texinfo. Οι @-εντολές έχουν μικρά και κατανοητά ονόματα, κάτι που δεν συμβαίνει με το Latex.
Ας δούμε ένα μεγαλύτερο παράδειγμα. Σε ένα νέο αρχείο γράψτε τα παρακάτω.
\input texinfo
@setfilename sample.info
@settitle A sample manual
@setchapternewpage odd
@titlepage
@title My first Texinfo manual
@subtitle Demo for Magaz
@author Kapelonis Kostis
@comment This is a comment
@page
@vskip 11pt plus 1fill1
Copyright @copyright{} 2002
@end titlepage
@comment name,next,prev,up
@node Top,First Chapter,,(dir)
@menu
Εδώ βλέπουμε αρκετές @εντολές. Δεν θα τις αναφέρω όλες, για τις λεπτομέρειες δείτε το manual του texinfo. Οι γνώστες του Latex ήδη θα έχουν δει πως το texinfo "καλύπτει" με τις δικές του @εντολές τις αντίστοιχες του Latex.
Το παράδειγμα δείχνει τις εντολές για την δημιουργία indexing, την @menu για την δημιουργία μενού για το browsing μέσα σε Info αρχείου, καθώς και την πολύ σημαντική εντολή @node. H εντολή @vskip υπάρχει για να δείξει ότι δεν έχει χαθεί η ευελιξία που διαθέτει το Tex/Latex.
Ένα node (κόμβος στα ελληνικά) είναι το μικρότερο δομικό στοιχείο ενός info αρχείου. Όταν πατήσατε previous,next και up στο manual του flex, ουσιαστικά μετακινηθήκατε στα αντίστοιχα nodes. Κάθε info αρχείο "κρέμεται" από έναν top node που είναι ο αρχικός κόμβος του αντίστοιχου manual. Όλοι οι top nodes από τα manuals που έχετε στο σύστημα σας "κρέμονται" από έναν top node(supernode) του συνολικού info tree. Αν γράψετε σκέτο info σε ένα τερματικό (χωρίς όνομα manual δηλαδή) βλέπετε αυτόν τον supernode και άρα έχετε μπροστά σας όλα τα manual που έχετε εγκατεστημένα. To ίδιο συμβαίνει και όταν μπαίνετε στο info mode του Emacs.
Πρακτικά αυτό σημαίνει ότι τελικά θα πρέπει να χωρίσετε το κείμενο σας σε nodes. Τα @chapter και @section δεν είναι αυτά που καθορίζουν την δομή του online manual. Όπως είδατε και στην σελίδα της GNU για τον flex[6] ειδικά η html μορφή είναι δυνατόν να κατασκευαστεί με διάφορους τρόπους ανάλογα με τα nodes/chapters. Αυτή είναι και μια μεγάλη διαφορά που ίσως δυσκολέψει όσους "σκέφτονται" σε Latex. (Αναφέρομαι πάντα στο .info output που είναι browsable. Για ps/pdf ισχύουν τα γνωστά, δηλαδή το texinfo είναι ένα πιο φιλικό tex. Αν γράψετε ένα manual και ξέρετε από πριν ότι θα το βγάλετε μόνο σε pdf δεν χρειάζεται να δώσετε σημασία σε @node και @menu).
6: http://www.gnu.org/manual/flex-2.5.4/flex.html
To @node command συντάσσεται ως εξής:
@node όνομα,όνομα-επόμενου,όνομα-προηγούμενου,όνομα-πατρικού.
Μία από τις πρώτες δυσκολίες που θα συναντήσετε κάθε φορά που γράφετε ένα καινούριο node,είναι να συμπληρώσετε τα παραπάνω ονόματα. Αν γράφετε σε Emacs υπάρχει βέβαια έτοιμη εντολή που απλοποιεί τα πράγματα. Στην αμέσως επόμενη γραμμή βάλτε ένα "συμβατικό" δομικό @command (π.χ. @chapter, @section) για τα outputs se html/ps/pdf.
Τo @menu ορίζει το μενού που θα φαίνεται στην κάτω μεριά του node που βρίσκεται ο χρήστης. Συνήθως περιέχουν pointers σε άλλα nodes του ίδιου manual. Το supernode (μετά από ένα εισαγωγικό κείμενο) δεν είναι παρά ένα μεγάλο μενού με όλα τα manuals του συστήματος. Οι λεπτομέρειες αφήνονται ως άσκηση στον αναγνώστη (Βασικά δεν έχω ασχοληθεί πολύ με μενού ;-)
Τα outputs του παραπάνω αρχείου είναι τα παρακάτω [PDF screenshot][7] [HTML screenshot][8] [INFO screenshot][9]
Κατά τα άλλα, απλά γράφετε στο body του κειμένου, το τι ακριβώς κάνει το πρόγραμμα σας, ποιες παραμέτρους παίρνει και τι έξοδο πρέπει να περιμένει ο χρήστης.
Έχετε ανοιγμένο και το manual του texinfo για να βλέπετε τα διάφορα @commands και την χρήση τους. Θα δείτε ότι το texinfo διαθέτει αρκετά @commands ειδικά για το documentation προγραμμάτων (σε αντίθεση με το Latex που έχει δώσει μεγαλύτερο βάρος στο επιστημονικό/μαθηματικό κείμενο).
Υπάρχουν τα @key για keyboard input, τα @env για environment variables, τα @file για ονόματα αρχείων, και διάφορα άλλα @commands που ανάλογα με την περίπτωση μπορεί να σας φανούν πολύ χρήσιμα. Αυτά τα @commands καθορίζουν απλά την εμφάνιση του κειμένου πάνω στο οποίο εφαρμόζονται και όχι την δομή του. Προφανώς έχουν περισσότερη σημασία στο τυπωμένο manual αφού η html έχει λίγα tags μορφοποίησης κειμένου, και σχεδόν μηδαμινή στο περιβάλλον κονσόλας.
Επίσης υπάρχουν όλα τα αναμενόμενα @commands για list,bullets, subsection,verbatim text,code κ.τ.λ. Όλα βρίσκονται μέσα στο manual του texinfo με παραδείγματα.
Όπως ίσως έχετε υποψιαστεί για να βάλετε το ίδιο το "@" μέσα στο κείμενο το γράφετε δύο φορές δηλαδή "@@". Υπάρχει και ειδικό @command με όνομα @email.
Αφού το texinfo είναι μέρος της Gnu tool chain (Emacs,gcc,make,gdb, m4[10] ,automake,autoconf, gprof[11]) δεν ήταν δυνατόν να μην συνεργάζεται άψογα με τον Emacs.
10: http://www.gnu.org/software/m4/
11: http://sources.redhat.com/binutils/docs-2.12/gprof.info/
Έτσι λοιπόν υπάρχει ειδικό Texinfo mode το οποίο διαθέτει πολύ συχνά χρησιμοποιούμενα short commands (Ctrl-c) και λιγότερο συχνά long commands (Meta/Alt-x) Αναφέρω εδώ μερικά:
C-c C-c n Enter node C-c C-c e Enter end C-c C-c i Enter item C-c C-c v Enter variable C-c C-s Show structure C-c C-u C-m update Menu C-c C-u C-n update Node
Αυτά που πραγματικά σας λύνουν τα χέρια είναι οι εντολές για την εισαγωγή ενός νέου node,αφού συμπληρώνονται αυτόματα τα next,prev, up καθώς και η εντολή που ανοίγει ένα νέο buffer με την δομή του texinfo αρχείου όπου μπορείτε να καταλάβετε οπτικά πως είναι αυτή.
Γενικά, ακόμα και αν είστε φανατικός χρήστης του vi/vim/gvim σας προτείνω να ασχοληθείτε λίγο με τον Emacs κατά την συγγραφή texinfo αρχείων. Είναι πολύ χρήσιμος, ενώ για πολύ μεγάλα manuals με περίπλοκη δομή/μενού και cross references σχεδόν απαραίτητος.
Ξέρω ότι έδωσα λιγότερες τεχνικές λεπτομέρειες από όσες ίσως θα θέλατε. Δεν αναφέρθηκα στην δημιουργία indexing/table of contents ,cross-references,table και διάφορων άλλων δυνατοτήτων του Texinfo. Υπάρχει και η πολύ εντυπωσιακή δυνατότητα της δημιουργίας link σε εντελώς διαφορετικό manual, όπου μεταφέρεται αυτόματα ο χρήστης, όταν χρησιμοποιεί το info format.
Έτσι είναι δυνατόν ο χρηστής να διαβάζει το manual του flex μέσα στον Emacs και με ένα κλικ να βρεθεί σε αυτό του bison. Η από αυτό του automake να μεταφερθεί σε αυτό του autoconf και μόλις δει αυτό που θέλει, να επιστρέψει. Σε html και τυπωμένα manual τέτοια links γίνονται απλά "See the bison manual page 33" ή κάτι τέτοιο, και πάλι όμως είναι εντυπωσιακή η αυτόματη εισαγωγή τους, αφού εσείς μέσα στο texinfo αρχείο απλά βάζετε το όνομα του manual που θα μεταφερθεί ο χρήστης καθώς και το όνομα του node στο οποίο θα γίνει η μεταφορά.
Νομίζω όμως ότι ο σκοπός των άρθρων του magaz δεν είναι να σας πάρουν από το χεράκι και να σας δείξουν βήμα-βήμα τις οδηγίες χρήσης. Οφείλετε απλά να δείτε τι υπάρχει διαθέσιμο και αν κάτι σας φαίνεται χρήσιμο να ασχοληθείτε μαζί του.
