| Indstilling af dokumentationen |
| forrige | Indstilling af KDevelop | næste |
KDevelop indeholder en meget kraftig dokumentationsfacilitet som sørger for adgang til adskillig slags ekstensiv dokumentation. f.eks. i IDEAl-tilstand finder du et Dokumentationsfaneblad i højre kant af arbejdsområdet.
KDevelop's dokumentationsvinduet (IDEAl-tilstand)
KDevelop skal have indlæst Dokumentation-plugin for at kunne vise dokumentationsvinduet. Se Plugin-værktøjer-afsnittet for mere info.
Du kan indstille indholdet af dette dokumentationstræ hvis du vælger -> i menulinjen. Dialogen Indstil KDevelop dukker op, hvor du skal vælge Dokumentation i feltet til venstre.
Den viste indstillingsside viser en serie af indstillingsdialoger som fanebladsider, nemlig:
| Dokumentationssamlinger |
| Fuld tekstsøgning |
| Andre |
Opsætningen af dokumentationsindstillingerne er opdelt i en række af dokumentationssamlinger, der hver især giver adgang til dokumentationsfilerne i et eller andet unikt format og indholdstype. Disse opsætninger kontrollerer hvilke dokumentationsindgange der vil stå på listen i Indhold-siden i KDevelopDokumentation funktionen og hvordan brugeren får adgang til dokumentationsdetaljer gennem indekserede og fuldtekstsøgninger.
Fanebladet Dokumentation giver en række indstillingssider som er ordnet lodret som en stak af indekskort. En side ad gangen åbner efter et klik på dens indekskorttitel.
| Qt™ dokumentationssamling |
| CHM dokumentationssamling |
| Doxygen dokumentationssamling |
| KDevelop TOC dokumentationsamling |
| Devhelp dokumentationssamling |
| Brugerdefineret dokumentationssamling |
Indstilling af dokumentationssamlinger
Alle indstillingssiderne på Dokumentation fanebladet bruger et almindelig layout. Du finder den tilgængelige dokumentationsliste på den åbne side til venstre og et sæt knapper til højre.
Der er tre knapper til rådighed til at vedligeholde indholdet af dokumentationsopsætningssiderne:
Åbner en Dokumentationssamlingsegenskaber-dialog, som vist herunder, hvor du kan ændre kildeplaceringen af dokumentationen der skal tilføjes og hvor du også kan navngive den.
Åbner en Dokumentationssamlingsegenskaber dialog, som vist herunder, hvor du kan ændre kildeplaceringen af dokumentationen allerede valgt på listen og omdøbe den.
Fjerner den valgte dokumentationsindgang fra listen.
Indgangen bliver fjernet kun fra listen. Den egentlige dokumentationskilde bevares. Du skal bruge en anden metode for at fjerne den eksplicit.
Tilføjelse eller ændring af en indgang til dokumentationen.
Knappen til højre for Sted feltet, åbner en mappedialog, hvis indgange normalt bliver filtreret i henhold til den valgte indstilingssides filtype.
Titelfeltet er ikke altid tilgængeligt. Det afhænger af dokumentationstypen.
Hver dokumentationsindstillingsside viser dokumentationsindgangene i en tabel med fire søjler.
Hvis dette felt er afkrydset vises dokumentationsindgangen i Indholdsfortegnelsen i KDevelops Dokumentationfunktion.
Ved at fjerne afkrydsningen i TOC afkrydsningsfeltet, fjerner skiftevis afkrydsningerne i Indeks og Søg, se herunder. Derfor kan du ikke have dokumentationssamlingsindgange indekseret men ikke vist i indholdsfortegnelsen.
Hvis dette afkrydsningsfelt er afkrydset, bygges der et internt indeks af denne dokumentationsindgang. Dette medfører hurtig adgang til dokumentationen vha. Indeks og (valgfrit) Finder siderne i KDevelop Dokumentationsfunktionen.
Det interne indeks bygges første gang brugeren vælger Indekssiden. Dette gør første tilgang til indekset temmelig langsom fordi indekset skal læses fra disken og derefter lægges i cache.
Alle følgende indekssøgninger derimod, vil benytte denne cache og derfor virke markant hurtigere.
Hvis dette afkrydsningsfelt er markeret, bliver indholdet af denne dokumentationsindgang inkluderet i fuldtekstsøgestien i Søgesiden i KDevelops Dokumentationfunktion.
KDevelop benytter htdig-programsamlingen til at udføre fuldtekstsøgninger. Denne søgning udføres i et internt indeks som htdig-maskineriet er nødt til at bygge for det kan bruges.
En ændring i Søg-afkrydsningsfeltet har dermed først effekt på søgninger efter du har bygget indekset på ny, i KDevelops Dokumentationfunktion.
Dette er navnet på dokumentationsindgangen som den vil blive vist i Indhold-sfortegnelsen i KDevelops Dokumentationfunktion.
I tidligere udgaver af KDevelop var det tilladt at vælge at dokumentationsindgange kunne vises forskelligt for hvert enkelt projekt. Dette er ikke længere muligt.
På denne indstillingsside indstilles al Qt™-dokumentation.
Opsætning af Qt™-dokumentationssamlinger
Normalt vil KDevelop udfylde denne ved sin første opstart. Den leder efter standarddokumentationsfiler, *.xml, eller *.dcf, i Qt™'s installationskatalog. Tabellen til venstre giver en liste af de filer KDevelop fandt, med deres standardtitler.
Hvis du har en ikke-standardinstallation, vil der enten ingen information være overhovedet eller indgangene vil muligvis pege på forkerte steder (f.eks. til en anden Qt™-installation på dit system). Du kan justere indgangene ved brug af knapperne til højre for listefeltet.
KDevelop bruger titlerne fra Qt™-dokumentationen. Derfor er Titelfeltet i Dokumentationssamlingerdialogen ikke tilgængelig.
Som standard vises ikke al Qt™-dokumentation i Indholdsfortegnelsen i KDevelops Dokumentationfunktion. Brug TOC-afkrydsningsfeltet i tabelindstilling for at vælge dokumentationen der skal vises.
Hvis du vil have noget specifikt Qt™-dokumentation inkluderet i søgeindekset eller fuldtekstsøgning, så brug Indeks og Søg-afkrydsningsfeltet i tabelindstilling.
På denne indstillingsside kan du samle dokumentation der følger Microsoft®s CHM hjælpefilstandard.
Opsætning af Microsoft®s CHM dokumentationsfiler.
Som standard er denne indstillingsside, som vist ovenfor, tom. Du kan tilføje nye indgange ved at bruge knapperne til højre for listen. KDevelop filtrerer *.chm-filer i mappedialogerne der hører til og -knapperne.
For mere information om Microsoft®s *.chm-filformat, se f.eks. PHP: Dokumentation - Udvidet CHM format på http://de2.php.net/docs-echm.php.
På denne indstillingsside opsættes al API-dokumentation genereret af Doxygen.
Opsætning af Doxygen-genereret API-dokumentation
Kort sagt dokumenterer en API-grænsefladen til visse biblioteksfunktioner. API-dokumentation på denne side skal laves af det eksterne Doxygen-værktøj.
Doxygen-generet API-dokumentation, består af en samling html-filer, der starter med index.html. Derudover kan der eksistere tag-filer som indeholder information om hvordan der linkes til eksisterende API-dokumentation. Derfor leder KDevelop efter index.html og *.tag-filer når der søges efter Doxygen-genereret API-dokumentation.
Der antages nogle strukturelle begrænsninger når der søges efter Doxygen-genereret API-dokumentation. Kataloget hvori index.html-filen ligger, skal indeholde underkataloger med adskilte dokumentationssamlinger. Hver af disse underkataloger antages at indeholde en .tag-fil og et html/ underkatalog.
Du kan tage et kig i $ hvor der findes et eksempel på et sådant layout for dokumentation af programmeringsgrænseflade med Doxygen. KDEDIR/share/doc/HTML/en/kdelibs-apidocs
Det ældre KDE KDoc genererede API-format er ikke længere direkte understøttet. Hvis du stadig vil bruge den slags dokumentation, kan du tilføje det på Brugerdefineret documentationsamlinglssiden.
KDevelop vil have indsat et link til de nuværende KDE-bibliotekers API, hvis de ellers blev fundet på installationstidspunktet. Der er flere måder for KDevelop at finde ud af det:
Enten gav du configure kommandoen --with-kdelibsdoxy-dir flaget da du kompilerede KDevelop (se Hvordan man får fat på en KDevelop API dokumentation-kapitlet).
Eller configure kommandoen fandt automatisk en Doxygen genereret KDE-biblioteker API på et af de adskillige standardsteder den kender til.
Eller som sen sidste udvej $ blev fundet ved første opstart af KDevelop. KDEDIR/share/doc/HTML/en/kdelibs-apidocs/
Hvis KDevelop ikke fandt en gyldig Doxygen genereret KDE-API ved sin første opstart, vil listen med Doxygendokumentationssamlingen være tom.
Du kan tilføje dine egne API-dokumentationsindgange (f.eks. fra dine aktuelle projekter) ved at bruge knapperne til højre. Hvis du vil inkludere dem i den indekserede og eller fuldtekstsøgning, så afkryds Indeks ellerSøg afkrydsningsfeltet i tabelindstilling.
KDevelop bruger titelinformationen fra index.html. Derfor er Titelfeltet i Dokumentationsamlingsdialogen ikke tilgængelig.
KDE-systemet sørger for mere API-dokumentation end kun KDE-bibliotekernes API. Du vil få brug for yderligere grænsefladeinformation hvis du ønsker f.eks. at inkludere Kate-parten i dine programmer. For denne Kate-part-API for eksempel, vil du skulle kompilere og installere KDE's basisbibliotekernes API fra kilderne (ved brug af make apidox og make install kommandoerne i kdebases kilder) og så tilføje en indgang til Doxygen dokumentationssamlingslisten sådan her:
Tilføjelse af KDE's basis-API til listen
(Du skal naturligvis erstatte /home/dev/mitkde-system/-kataloget i Stedfeltet, med stien til din egen KDE-installation.)
Du er nødt til også at lægge dit nuværende projekts API ind i Doxygendokumentationssamling. I tidligere KDevelopudgaver lagde det ind i dokumentationen for hvert enkelt projekt. Dette er ikke længere understøttet.
Hoveddelen af KDevelop's dokumentationstræ sørger for umiddelbar adgang til struktureret dokumentation, lokal så vel som ekstern. Du kan indstille dette i KDevelopTOC dokumentationssamling-fanebladet i Dokumentationsamlinger-indstillingssiden.
Sørger for KDevelopTOC-struktureret dokumentationsadgang
KDevelop kommer med en mængde foruddefinerede KDevelopTOC-filer som automatisk tilføjes i tabellen på installationstidspunktet. For at holde visningen overskuelig, er det kun de oftest brugte der makeres til visning. Hvis du vil kunne se andet dokumentation så afkryds TOC afkrydsningsfeltet i tabelindstilling.
KDevelopTOC-filer kan ikke indekseres så der kan udføres fuldtekstsøgning, fordi de normalt peger på en ekstern placering. På den anden side kan en .toc-fil få et manuelt defineret indeks, ved at bruge <index> mærket. Derfor vil Indeks afkrydsningsfeltet kun være aktiveret når KDevelop finder et <index> mærke i .toc -filen. (For mere information, se beskrivelsen herunder i KDevelop TOC Filer sektionen.)
Søg afkrydsningsfeltet i tabelindstilling vil altid være deaktiveret.
Du kan tilføje nye indgange ved at bruge knapperne til højre for listen. KDevelop vil filtrere *.toc-filer i mappedialogerne der hører til og -knapperne.
Kun i ældre udgaver af KDevelop vil -knappen ikke ændre *.toc-filer på disken, så fjern-funktionen er sikker nu.
Der er en særlig funktion knyttet til dette. For at illustrere det, følg disse skridt: I dokumentationstræet findes en indgang lige under Qt™/KDE-dokumentationen (f.eks. “KDE2 Udviklingsbog (kde.org)”). Klik på plus-tegnet ved siden af den. Et træ vil blive åbnet hvor du hurtigt kan navigere til de følgende kapitler adskillige lag dybt, altsammen offline. Men hvis du vælger et af kapitlerne, vil KDevelop i mange tilfælde prøve at få adgang til en ekstern dokumentationsfil.
Rationalet bag dette er ikke kun at navigere ekstern dokumentation lokalt uden at spilde ressourcer på adgang til nettet, men også at give udvikleren nem og struktureret adgang til den ønskede dokumentation. Med de værktøjer der er til rådighed her, kan man få adgang til næsten al lokal eller ekstern dokumentation på en struktureret måde, selvom originalen er lagt fladt ud eller struktureret på en anden måde. Det eneste der behøves, er adgang til filer og/eller dele af filer, som kan vises med Konqueror.
Sådan struktureret adgang er gjort mulig ved brug af specielle “indholdsfortegnelses”filers, som er betegnet med .toc filnavneendelser. Enhver sådan af KDevelop's TOC-filer indeholder en XML™-struktureret beskrivelse af dokumentet der skal bruges.
Da KDevelop blev installeret blev der normalt lagt en række prædefinerede .toc-filer ind i mappen $KDEDIR/share/apps/kdevdoctreeview/tocs. Disse er temmelig simple, strukturerede tekstfiler. Du kan studere dem med en teksteditor eller anden tekstvisningsfacilitet.
Basal struktur af KDevelop's TOC-filer
<!DOCTYPE kdeveloptoc>
|
<kdeveloptoc>
|
| (titel) |
| (basisadresse) |
| (indholdsstruktur) |
| (indeksstruktur) |
</kdeveloptoc>
|
Denne XML™-struktur vil blive tolket af KDevelop's Dokumentation-plugin for at indstille dokumentationstræets indhold og hjælpe brugeren med at navigere dokumentationen. Den indeholder al den nødvendige information til at vise titlet og få adgang til dokumentationsfilernes indhold.
<title> (en titelstreng) </title> |
Dette er den titel som KDevelop vil vise på de basale niveauer i dokumentationstræet.
Denne viste titel kan for øjeblikket ikke ændres af brugeren. Hvis du ønsker at en anden tekst skal vises, må ændre <title>-indgangen i .toc-filen manuelt.
<base href=" (basisdokument URL) "/> |
Denne URL peger på stedet hvor alle filerne i denne dokumentation er. Den vil blive sat forud for hvert afsnits-URL i følgende indholdsstrukturliste. Så, hvis du f.eks. hentede en dokumentation fra en ekstern server, er alt du behøver for at vise filerne fra dette nye sted at ændre dets <basis>-URL.
<tocsect1 name=" (afsnittets titel) " url=" (afsnittets URL) "> |
| ... |
<tocsectn name=" (afsnittets titel) " url=" (afsnittets URL) "/> |
| ... |
</tocsect1>
|
Al øvrig navigations og adgangsinformation er opbevaret i en række indlejrede <tocsecti> ... </tocsecti> par. Hvert i betegner det følgende indlejringsniveau ned til nummer n som vil svare til det endeligt viste dokumentationsafsnit.
Enhver <tocsecti>-indgang skal have en name="xxx"-attribut tilknyttet (hvor "xxx" betegner den faktiske titelstreng). Dette vil blive vist som niveautitlen i dokumentationstræet. Det skal svare til et egentligt dokumentationsafsnit.
Der kan være en url=""-attribut knyttet til ethvert i indlejringsniveau. Når brugeren klikker på et afsnit titel i dokumentationstræet vil KDevelop forsøge at få adgang til filen på det sted der peges på af den kombinerede basis- og afsnits-URL.
<tocsectn/>-indgangen skal have en url=""-attribut under alle omstændigheder. Den endelige indlejrede <tocsectn/> kommer ikke i par men vil umiddelbart blive lukket af en / før >-parentesen.
Enhver adresse kombineret af basis- og afsnits-URL skal pege på en tekstfil der kan fremvises. Sædvanligvis vil dette være en HTML-struktureret fil. Det er muligt at linke til ankermærker indenfor sådan en HTML-fil ved brug af standard # notation i formatet: /base-url/section-url#anker-mærke.
<index>
|
<entry name=" (afsnittets titel) " url=" (afsnittets URL) "/> |
</index>
|
Indeks er en enkel liste med indeksindgange, par af titler og URL'er. Et indeks er ikke obligatorisk.
DevHelp dokumentation er en anden måde for struktureret dokumentationsadgang. Den bruger strukturerede tabeller af indholdsfiler betegnet med en .devhelp-endelse ligesom KDevelop's TOC-filer for at få adgang til dokumentationen for GNOME 2 desktoppen.
Du kan kontrollere hvilke DevHelp-filer der skal være adgang til, på DevHelp dokumentationssamlingindstillingssiden.
Sørger for DevHelp dokumentation
DevHelp-filerne kunne oprindeligt nås på hjemmesiden LiDN, men det synes ikke længere at være vedligeholdt et stykke tid nu. Mere nylig DevHelp-dokumentation er tilgængelig på hjemmesiden Nedtagning af DevHelp-bøger.
Når KDevelop installeres, vil det forsøge at finde alle .devhelp-filer i nogle standardplaceringer i systemet, f.eks. i underkatalogerne af /opt/gnome/share/. Til at begynde med markeres disse filer ikke til visning. Hvis du vil se anden dokumentation skal du afkrydse TOC-afkrydsningsfeltet i tabelindstilling.
Du kan tilføje nye indgange ved at bruge knapperne til højre for listen. KDevelop vil filtrere *.toc-filer i mappedialogerne der hører til og -knapperne.
Dette er til eget brug. Du kan tilføje stort set alle dokumentationsfiler her, forudsat at de kan vises med en Konqueror-plugin.
Sørger for brugerdefineret dokumentation
Normalt er denne liste tom ved KDevelops første opstart. Vi har lagt en indgang ind for at vise indgangsstrukturen.
Håndteringen er ligeud ad landevejen her. Brug knapperne til højre for listen for at tilføje, redigere eller fjerne dokumentationsindgangene. KDevelop vil ikke filtrere noget som helst i mappedialogen der hører til og -knapperne.
Du skal eksplicit tilføje indgangene der skal vises i KDevelops dokumentationsfunktion. Afkryds indgangens TOC afkrydsningsfeltet i tabelindstilling.
Brugerdefineret dokumentation kan hverken indekseres eller søges i. Derfor er Indeksx og Søg afkrydsningsfelterne ingen effekt, som vist herover.
| forrige | hjem | næste |
| Indstilling af KDevelop | op | Avancerede indstillinger |
