Εκτός από το βασικό σύστημα και την Συλλογή των Ports, η τεκμηρίωση αποτελεί επίσης βασικό τμήμα ενός συστήματος FreeBSD. Αν και πάντα μπορείτε να βρείτε την πιο πρόσφατη τεκμηρίωση στην δικτυακή τοποθεσία του FreeBSD, ορισμένοι χρήστες ίσως έχουν αργή ή μη σταθερή σύνδεση με το Διαδίκτυο. Ευτυχώς υπάρχουν αρκετοί τρόποι για να ενημερώσετε την τεκμηρίωση η οποία παρέχεται με κάθε επίσημη έκδοση, διατηρώντας το δικό σας τοπικό αντίγραφο της πιο πρόσφατης τεκμηρίωσης του FreeBSD.
Ο πηγαίος κώδικας και το εγκατεστημένο αντίγραφο της τεκμηρίωσης του FreeBSD, μπορούν να ενημερωθούν με την βοήθεια του CVSup, χρησιμοποιώντας ένα μηχανισμό παρόμοιο με αυτόν που χρησιμοποιείται στο βασικό σύστημα (δείτε το Τμήμα 24.7). Η ενότητα αυτή περιγράφει:
Πως να εγκαταστήσετε τα εργαλεία που απαιτούνται για την τεκμηρίωση, με τα οποία μπορείτε να δημιουργήσετε την τεκμηρίωση του FreeBSD ξεκινώντας από τον πηγαίο της κώδικα.
Πως να κατεβάσετε ένα αντίγραφο του πηγαίου κώδικα της τεκμηρίωσης στον κατάλογο /usr/doc χρησιμοποιώντας το CVSup.
Πως να αναδημιουργήσετε την τεκμηρίωση του FreeBSD από τον πηγαίο της κώδικα, και να την εγκαταστήσετε στον κατάλογο /usr/share/doc/.
Η αναδημιουργία της τεκμηρίωσης του FreeBSD από τον πηγαίο κώδικα, απαιτεί μια σχετικά μεγάλη συλλογή εργαλείων. Τα εργαλεία αυτά δεν είναι μέρος του βασικού συστήματος του FreeBSD, καθώς χρειάζονται αρκετό χώρο στο δίσκο και δεν είναι χρήσιμα σε όλους τους χρήστες. Είναι χρήσιμα μόνο στους χρήστες που ασχολούνται με τη συγγραφή νέας τεκμηρίωσης για το FreeBSD, ή που ενημερώνουν συχνά την τοπική τους τεκμηρίωση μέσω του πηγαίου κώδικα.
Όλα τα απαιτούμενα εργαλεία διατίθενται μέσω της Συλλογής των Ports. Το textproc/docproj είναι το κύριο port το οποίο έχει αναπτυχθεί από την Ομάδα Τεκμηρίωσης του FreeBSD, για να βοηθήσει στην αρχική εγκατάσταση και τις μελλοντικές αναβαθμίσεις αυτών των εργαλείων.
Σημείωση: Αν δεν απαιτείται η δημιουργία τεκμηρίωσης σε μορφές PostScript® ή PDF, μπορείτε να εγκαταστήσετε το port textproc/docproj-nojadetex. Αυτή η έκδοση των εργαλείων περιέχει τα πάντα εκτός από την μηχανή στοιχειοθεσίας teTeX. Το teTeX είναι μια αρκετά μεγάλη συλλογή εργαλείων, και δεν έχει νόημα να το εγκαταστήσετε αν δεν σας είναι απαραίτητη η παραγωγή της τεκμηρίωσης σε μορφή PDF.
Για περισσότερες πληροφορίες σχετικά με την εγκατάσταση και χρήση του CVSup, δείτε την ενότητα Χρησιμοποιώντας το CVSup.
Το βοηθητικό πρόγραμμα CVSup μπορεί να κατεβάσει ένα καθαρό αντίγραφο του πηγαίου κώδικα της τεκμηρίωσης, χρησιμοποιώντας το /usr/share/examples/cvsup/doc-supfile ως πρότυπο αρχείο ρυθμίσεων. Ο προεπιλεγμένος υπολογιστής ενημερώσεων στο παραπάνω αρχείο είναι ρυθμισμένος σε πλασματική τιμή. Ωστόσο, η cvsup(1) δέχεται όνομα υπολογιστή μέσω της γραμμής εντολών, έτσι μπορείτε να ανακτήσετε τον πηγαίο κώδικα της τεκμηρίωσης μέσω κάποιου εξυπηρετητή CVSup γράφοντας:
# cvsup -h cvsup.FreeBSD.org -g -L 2 /usr/share/examples/cvsup/doc-supfile
Αλλάξτε το cvsup.FreeBSD.org με τον κοντινότερο σας εξυπηρετητή CVSup. Δείτε το Τμήμα A.6.7 για μια πλήρη λίστα των mirror sites.
Το αρχικό κατέβασμα του πηγαίου κώδικα της τεκμηρίωσης μπορεί να διαρκέσει αρκετή ώρα. Αφήστε το να εκτελείται μέχρι να ολοκληρωθεί.
Μπορείτε να συνεχίσετε να ενημερώνετε τον πηγαίο κώδικα της τεκμηρίωσης χρησιμοποιώντας την ίδια εντολή. Το βοηθητικό πρόγραμμα CVSup κατεβάζει και αντιγράφει μόνο τις ενημερώσεις σε σχέση με την τελευταία εκτέλεση του, έτσι κάθε εκτέλεση του CVSup μετά την πρώτη θα πρέπει να είναι αρκετά γρήγορη.
Μετά την αρχική ανάκτηση του πηγαίου κώδικα, ένας εναλλακτικός τρόπος ενημέρωσης της τεκμηρίωσης είναι μέσω του αρχείου Makefile στον κατάλογο /usr/doc. Θέτοντας τις μεταβλητές SUP_UPDATE, SUPHOST και DOCSUPFILE στο αρχείο /etc/make.conf, μπορείτε να εκτελέσετε:
# cd /usr/doc # make update
Τυπικές τιμές για τις παραπάνω επιλογές του make(1) στο αρχείο /etc/make.conf είναι:
SUP_UPDATE= yes SUPHOST?= cvsup.freebsd.org DOCSUPFILE?= /usr/share/examples/cvsup/doc-supfile
Σημείωση: Αν θέσετε τις τιμές των SUPHOST και DOCSUPFILE σε ?=, θα μπορείτε να ορίσετε άλλες τιμές για αυτές στη γραμμή εντολής του make. Αυτός είναι και ο συνιστώμενος τρόπος να προσθέσετε επιλογές στο make.conf, ώστε να αποφεύγετε να τροποποιείτε συνέχεια το αρχείο κάθε φορά που θέλετε να δοκιμάσετε μια νέα τιμή σε μια επιλογή.
Το σύστημα ενημέρωσης και μεταγλώττισης της τεκμηρίωσης του FreeBSD, υποστηρίζει μερικές επιλογές που διευκολύνουν τη διαδικασία ενημέρωσης ενός μόνο μέρους της τεκμηρίωσης, ή την μεταγλώττιση της τεκμηρίωσης κάποιων συγκεκριμένων μεταφράσεων. Αν θέλετε οι επιλογές αυτές να ισχύουν μόνιμα, μπορείτε να τις ορίσετε μέσα στο αρχείο /etc/make.conf, διαφορετικά μπορείτε να τις ορίζετε κάθε φορά στη γραμμή εντολής της make(1).
Κάποιες από τις επιλογές αυτές φαίνονται παρακάτω:
Λίστα των γλωσσών και κωδικοποιήσεων που θα μεταγλωττιστούν και θα εγκατασταθούν, π.χ. en_US.ISO8859-1 αν είναι επιθυμητή μόνο η Αγγλική τεκμηρίωση.
Η μορφή (ή μια λίστα από μορφές) στην οποία θα παραχθεί η μεταγλωττισμένη τεκμηρίωση. Τη δεδομένη στιγμή υποστηρίζονται οι μορφές html, html-split, txt, ps, pdf και rtf.
Το όνομα του εξυπηρετητή CVSup που θα χρησιμοποιηθεί κατά την ενημέρωση.
Ο κατάλογος στον οποίο θα εγκατασταθεί η τεκμηρίωση. Από προεπιλογή είναι ο /usr/share/doc.
Για περισσότερες πληροφορίες σχετικά με τις μεταβλητές του make που υποστηρίζονται ως επιλογές συστήματος στο FreeBSD, δείτε την σελίδα manual του make.conf(5).
Για περισσότερες πληροφορίες και μεταβλητές make που υποστηρίζονται από το σύστημα μεταγλώττισης της τεκμηρίωσης του FreeBSD, παρακαλούμε δείτε τις Οδηγίες της Ομάδας Τεκμηρίωσης του FreeBSD για Νέους Συγγραφείς.
Έχοντας ενημερώσει το τοπικό αντίγραφο του πηγαίου κώδικα της τεκμηρίωσης στον κατάλογο /usr/doc, είμαστε έτοιμοι για την ενημέρωση της εγκατεστημένης τεκμηρίωσης.
Μπορείτε να προχωρήσετε σε πλήρη ενημέρωση όλων των γλωσσών που ορίζονται στην επιλογή DOC_LANG του Makefile, γράφοντας:
# cd /usr/doc # make install clean
Αν έχετε ρυθμίσει το make.conf με τις σωστές τιμές για τις επιλογές DOCSUPFILE, SUPHOST και SUP_UPDATE, μπορείτε να συνδυάσετε τα βήματα ενημέρωσης και εγκατάστασης του πηγαίου κώδικα σε ένα, γράφοντας:
# cd /usr/doc # make update install clean
Αν επιθυμείτε την ενημέρωση μιας μόνο συγκεκριμένης γλώσσας, μπορείτε να καλέσετε την make(1) σε ένα συγκεκριμένο υποκατάλογο του /usr/doc, π.χ.:
# cd /usr/doc/en_US.ISO8859-1 # make update install clean
Μπορείτε να καθορίσετε τη μορφή της τεκμηρίωσης που θα εγκατασταθεί, ρυθμίζοντας τη μεταβλητή FORMATS του make, π.χ.:
# cd /usr/doc # make FORMATS='html html-split' install clean
Στην προηγούμενη ενότητα, παρουσιάσαμε μια μέθοδο για την ενημέρωση της τεκμηρίωσης του FreeBSD μέσω του πηγαίου κώδικα. Ωστόσο, οι ενημερώσεις που βασίζονται στον πηγαίο κώδικα μπορεί να μην είναι δυνατές ή πρακτικές για κάθε σύστημα FreeBSD. Η διαδικασία μεταγλώττισης του πηγαίου κώδικα της τεκμηρίωσης απαιτεί σχετικά μεγάλο αριθμό εργαλείων και βοηθητικών προγραμμάτων, γνωστά ως εργαλεία τεκμηρίωσης. Απαιτεί επίσης και μια σχετική εξοικείωση με το CVS και τη διαδικασία ανάκτησης των αρχείων από αυτό, καθώς και μια σειρά από βήματα για τη μεταγλώττιση του κώδικα. Στην ενότητα αυτή περιγράφουμε ένα εναλλακτικό τρόπο ενημέρωσης της τεκμηρίωσης που εγκαθίσταται μαζί με το FreeBSD. Η μέθοδος αυτή χρησιμοποιεί την Συλλογή των Ports και δίνει τις παρακάτω δυνατότητες:
Κατέβασμα και εγκατάσταση προ-μεταγλωττισμένων στιγμιότυπων της τεκμηρίωσης, χωρίς να απαιτείται καμιά τοπική μεταγλώττιση (εξαλείφοντας έτσι και την ανάγκη εγκατάστασης όλων των εργαλείων τεκμηρίωσης).
Κατέβασμα του πηγαίου κώδικα της τεκμηρίωσης και μεταγλώττιση του μέσω των δυνατοτήτων που παρέχουν τα εργαλεία των ports (απλοποιώντας με αυτό τον τρόπο τη χειροκίνητη διαδικασία ανάκτησης και μεταγλώττισης).
Αυτές οι δύο μέθοδοι ενημέρωσης της τεκμηρίωσης του FreeBSD υποστηρίζονται από μια
σειρά από ports τεκμηρίωσης τα
οποία ενημερώνονται κάθε μήνα από την Ομάδα Αρχιτεκτονικής της Τεκμηρίωσης <doceng@FreeBSD.org>. Στη Συλλογή των
Ports, θα τα βρείτε κάτω από την κατηγορία docs.
Τα ports της τεκμηρίωσης χρησιμοποιούν τις δυνατότητες μεταγλώττισης που παρέχει το σύστημα των ports ώστε να διευκολύνουν τη διαδικασία δημιουργίας της τεκμηρίωσης. Με αυτό τον τρόπο η ανάκτηση του πηγαίου κώδικα της τεκμηρίωσης γίνεται αυτόματα με την εκτέλεση της make(1) και τις κατάλληλες ρυθμίσεις στο περιβάλλον. Η εγκατάσταση και απεγκατάσταση της τεκμηρίωσης είναι το ίδιο εύκολη με την εγκατάσταση οποιουδήποτε άλλου port ή πακέτου στο FreeBSD.
Σημείωση: Σε περίπτωση τοπικής μεταγλώττισης των ports της τεκμηρίωσης, απαιτείται και η εγκατάσταση των εργαλείων τεκμηρίωσης. Τα εργαλεία αυτά ωστόσο θα εγκατασταθούν αυτόματα.
Η οργάνωση των ports τεκμηρίωσης φαίνεται παρακάτω:
Υπάρχει ένα κεντρικό «master port», το misc/freebsd-doc-en το οποίο διαθέτει τα απαραίτητα αρχεία και αποτελεί την βάση όλων των άλλων ports τεκμηρίωσης. Από προεπιλογή, το port αυτό μεταγλωττίζει μόνο την Αγγλική τεκμηρίωση.
Υπάρχει ένα port «όλα σε ένα», το misc/freebsd-doc-all το οποίο μεταγλωττίζει και εγκαθιστά όλη την τεκμηρίωση σε όλες τις διαθέσιμες γλώσσες.
Τέλος, υπάρχει ένα «εξαρτώμενο port» για κάθε μετάφραση, π.χ.: misc/freebsd-doc-el για την Ελληνική τεκμηρίωση. Όλα αυτά τα ports εξαρτώνται από το master port και εγκαθιστούν την τεκμηρίωση που έχει μεταφραστεί στην αντίστοιχη γλώσσα.
Για να εγκαταστήσετε ένα port τεκμηρίωσης από τον πηγαίο κώδικα, εκτελέστε τις παρακάτω εντολές (ως root):
# cd /usr/ports/misc/freebsd-doc-en # make install clean
Το παραπάνω θα μεταγλωττίσει και θα εγκαταστήσει την Αγγλική τεκμηρίωση σε μορφή τμηματικών HTML κειμένων (όπως χρησιμοποιούνται και στο http://www.FreeBSD.org), στον κατάλογο /usr/local/share/doc/freebsd.
Μπορείτε να χρησιμοποιήσετε αρκετές επιλογές για την τροποποίηση της προεπιλεγμένης συμπεριφοράς των ports τεκμηρίωσης. Παρακάτω δείχνουμε μερικές μόνο από αυτές:
Επιτρέπει τη δημιουργία της τεκμηρίωσης σε μορφή HTML. Θα δημιουργηθεί ένα αρχείο HTML για κάθε κείμενο. Η μορφοποιημένη τεκμηρίωση θα αποθηκευθεί, ανάλογα με την περίπτωση, σε ένα αρχείο με όνομα article.html ή book.html. Θα γίνει επίσης και αποθήκευση των αντίστοιχων εικόνων.
Επιτρέπει τη δημιουργία εγγράφου σε μορφή Adobe® Portable Document Format (PDF) για χρήση με τον Adobe Acrobat Reader®, το Ghostscript, ή άλλα προγράμματα προβολής εγγράφων PDF. Η μορφοποιημένη τεκμηρίωση θα αποθηκευθεί, ανάλογα με την περίπτωση, σε ένα αρχείο article.pdf ή book.pdf.
Πρόκειται για την θέση στην οποία θα εγκατασταθεί η τεκμηρίωση. Από προεπιλογή, είναι ο κατάλογος /usr/local/share/doc/freebsd.
Σημείωση: Παρατηρήστε ότι ο προεπιλεγμένος κατάλογος διαφέρει από αυτόν που χρησιμοποιείται στη μέθοδο CVSup. Αυτό συμβαίνει επειδή γίνεται εγκατάσταση port, τα οποία από προεπιλογή χρησιμοποιούν τον κατάλογο /usr/local. Μπορείτε να παρακάμψετε αυτή την προεπιλογή, αλλάζοντας την τιμή της μεταβλητής PREFIX.
Παρακάτω θα βρείτε ένα σύντομο παράδειγμα σχετικό με τη χρήση των μεταβλητών για την εγκατάσταση της Αγγλικής τεκμηρίωσης σε μορφή PDF:
# cd /usr/ports/misc/freebsd-doc-en # make -DWITH_PDF DOCBASE=share/doc/freebsd/en install clean
Η μεταγλώττιση των ports τεκμηρίωσης από τον πηγαίο κώδικα (όπως είδαμε στην προηγούμενη ενότητα), απαιτεί τοπική εγκατάσταση των αντίστοιχων εργαλείων τεκμηρίωσης και επάρκεια χώρου στο δίσκο για την διαδικασία. Όταν δεν διατίθενται οι απαραίτητοι πόροι για την εγκατάσταση των εργαλείων τεκμηρίωσης (ή επειδή η μεταγλώττιση από τα ports θα χρησιμοποιούσε πολύ χώρο), η εγκατάσταση μπορεί να γίνει μέσω έτοιμων πακέτων τεκμηρίωσης.
H Ομάδα Αρχιτεκτονικής της Τεκμηρίωσης <doceng@FreeBSD.org> προετοιμάζει μηνιαία
στιγμιότυπα πακέτων τεκμηρίωσης του FreeBSD. Τα έτοιμα αυτά πακέτα μπορούν να
χρησιμοποιηθούν με την βοήθεια οποιουδήποτε εργαλείου διαχείρισης πακέτων που διατίθεται
με το FreeBSD, όπως για παράδειγμα τα pkg_add(1), pkg_delete(1)
κ.λ.π.
Σημείωση: Όταν χρησιμοποιείτε έτοιμα πακέτα, η εγκατάσταση της τεκμηρίωσης της επιλεγμένης γλώσσας θα γίνεται σε όλες τις διαθέσιμες μορφές.
Για παράδειγμα, η παρακάτω εντολή θα εγκαταστήσει την τελευταία έκδοση του έτοιμου πακέτου της Ελληνικής τεκμηρίωσης:
# pkg_add -r el-freebsd-doc
Σημείωση: Τα πακέτα χρησιμοποιούν τη μορφή lang-freebsd-doc στο όνομα τους, η οποία διαφέρει από την αντίστοιχη μορφή του port. Το lang είναι η σύντομη μορφή της γλώσσας, π.χ. el για Ελληνικά ή zh_cn για Απλοποιημένα Κινέζικα.
Για να ενημερώσετε ένα ήδη εγκατεστημένο port τεκμηρίωσης, μπορείτε να χρησιμοποιήσετε οποιοδήποτε εργαλείο αναβάθμισης ports. Για παράδειγμα, η παρακάτω εντολή ενημερώνει την εγκατεστημένη Ελληνική τεκμηρίωση μέσω του εργαλείου ports-mgmt/portupgrade με τη χρήση μόνο έτοιμων πακέτων:
# portupgrade -PP el-freebsd-doc
| Προηγ | Αρχή | Επόμενο |
| Portsnap: Ένα Εργαλείο Ενημέρωσης της Συλλογής των Ports | Πάνω | Παρακολούθηση Ενός Κλάδου Ανάπτυξης |
Αυτό το κείμενο, και άλλα κείμενα, μπορεί να βρεθεί στο ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.
Για ερωτήσεις σχετικά με το FreeBSD, διαβάστε την τεκμηρίωση πριν να επικοινωνήσετε με την
<questions@FreeBSD.org>.
Για ερωτήσεις σχετικά με αυτή την τεκμηρίωση, στείλτε e-mail στην <doc@FreeBSD.org>.