Κάθε πρόσθετη λειτουργία που συνεισφέρει αρχεία βοήθειας θα πρέπει γενικά να πραγματοποιεί τα εξής:
Προαιρετικά, μπορεί να προ-δομηθεί ένα ευρετήριο αναζήτησης και να καταχωρηθεί με τη χρήση του στοιχείου index
προκειμένου να πραγματοποιείται η πρώτη προσπάθεια αναζήτησης. Μπορεί να καταχωρηθεί μόνο ένα ευρετήριο ανά πρόσθετη λειτουργία - περισσότερα στοιχεία index
θα οδηγήσουν σε ακαθόριστη συμπεριφορά.
<!ELEMENT extension (toc* , index?)>>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED>
<!ELEMENT toc EMPTY>
<!ATTLIST toc
file CDATA #REQUIRED
primary (true | false) "false"
extradir CDATA #IMPLIED
category CDATA #IMPLIED>
Μορφοποίηση ρυθμίσεων για το αρχείο toc:
<!ELEMENT toc (topic | anchor | link)* >
<!ATTLIST toc link_to CDATA #IMPLIED >
<!ATTLIST toc label CDATA #REQUIRED >
<!ATTLIST toc topic CDATA #IMPLIED >
<!ELEMENT topic (topic | anchor | link )* >
<!ATTLIST topic label CDATA #REQUIRED >
<!ATTLIST topic href CDATA #IMPLIED >
<!ELEMENT anchor EMPTY >
<!ATTLIST anchor id ID #REQUIRED >
<!ELEMENT link EMPTY >
<!ATTLIST link toc CDATA #REQUIRED >
Γενικά, μια πρόσθετη λειτουργία η οποία πρέπει να παρέχει ηλεκτρονική βοήθεια θα ορίζει τα δικά της αρχεία TOC. Στο τέλος, το σύστημα βοήθειας ρυθμίζεται έτσι ώστε να ξεκινά όπως ορισμένες ενέργειες και η διαδρομή του αρχείου TOC μπορεί να χρησιμοποιηθεί για τον σκοπό αυτό.
Το στοιχείο topic
Όλα τα στοιχεία topic της βοήθειας συνεισφέρονται ως τμήμα του στοιχείου θέσης υποδοχής toc. Μπορούν να έχουν ιεραρχική δομή ή να περιέχονται σε μια επίπεδη λίστα.
Το στοιχείο topic είναι αυτό που εκτελεί όλη την εργασία στη δομή του πίνακα περιεχομένων. Υπάρχουν δύο συνήθεις χρήσεις για το στοιχείο topic:
1. παρέχει μια διασύνδεση προς ένα αρχείο τεκμηρίωσης - συνήθως ένα αρχείο HTML.
2. δρα ως θέση υποδοχής για άλλο toc, είτε στο ίδιο αρχείο δήλωσης είτε σε διαφορετικό.
1. Θέματα ως διασυνδέσεις
Η απλούστερη χρήση ενός στοιχείου topic είναι η χρήση του ως διασύνδεση με ένα αρχείο τεκμηρίωσης.
<topic label="Some concept file" href="concepts/some_file.html" />
Το γνώρισμα href σχετίζεται με την πρόσθετη λειτουργία στην οποία ανήκει το αρχείο δήλωσης. Εάν απαιτείται η πρόσβαση σε ένα αρχείο μιας άλλης πρόσθετης λειτουργίας, μπορείτε να χρησιμοποιήσετε τη σύνταξη
<topic label="topic in another plug-in" href="../other.plugin.id/concepts/some_other_file.html" />
2. Θέματα ως θέσεις υποδοχής
Η επόμενη πιο κοινή χρήση ενός θέματος είναι η χρήση του ως θέση υποδοχής για άλλο toc. Το ίδιο το θέμα που λειτουργεί ως θέση υποδοχής μπορεί να παραπέμπει και σε άλλο συγκεκριμένο αρχείο.
<topic label="Integrated Development Environment" href="concepts/ciover.htm" >
<topic label="Starting the IDE" href="concepts/blah.htm" />
...
</topic>
Το στοιχείο link
Το στοιχείο link επιτρέπει τη διασύνδεση του πίνακα περιεχομένων που ορίζεται σε άλλο αρχείο toc.Όλα τα θέματα από το αρχείο toc που προσδιορίζονται στο γνώρισμα toc θα εμφανίζονται στον πίνακα περιεχομένων σαν να ορίζονταν απευθείας στη θέση του στοιχείου link. Για να εισαγάγετε ένα toc από ένα αρχείο api.xml μπορείτε να γράψετε:
<topic label="References" >
...
<link toc="api.xml" />
...
</topic>
Το στοιχείο anchor
Το στοιχείο anchor ορίζει ένα σημείο το οποίο θα επιτρέπει τη διασύνδεση άλλων αρχείων toc σε αυτή την πλοήγηση και την επέκτασή της, χωρίς να χρησιμοποιείται το στοιχείο link και να πραγματοποιείται παραπομπή σε άλλα αρχεία toc από το σημείο αυτό. Για να έχετε τη δυνατότητα να εισάγετε πίνακα περιεχομένων με περισσότερα θέματα μετά το έγγραφο "ZZZ" μπορείτε να ορίσετε ένα στοιχείο anchor ως εξής:
...
<topic label="zzz" href="zzz.html" />
<anchor id="moreapi" />
...
Το στοιχείο toc
Το στοιχείο toc είναι ένας πίνακας περιεχομένων ο οποίος ομαδοποιεί τα θέματα και άλλα στοιχεία που ορίζονται στο αρχείο αυτό. Η ετικέτα προσδιορίζει τον πίνακα περιεχομένων, όταν εμφανίζεται στον χρήστη. Το προαιρετικό γνώρισμα topic είναι η διαδρομή προς ένα αρχείο θέματος που περιγράφεται στο TOC. Το προαιρετικό γνώρισμα link_to επιτρέπει τη διασύνδεση toc από το αρχείο αυτό προς άλλο αρχείο toc που βρίσκεται σε ανώτερο επίπεδο στην ιεραρχία πλοήγησης. Η τιμή του γνωρίσματος link_to πρέπει να προσδιορίζει ένα στοιχείο αγκύρωσης σε άλλο αρχείο toc. Για τη διασύνδεση ενός toc από αρχείο myapi.xml σε αρχείο api.xml, που προσδιορίζεται σε άλλη πρόσθετη λειτουργία, θα πρέπει να χρησιμοποιήσετε τη σύνταξη
<toc link_to="../anotherPlugin/api.xml#moreapi" label="My Tool API"/>
...
<toc />
όπου ο χαρακτήρας # διαχωρίζει το όνομα του αρχείου toc από την ταυτότητα του σημείου αγκύρωσης.
<!ELEMENT index EMPTY>
<!ATTLIST index
path CDATA #REQUIRED>
(Από την έκδοση 3.1 και έπειτα) ένα προαιρετικό στοιχείο που επιτρέπει τη δήλωση προ-δομημένου ευρετηρίου αναζήτησης που δημιουργείται από έγγραφα τα οποία συνεισφέρονται από αυτή την πρόσθετη λειτουργία.
index/
, nl/ja/JP/index/
, nl/en/US/index/
κλπ.).(σε αρχείο plugin.xml)
<extension point=
"org.eclipse.help.toc"
>
<toc file=
"toc1.xml"
primary=
"true"
/>
<toc file=
"toc2.xml"
primary=
"true"
category=
"myCategory"
/>
<toc file=
"task.xml"
/>
<toc file=
"sample.xml"
extradir=
"samples"
/>
<index path=
"index/"
/>
</extension>
(σε αρχείο maindocs.xml)
<toc label="Help System Example">
<topic label="Introduction" href="intro.html"/>
<topic label="Tasks">
<topic label="Creating a Project" href="tasks/task1.html">
<topic label="Creating a Web Project" href="tasks/task11.html"/>
<topic label="Creating a Java Project" href="tasks/task12.html"/>
</topic>
<link toc="task.xml" />
<topic label="Testing a Project" href="tasks/taskn.html"/>
</topic>
<topic label="Samples">
<topic label="Creating Java Project" href="samples/sample1.html">
<topic label="Launch a Wizard" href="samples/sample11.html"/>
<topic label="Set Options" href="samples/sample12.html"/>
<topic label="Finish Creating Project" href="samples/sample13.html"/>
</topic>
<anchor id="samples" />
</topic>
</toc>
(σε αρχείο tasks.xml)
<toc label="Building a Project">
<topic label="Building a Project" href="build/building.html">
<topic label="Building a Web Project" href="build/web.html"/>
<topic label="Building a Java Project" href="build/java.html"/>
</topic>
</toc>
(σε αρχείο samples.xml)
<toc link_to="maindocs.xml#samples" label="Using The Compile Tool">
<topic label="The Compile Tool Sample" href="compilesample/example.html">
<topic label="Step 1" href="compilesample/step1.html"/>
<topic label="Step 2" href="compilesample/step2.html"/>
<topic label="Step 3" href="compilesample/step3.html"/>
<topic label="Step 4" href="compilesample/step4.html"/>
</topic>
</toc>
Αν υποθέσουμε ότι υπάρχουν περισσότερα του ενός έγγραφα με διαδρομή που ξεκινά με "samples", αυτά δεν θα εμφανίζονται στη διακλάδωση πλοήγησης, αλλά θα είναι προσβάσιμα με τη χρήση της αναζήτησης. Αυτό οφείλεται στο γνώρισμα "extradir" του στοιχείου <toc file="sample.xml" extradir="samples" /> μέσα στο αρχείο plugin.xml . Για παράδειγμα, η αναζήτηση του "Creating Java Project" θα επιστρέψει ως αποτέλεσμα ένα έγγραφο "Other Ways of Creating Java Project", του οποίου η διαδρομή είναι samples/sample2.html.
Διεθνής προσαρμογή Τα αρχεία XML TOC μπορούν να μεταφραστούν και το αντίγραφο που προκύπτει (με μεταφρασμένες ετικέτες) θα πρέπει να τοποθετείται στον κατάλογο nl/<language>/<country> ή nl/<language>. Τα <language> και <country> θα είναι κωδικοί δύο γραμμάτων για τη γλώσσα και τη χώρα, όπως χρησιμοποιούνται στους κωδικούς τοπικών ρυθμίσεων. Για παράδειγμα, οι μεταφράσεις σε παραδοσιακή κινεζική θα πρέπει να τοποθετηθούν στον κατάλογο nl/zh/TW. Ο κατάλογος nl/<language>/<country> έχει υψηλότερη προτεραιότητα από τον κατάλογο nl/<language>. Εάν δεν βρεθεί το αρχείο του καταλόγου nl/<language>/<country>, μόνο τότε θα χρησιμοποιηθεί το αρχείο του καταλόγου nl/<language>. Η αναζήτηση στον κεντρικό κατάλογο μιας πρόσθετης λειτουργίας θα πραγματοποιηθεί τελευταία.
Η τεκμηρίωση που περιέχεται στο doc.zip μπορεί να τροποποιηθεί τοπικά σε ένα αρχείο doc.zip με μεταφρασμένη έκδοση των εγγράφων και το doc.zip να τοποθετηθεί στον κατάλογο
nl/<language>/<country> ή nl/<language>. Το σύστημα βοήθειας θα αναζητά τα αρχεία των καταλόγων αυτών, πριν πραγματοποιήσει αναζήτηση στον προεπιλεγμένο κατάλογο της πρόσθετης λειτουργίας.
Copyright (c) 2000, 2006 IBM Corporation και άλλων.
Με την επιφύλαξη παντός δικαιώματος. Αυτό το πρόγραμμα και τα συνοδευτικά του υλικά διατίθενται βάσει των όρων της κοινής άδειας χρήσης Eclipse Public License v1.0 που συνοδεύει αυτή τη διανομή και διατίθεται στην ακόλουθη διεύθυνση: http://www.eclipse.org/legal/epl-v10.html.