Skriftlig Info ➜ DITA-publisering ➜ DITA topics ➜ DITA Reference topic
Her er en den offisielle beskrivelsen fra Oasis (i min oversettelse):
Referanseemner gir data som støtter brukere når de utfører en oppgave. Referanseemner kan gi lister og tabeller som inkluderer produktspesifikasjoner, delelister og andre data som ofte blir "slått opp" i stedet for huskes. Et referanseemne kan også beskrive kommandoer i et programmeringsspråk eller nødvendige verktøy for en rekke vedlikeholdsoppgaver. Referanseemner gir rask tilgang til faktabasert informasjon. I teknisk informasjon brukes referanseemner for å liste opp produktspesifikasjoner og parametere, gi viktige data og gi detaljert informasjon om emner som kommandoene i et programmeringsspråk. Referanseemner kan inneholde alle emner som har vanlig innhold, for eksempel ingredienser til mat i oppskrifter, bibliografiske lister, katalogartikler og så videre.
Oasis: "Reference topic", docs.oasis-open.org, [REF]
Jeg velger å definere reference topic på denne måten:
En DITA Reference topic er en frittstående datamodul som inneholder multimodal tekst. Modulen har en tittel og nok informasjon til å formidle nødvendig detaljert informasjon om noe leseren kan ha nytte av i forbindelse med en oppgave, men ikke nødvendigvis trenger å huske. Informasjonen skal formidle faktabasert informasjon for å støtte opp om forståelsen av de oppgavene som produktet utfører. En Reference topic skal således formidle detaljerte beskrivelser som kan hentes frem ved behov for å hjelpe leseren med å forstå et produkts tekniske spesifikasjoner eller grunnleggende funksjonalitet.
På sett og vis kan du si at en concept topic gir leseren informasjon som det er "nødvendig å ha" for å forstå produktet. En reference topic formidler informasjon som det er "kjekt å ha". Dette er informasjon som leseren strengt tatt ikke trenger for å bruke produktet, men som er nyttig for de som ønsker mer detaljert informasjon. Det er du som må plassere informasjonen i en av de to kategoriene. Dette er det nyttig å diskutere i fagmiljøet for å etablere retningslinjer.
En reference topic er enkel å bruke fordi strukturen er åpen. Informasjonen kan presenteres med alle relevante DITA-elementer, med unntak av de som er spesifikke for task topic.
En DITA reference concept er strukturert som følger:
<title>
Alle reference topics skal ha en tittel.
<shortdesc>
Alle reference topics må ha en "short description" som definerer kontekst.
<prolog>
Dette elementet kan brukes for å legge inn indeks-informasjon. Denne informasjonen kan forøvrig også legges inn andre steder i topic'en.
<refbody>
Dette elementet brukes for å samle all informasjonen i topic'en. Se Struktur for <refbody>
Av disse elementene er det bare <title> og <refbody> som er obligatoriske.
Strukturen i <refbody> er åpen. De grunnleggende elementen kan plasseres i tilfeldig rekkefølge uten viktige begrensninger. Det er ikke hensiktsmessig å forklare alle elementene her. De vanligste elementene som brukes er:
<section>
I reference topics må <section> brukes for å samle andre elementer under et felles element. <section> brukes for å samle undeliggende elementer under et felles hovedelement. <section> kan ha en <title>, og elementet kan deles videre i <sectiondiv>- og/eller <div>-elementer. <section>-elementer kan ikke plasseres inni hverandre.
<p>
<p> er en paragraf som kan inneholde en eller flere setninger. <p> kan legges rett inn under <section>.
<ul>
<ul> er en unummerert liste (Engelsk: unordered list), også kalt "bulletliste". Den kan inneholde en eller flere punkter. <ul> kan legges rett inn under <section>. <ul>-lister kan plasseres inni hverandre for å skape flere nivåer. Du kan også legge <ul>-lister inn i <ol>-lister og omvendt.
<ol>
<ol> er en nummerert liste (Engelsk: ordered list). Den kan inneholde en eller flere nummererte punkter. <ol> kan legges rett inn under <section>. <ol>-lister kan plasseres inni hverandre for å skape flere nivåer. Du kan også legge <ol>-lister inn i <ul>-lister og omvendt.
|
Det kan være fristende å bruke <ol>-elementet for å lage en nummerert liste, og deretter kalle dette en prosedyre. Dette er ikke tillatt, og det er et direkte brudd på hele filosofien som DITA representerer. Prosedyrer skal og må plasseres i Task topics. Concept topics skal bare inneholde forklarende og beskrivende informasjon. |
Noen steder er det ønskelig bytte ut nummerne i listen med store eller små bokstaver, eller kanskje romertall. Dette gjøres ved hjelp av attributter, og må implementeres i stilarket. Generelt er det for eksempel lurt å bruke bokstaver når man skal henvise til detaljer i en illustrasjon. En liste med A, B, C osv kan ikke misforstås som en prosedyre.
<dl>
<dl> er en liste for å forklare terminologi, og brukes ofte for å liste opp valg i en meny. Den kan inneholde en eller flere termer i <dlentry>-strukturer. <dl> kan legges rett inn under <section>.
<div>
<div> brukes for å samle andre elementer under et felles element. Dette er nyttig ved profilering og gjenbruk.
<example>
<example> brukes som navnet tilsier til å beskrive et eksempel.
Om ønskelig kan elementet <refbodydiv> også brukes for å samle informasjon. En <refbodydiv> har samme egenskaper som en et <refbody>-element. Bruken av <refbody> og <section> gjør at du kan samle informasjon som hører sammen. Dette kan være svært nyttig fordi eventuell profilering av et <refbodydiv>-element også vil gjelde alt som er inni. Du kan også bruke et slikt "samle-element" i et bibliotek for å gjenbruke all informasjonen inni det på en gang.
På tilsvarende måte kan <sectiondiv> og/eller <div> brukes inni <section>.
Det som er viktig med en reference topic er den begrensningen som er tillagt <refbody>-elementet. Denne begrensningen virker på følgende måte:
Det kan høres ut som dette er en begrensning som vanskeliggjør bruken, men slik er det slett ikke. Faktisk er den ganske logisk. Hvis du for eksempel legger inn et <section>-element med en tittel, og inne i denne legger inn vanlig tekst, hvordan kan da leseren se at innholdet i <section>-elementet slutter og "annen" informasjon starter? Tittelen som brukes først i <section>-element vil jo gjelde all informasjon frem til neste tittel.
Her er et eksempel som beskriver en (svært) kort reference topic.
<reference>
<title>Dette er den tittelen som vises i publikasjonens innholdsfortegnelse</title>
<shortdesc>Dette er den innledende teksten som definerer context</shortdesc>
<refbody>
<section>
<title>Denne tittelen vises ikke i innholdsfortegnelsen, for Reference topic'en har en flat struktur</title>
<p>Brødtekst</p>
<p>Brødtekst</p>
</section>
<section>
<title>Denne tittelen vises ikke i innholdsfortegnelsen, for Reference topic'en har en flat struktur</title>
<p>Brødtekst</p>
<p>Brødtekst</p>
</section>
</refbody>
</reference>
Dette eksempelet viser en reference topic som inneholder en tittel, en kort beskrivelse (<shortdesc>), og deretter to <section>-elementer med tittel og to setninger. Når du jobber i en XML-editor vil sjelden koden se slik ut. Du trenger heller ikke huske på hvilke elementer du kan bruke hvor, for det vil editoren hjelpe deg med.
Lage en ny DITA topic fra en mal
Lage en ny DITA topic ved å duplisere en eksisterende topic
Sette en topic inn i en topic map
Sette en topic inn i en bookmap
Alle eksterne linker åpner i et nytt vindu. Jeg tar ikke ansvar for informasjon på eksterne nettsteder, selv om jeg har linket til dem. Vennligst rapporter linker som ikke virker.
Informasjonen på denne siden representerer mine personlige meninger, og min egen forståelse av temaet som beskrives. Du kan gjerne linke til siden, men ikke kopiere større deler av innholdet uten tillatelse. Jeg tar ingen ansvar for eventuelle feil, misforståelser eller manglende informasjon om omfattende temaer. Jeg tar heller intet ansvar for feil du måtte gjøre eller forårsake som et resultat av feilaktig eller manglende informasjon. Du kan gjerne bidra med kommentarer, egner erfaringer eller utfyllende informasjon. Se Kontaktinformasjonen.
2022-11-27