Η πλατφόρμα χρησιμοποιεί το δικό της εξυπηρετητή τεκμηρίωσης για την παροχή δικτυακών σελίδων για την τεκμηρίωση της πρόσθετης λειτουργίας. Ο προσαρμοσμένος εξυπηρετητής επιτρέπει στην πλατφόρμα να χειριστεί το περιεχόμενο HTML με τρόπο ανεξάρτητο από πρόγραμμα πλοήγησης και να παράγει υποστήριξη για πρόσθετες λειτουργίες. Η βασική διαφορά για σας ως προγραμματιστή πρόσθετων λειτουργιών είναι ότι έχετε λίγο μεγαλύτερη ευελιξία στον τρόπο που δομείτε τα αρχεία σας και προσδιορίζετε τις διασυνδέσεις σας.
Η πρόσθετη λειτουργία τεκμηρίωσης μπορεί να εκτελεστεί από ένα αρχείο jar ή να αποσυσκευαστεί σε έναν κατάλογο πρόσθετης λειτουργίας κατά τη διάρκεια της εγκατάστασης. Ένα αρχείο αποθήκευσης jar πρόσθετης λειτουργίας δεν επεκτείνεται σε κατάλογο πρόσθετης λειτουργίας όταν η τιμή του γνωρίσματος unpack
του στοιχείου plugin
είναι true στη δήλωση λειτουργίας. Σε τέτοια πρόσθετη λειτουργία, η τεκμηρίωση συμπιέζεται στο αρχείο jar της πρόσθετης λειτουργίας, μαζί με άλλα αρχεία της.
Στις πρόσθετες λειτουργίες που εκτελούνται αποσυσκευασμένες, η τεκμηρίωση μπορεί να παραδοθεί σε αρχείο zip, αποφεύγοντας προβλήματα που μπορεί να προκύψουν όταν υπάρχει μεγάλος αριθμός αρχείων σε έναν κατάλογο πρόσθετης λειτουργίας. Στο παράδειγμα πρόσθετης λειτουργίας, δημιουργήσαμε έναν υποκατάλογο με όνομα html. Εναλλακτικά, θα μπορούσαμε να τοποθετήσουμε τα αρχεία html σε ένα αρχείο zip με όνομα doc.zip. Αυτό το αρχείο zip πρέπει να μιμηθεί τη δομή αρχείου κάτω από τον κατάλογο της πρόσθετης λειτουργίας. Στην περίπτωσή μας, πρέπει να περιέχει τον υποκατάλογο html και όλα τα περιεχόμενα κάτω από τον html.
Σημειώστε ότι για την εκτέλεση της πρόσθετης λειτουργίας κατευθείαν από το αρχείο jar, δεν είναι αναγκαία η συμπερίληψη της τεκμηρίωσης και σε αρχείο doc.zip. Επίσης, η χρήση αρχείων doc.zip σε συμπιεσμένα αρχεία jar πρόσθετων λειτουργιών δεν υποστηρίζεται από το σύστημα βοήθειας.
Κατά την ανάλυση ονομάτων αρχείων σε μια πρόσθετη λειτουργία που εκτελείται αποσυσκευασμένη, ο εξυπηρετητής βοήθειας αναζητά έγγραφα στο αρχείο doc.zip πριν ψάξει μέσα στον κατάλογο της ίδιας της πρόσθετης λειτουργίας. Όταν χρησιμοποιείται ως διασύνδεση, το όρισμα σε ένα href θεωρείται σχετικό με την τρέχουσα πρόσθετη λειτουργία. Εξετάστε την ακόλουθη διασύνδεση:
<topic label="Ref1" href="html/ref/ref1.html"/>
Η πρόσθετη λειτουργία βοήθειας θα αναζητήσει το φάκελο ως εξής:
Μπορεί να χρησιμοποιηθεί μια πλήρης διασύνδεση για αναφορά σε κάθε περιεχόμενο του διαδικτύου.
<topic label="Ref1" href="http://www.example.com/myReference.html"/>
Το σύστημα βοήθειας πλατφόρμας χρησιμοποιεί το ίδιο σχήμα αναζήτησης καταλόγου εθνικής γλώσσας που χρησιμοποιείται από την υπόλοιπη πλατφόρμα για την εύρεση μεταφρασμένων αρχείων. (Δείτε Αρχεία ανάλογα με τοπική ρύθμιση για εξήγηση της δομής αυτού του καταλόγου.) Εάν χρησιμοποιείτε αρχείο doc.zip, πρέπει να παράγετε ένα αρχείο doc.zip για τοπική ρύθμιση each και να το τοποθετήσετε μέσα στο σωστό κατάλογο τοπικής ρύθμισης. (Δεν πρέπει να αντιγράφετε τη δομή του καταλόγου τοπικής ρύθμισης nl μέσα στο αρχείο doc.zip file.)
Επιπλέον των καταλόγων ανάλογα με την τοπική ρύθμιση, το σύστημα βοήθειας ελέγχει το σύστημα παραθύρων και τους καταλόγους του λειτουργικού συστήματος κατά τον εντοπισμό πόρων βοήθειας. Η αναζήτηση πραγματοποιείται με την ακόλουθη σειρά: υποκατάλογοι ws, os, nl, ύστερα η αφετηρία της πρόσθετης λειτουργίας μέχρι τον εντοπισμό του πόρου. Έγγραφα και άλλοι πόροι, όπως εικόνες που διαφέρουν μεταξύ συστημάτων, πρέπει να τοποθετηθούν κάτω από τον κατάλογο ws ή os για συγκεκριμένη πλατφόρμα.
Το όρισμα href μπορεί επίσης να παραπέμψει σε περιεχόμενο από άλλη πρόσθετη λειτουργία. Αυτό γίνεται με τη χρήση ειδικής σημειογραφίας παραπομπών μεταξύ πρόσθετων λειτουργιών, η οποία αναλύεται από τον εξυπηρετητή βοήθειας:
<topic label="Ref1" href="PLUGINS_ROOT/another_plugin_id/ref/ref1.html"/>
Εδώ το PLUGINS_ROOT
θα αναλυθεί κατά το χρόνο εκτέλεσης και
θα αντικατασταθεί από τον κεντρικό κατάλογο για τις πρόσθετες λειτουργίες. Μπορείτε
να ορίσετε την ταυτότητα της δικής σας πρόσθετης λειτουργίας στο another_plugin_id
. Για παράδειγμα, μπορείτε να δημιουργήσετε διασύνδεση με αυτό το κεφάλαιο του οδηγού για τους προγραμματιστές χρησιμοποιώντας το ακόλουθο θέμα:
<topic label="Help Chapter in Platform Doc" href="PLUGINS_ROOT/org.eclipse.platform.doc.isv/guide/help.html"/>
Πριν από το 3.2, οι παραπομπές σε έγγραφα σε άλλες πρόσθετες λειτουργίες
πραγματοποιούνταν χρησιμοποιώντας '..'
για τη μετάβαση σε επίπεδο πρόσθετης λειτουργίας, και στη συνέχεια
παραπέμποντας στην ταυτότητα της πρόσθετης λειτουργίας, η οποία ακολουθείται
από το HREF στο θέμα μέσα στην πρόσθετη λειτουργία.
Ο συνιστώμενος τρόπος εκτέλεσης των παραπάνω είναι πλέον η χρήση του
PLUGINS_ROOT
αντί του '..'. Με τη χρήση αυτής της μεταβλητής
αποφεύγεται η αναζήτηση προς τα επάνω/κάτω στις παραπομπές. Η μεταβλητή μπορεί
επίσης να χρησιμοποιηθεί σε όλες τις διευθύνσεις URL πόρων στα έγγραφα βοήθειας (εικόνες, διασυνδέσεις,
αρχεία CSS, αρχεία σεναρίου java κλπ.)
Σημείωση: Όταν κάνετε παραπομπή σε περιεχόμενο άλλης πρόσθετης λειτουργίας, βεβαιωθείτε ότι χρησιμοποιείτε το γνώρισμα id της πρόσθετης λειτουργίας, όπως δηλώνεται στο αρχείο plugin.xml , κι όχι το όνομα καταλόγου. Αν και συχνά είναι ίδια στην πράξη, είναι σημαντικό να ελέγχετε ότι χρησιμοποιείτε την ταυτότητα κι όχι το όνομα καταλόγου.
Συχνά τοποθετούνται πληροφορίες εμπορικής επωνυμίας σε μια πρόσθετη λειτουργία που καθορίζουν ένα προϊόν όπως εξηγείται στην ενότητα Προϊόντα και λειτουργίες.
Είναι δυνατή η δημιουργία παραπομπών στους πόρους βοήθειας στην πρόσθετη
λειτουργία του προϊόντος από τον πίνακα περιεχομένων ή από θέματα
χρησιμοποιώντας την ειδική ταυτότητα PRODUCT_PLUGIN
για την
ταυτότητα της πρόσθετης λειτουργίας. Για παράδειγμα, η
href="PLUGINS_ROOT/PRODUCT_PLUGIN/book.css"
αναφέρεται σε φύλλο στυλ που βρίσκεται στην πρόσθετη λειτουργία για τον προϊόν υπό εκτέλεση.