327 γραμμές
30 KiB
Markdown
327 γραμμές
30 KiB
Markdown
|
+++
|
|||
|
|
title = 'Documentation ala GNU'
|
|||
|
|
date = '2002-07-01T00:00:00Z'
|
|||
|
|
description = ''
|
|||
|
|
author = 'Καπελώνης Κωστής kkapelon _AT_ freemail.gr(mailto:kkapelonSPAM@SUXfreemail.gr)'
|
|||
|
|
issue = ['Magaz 34']
|
|||
|
|
issue_weight = 2
|
|||
|
|
+++
|
|||
|
|
|
|||
|
|
----------------------------------------------------------------------------------------------------------------------------------------------------------------
|
|||
|
|
|
|||
|
|
*Σε αυτό το άρθρο γίνεται μία εισαγωγή στο επίσημο εργαλείο για documentation της GNU, το σύστημα Texinfo. Απευθύνεται σε προγραμματιστές που έχουν τελειώσει
|
|||
|
|
την κατασκευή μιας εφαρμογής κονσόλας και επιθυμούν να ενσωματώσουν βοήθεια σε αυτή.*
|
|||
|
|
|
|||
|
|
----------------------------------------------------------------------------------------------------------------------------------------------------------------
|
|||
|
|
|
|||
|
|
**1. Εισαγωγή**
|
|||
|
|
-----------------------------------------
|
|||
|
|
|
|||
|
|
**2. Οι επιλογές σας**
|
|||
|
|
------------------------------------------------
|
|||
|
|
|
|||
|
|
**3. Το texinfo από την μεριά του χρήστη.**
|
|||
|
|
---------------------------------------------------------------------
|
|||
|
|
|
|||
|
|
**4. texinfo vs manpages**
|
|||
|
|
----------------------------------------------------
|
|||
|
|
|
|||
|
|
**5. Η φιλοσοφία του texinfo**
|
|||
|
|
--------------------------------------------------------
|
|||
|
|
|
|||
|
|
**6. To πιο απλό Texinfo αρχείο**
|
|||
|
|
-----------------------------------------------------------
|
|||
|
|
|
|||
|
|
**7. Ένα μεγαλύτερο έγγραφο**
|
|||
|
|
-------------------------------------------------------
|
|||
|
|
|
|||
|
|
**8. Συγγραφή του κυρίως κειμένου.**
|
|||
|
|
--------------------------------------------------------------
|
|||
|
|
|
|||
|
|
**9. Emacs shortcuts**
|
|||
|
|
------------------------------------------------
|
|||
|
|
|
|||
|
|
**10. Επίλογος**
|
|||
|
|
--------------------------------------------
|
|||
|
|
|
|||
|
|
|
|||
|
|
### [1. Εισαγωγή]{#s1}
|
|||
|
|
|
|||
|
|
Δεν νομίζω ότι χρειάζεται να επαναλάβω ρήσεις για το Documentation και το sex. Μεγάλα παιδιά είστε, οπότε ξέρετε ότι μεγάλο βάρος στην ποιότητα και την
|
|||
|
|
ευχρηστία μιας εφαρμογής, έχει ΚΑΙ η βοήθεια/τεκμηρίωση που την συνοδεύει.
|
|||
|
|
|
|||
|
|
Δυστυχώς αρκετές φορές η βοήθεια ενός προγράμματος παραμελείται από τους προγραμματιστές της. Όλοι μας έχουμε συναντήσει προγράμματα που ενώ ήταν λειτουργικά
|
|||
|
|
και μπορούσαν να εκπληρώσουν το σκοπό τους, είχαν ελλιπές ή ακόμα και μηδαμινό documentation.
|
|||
|
|
|
|||
|
|
Ειδικά στον χώρο του ανοιχτού λογισμικού (open source) τα πράγματα δεν είναι πολύ καλά. Άπειρες επιλογές με περίεργα ονόματα σε γραφικά προγράμματα, ή
|
|||
|
|
undocumented παράμετροι σε προγράμματα κονσόλας (command line arguments) είναι καθημερινό φαινόμενο. Δεν μου αρέσει να ενεργοποιώ επιλογές που απλά είδα στο
|
|||
|
|
δίκτυο ή άκουσα από φίλους ότι \"έτσι λειτουργεί\". Οι μέρες του voodoo πρέπει να μείνουν επιτέλους στην ιστορία.
|
|||
|
|
|
|||
|
|
Τώρα θα πούνε μερικοί, \"σιγά ρε φίλε! Use the source, Luke!\". Μα καλά είμαστε σοβαροί; Είμαστε στο 2000+ και θα πρέπει να ανοίξω τον πηγαίο κώδικα του
|
|||
|
|
προγράμματος για να δω τι κάνει;Δεν το δέχομαι αυτό. Καλή εφαρμογή = καλός κώδικας + καλή τεκμηρίωση.
|
|||
|
|
|
|||
|
|
Γράφω λοιπόν αυτό το άρθρο έτσι ώστε όταν τελειώσετε το προγραμματιστικό σας αριστούργημα, με την τέλεια δομημένη εσωτερική αρχιτεκτονική, την ταχύτατη μεταφορά
|
|||
|
|
πληροφορίας ανάμεσα στα διάφορα μέρη του, τις βελτιστοποιημένες στο έπακρο εσωτερικές ρουτίνες και τις πολύπλοκες δομές δεδομένων,όταν πιστέψετε ότι έχετε βάλει
|
|||
|
|
τάξη στο χάος ;-), όταν νιώσετε ένας μικρός θεός και βιώσετε το θαύμα της δημιουργίας, να μην ξεχάσετε και τον παράγοντα τεκμηρίωση.
|
|||
|
|
|
|||
|
|
### [2. Οι επιλογές σας]{#s2}
|
|||
|
|
|
|||
|
|
Αν η εφαρμογή που γράφετε έχει γραφικό μέρος και ανήκει σε κάποιο από τα δύο γνωστά περιβάλλοντα εφαρμογών (desktop environments), δεν χρειάζεται να συνεχίσετε
|
|||
|
|
την ανάγνωση. Απλά δείτε τις αντίστοιχες σελίδες που εξηγούν πως πρέπει να είναι το documentation της εφαρμογής σας. Λογικά θα πρέπει να γράψετε ένα αρχείο SGML
|
|||
|
|
Docbook το οποίο θα πρέπει να έχει μια συγκεκριμένη μορφή.
|
|||
|
|
|
|||
|
|
Αν η εφαρμογή σας είναι απλά γραφική και δεν υπάρχει \"σωστός\" τρόπος για την εισαγωγή βοήθειας, προτιμήστε το δοκιμασμένο Latex. Βάζετε το output σε html στο
|
|||
|
|
site του προγράμματος για online αναζήτηση, ενώ μαζί με το ίδιο το πρόγραμμα ενσωματώνετε τα ps και pdf αρχεία. Αυτό είναι απλά μία πρόταση. Είναι στην κρίση
|
|||
|
|
σας να επιλέξετε.
|
|||
|
|
|
|||
|
|
Εδώ θα μιλήσουμε για την περίπτωση όπου το πρόγραμμα σας δεν έχει γραφικό περιβάλλον, αλλά εκτελείται σε περιβάλλον γραμμής εντολών. Αν είναι πολύ απλό στην
|
|||
|
|
χρήση, και με λίγες παραμέτρους τα πράγματα είναι εύκολα. Απλά βάλτε στο -h/\--help του να εμφανίζεται κάθε δυνατή παράμετρος με μία μικρή εξήγηση. Σε αυτήν την
|
|||
|
|
περίπτωση μπορείτε να ακολουθήσετε και το GNU style για τις παραμέτρους όπου κάθε μία έχει ένα σύντομο όνομα για τους έμπειρους χρήστες (πχ -b) και ένα πιο
|
|||
|
|
μεγάλο για τους αρχάριους (πχ \--buffer-size).
|
|||
|
|
|
|||
|
|
Αν όμως δεν ισχύει κάτι τέτοιο οφείλετε να δώσετε ξεχωριστό documentation. Αυτό θα βοηθήσει τόσο τους έμπειρους χρήστες όταν θα θελήσουν να \"ξεζουμίσουν\" το
|
|||
|
|
πρόγραμμα σας, αλλά και τους αρχάριους που αρέσκονται στο να βρίσκουν κάπου \"μαζεμένη\" την βοήθεια ενός προγράμματος.
|
|||
|
|
|
|||
|
|
|
|||
|
|
### [3. Το texinfo από την μεριά του χρήστη.]{#s3}
|
|||
|
|
|
|||
|
|
Ας δούμε ένα παράδειγμα. Έστω ότι θέλετε να μάθετε τα πάντα για το GNU flex.
|
|||
|
|
|
|||
|
|
Αρχικά μπορείτε να ανοίξετε ένα τερματικό στο pc σας και να δώσετε \"info flex\" [\[εικόνα\]](/34/img/flexINFO.png). Πατώντας το πλήκτρο 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 που βλέπετε [\[εικόνα\]](/34/img/flexEMACS.png).
|
|||
|
|
|
|||
|
|
Αν επιθυμείτε κάτι πιο συμβατικό μπείτε στο [gnu.org (manuals section)](http://www.gnu.org/manual/manual.html) όπου μπορείτε είτε να κατεβάσετε ολόκληρο το
|
|||
|
|
manual σε Postscript μορφή [σε Postscript μορφή](http://www.gnu.org/manual/flex-2.5.4/ps/flex.ps.gz) για να το τυπώσετε ή μπορείτε να το διαβάσετε Online σε
|
|||
|
|
απλή και γρήγορη [HTML μορφή](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 έτοιμο για εκτύπωση. Ταχύτητα, ευχρηστία και συμβατότητα. Και όπως προφανώς καταλάβατε τα πάντα βγαίνουν από ένα αρχείο
|
|||
|
|
που γράφετε μία φορά και μετά με τα διάφορα εργαλεία το μετατρέπετε σε ότι μορφή θέλετε.
|
|||
|
|
|
|||
|
|
|
|||
|
|
### [4. texinfo vs manpages]{#s4}
|
|||
|
|
|
|||
|
|
Λυπάμαι που θα απογοητεύσω όλους τους 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,οπότε γιατί να μην
|
|||
|
|
το χρησιμοποιήσετε;
|
|||
|
|
|
|||
|
|
|
|||
|
|
### [5. Η φιλοσοφία του texinfo]{#s5}
|
|||
|
|
|
|||
|
|
Το 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).
|
|||
|
|
|
|||
|
|
|
|||
|
|
### [6. To πιο απλό Texinfo αρχείο]{#s6}
|
|||
|
|
|
|||
|
|
Ας ξεκινήσουμε με το πιο μικρό 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.
|
|||
|
|
|
|||
|
|
|
|||
|
|
### [7. Ένα μεγαλύτερο έγγραφο]{#s7}
|
|||
|
|
|
|||
|
|
Ας δούμε ένα μεγαλύτερο παράδειγμα. Σε ένα νέο αρχείο γράψτε τα παρακάτω.
|
|||
|
|
|
|||
|
|
----------------------------------------------------------------------------------------------------------------------------------------------------------------
|
|||
|
|
|
|||
|
|
\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
|
|||
|
|
* First Chapter:: The first chapter is the only chapter in this sample
|
|||
|
|
* Concept Index:: This index has two entries
|
|||
|
|
@end menu
|
|||
|
|
@node First Chapter,Concept Index,Top,Top
|
|||
|
|
@chapter First Chapter
|
|||
|
|
@cindex Sample index entry
|
|||
|
|
These are the contents of the first chapter
|
|||
|
|
Here is a simple line of text.
|
|||
|
|
@cindex Another sample index entry
|
|||
|
|
Here is a numbered list
|
|||
|
|
@enumerate
|
|||
|
|
@item
|
|||
|
|
This is the first item
|
|||
|
|
@item
|
|||
|
|
This is the second item
|
|||
|
|
@end enumerate
|
|||
|
|
|
|||
|
|
@iftex
|
|||
|
|
This paragraph should
|
|||
|
|
appear only in a printed manual.
|
|||
|
|
It is enclosed inside iftex keywords.
|
|||
|
|
@end iftex
|
|||
|
|
|
|||
|
|
@ifinfo
|
|||
|
|
This paragraph should
|
|||
|
|
appear only in the info manual.
|
|||
|
|
It is enclosed inside ifinfo keywords.
|
|||
|
|
@end ifinfo
|
|||
|
|
|
|||
|
|
The @command{makeinfo} command will convert this manual
|
|||
|
|
into an info file and @TeX{} to a printed file.
|
|||
|
|
@node Concept Index ,,First Chapter,Top
|
|||
|
|
@unnumbered Concept Index
|
|||
|
|
@printindex cp
|
|||
|
|
@comment Place here table of contents
|
|||
|
|
@contents
|
|||
|
|
@bye
|
|||
|
|
|
|||
|
|
----------------------------------------------------------------------------------------------------------------------------------------------------------------
|
|||
|
|
|
|||
|
|
Εδώ βλέπουμε αρκετές \@εντολές. Δεν θα τις αναφέρω όλες, για τις λεπτομέρειες δείτε το 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](http://www.gnu.org/manual/flex-2.5.4/flex.html) ειδικά η html μορφή είναι δυνατόν να κατασκευαστεί με
|
|||
|
|
διάφορους τρόπους ανάλογα με τα nodes/chapters. Αυτή είναι και μια μεγάλη διαφορά που ίσως δυσκολέψει όσους \"σκέφτονται\" σε Latex. (Αναφέρομαι πάντα στο .info
|
|||
|
|
output που είναι browsable. Για ps/pdf ισχύουν τα γνωστά, δηλαδή το texinfo είναι ένα πιο φιλικό tex. Αν γράψετε ένα manual και ξέρετε από πριν ότι θα το
|
|||
|
|
βγάλετε μόνο σε pdf δεν χρειάζεται να δώσετε σημασία σε \@node και \@menu).
|
|||
|
|
|
|||
|
|
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\]](/34/img/samplePDF.png) [\[HTML screenshot\]](/34/img/sampleHTML.png) [\[INFO
|
|||
|
|
screenshot\]](/34/img/sampleINFO.png)
|
|||
|
|
|
|||
|
|
|
|||
|
|
### [8. Συγγραφή του κυρίως κειμένου.]{#s8}
|
|||
|
|
|
|||
|
|
Κατά τα άλλα, απλά γράφετε στο 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.
|
|||
|
|
|
|||
|
|
|
|||
|
|
### [9. Emacs shortcuts]{#s9}
|
|||
|
|
|
|||
|
|
Αφού το texinfo είναι μέρος της Gnu tool chain (Emacs,gcc,make,gdb, [m4](http://www.gnu.org/software/m4/) ,automake,autoconf,
|
|||
|
|
[gprof](http://sources.redhat.com/binutils/docs-2.12/gprof.info/)) δεν ήταν δυνατόν να μην συνεργάζεται άψογα με τον Emacs.
|
|||
|
|
|
|||
|
|
Έτσι λοιπόν υπάρχει ειδικό 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 σχεδόν απαραίτητος.
|
|||
|
|
|
|||
|
|
|
|||
|
|
### [10. Επίλογος]{#s10}
|
|||
|
|
|
|||
|
|
Ξέρω ότι έδωσα λιγότερες τεχνικές λεπτομέρειες από όσες ίσως θα θέλατε. Δεν αναφέρθηκα στην δημιουργία 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 δεν είναι να σας πάρουν από το χεράκι και να σας δείξουν βήμα-βήμα τις οδηγίες χρήσης. Οφείλετε απλά να δείτε τι
|
|||
|
|
υπάρχει διαθέσιμο και αν κάτι σας φαίνεται χρήσιμο να ασχοληθείτε μαζί του.
|
|||
|
|
|