Writing an Application Manual/da: Difference between revisions

From KDE UserBase Wiki
(Created page with "* Titlen på et afsnit/underafsnit skal være præcis det samme som sidens navn, eller vil links ikke fungere i Docbook.")
(Created page with "{{Note/da|1=Hvis du arbejder på Amaroks manual, så vær opmærksom på, at nogle af siderne afviger fra den normale navngivningskonvention. For at finde alle matchende sider...")
 
(25 intermediate revisions by 2 users not shown)
Line 27: Line 27:
*** Appname/Manual/''afsnit 1''/''underafsnit 2''
*** Appname/Manual/''afsnit 1''/''underafsnit 2''
og så videre.
og så videre.
{{Info/da|Sidenavnene behøver ikke at følge dokumentets struktur tæt! I eksemplet ovenfor kunne du blot bruge Prognavn/Manual/''underafsnit 2'' i stedet for Prognavn/Manual/''Afsnit 1''/''underafsnit 2'' og tilsvarende for under-underafsnit (når blot denne fremgangsmåde ikke giver anledning til gentagelse af sidenavne {{Smiley}}).}}
{{Remember/da|Prøv at holde dine sidenavne korte og undgå lange stier. Meget lange sidenavne er besværlige at skrive når du linker til dem og de ser ikke godt ud på wiki-siderne. Og husk altid: Sidenavnene og deres struktur har overhovedet ingen indflydelse på den færdige håndbog! Den bestemmes helt og holdent af overskrifterne i den faktiske tekst.}}


For at den automatisk dannede Docbook skal få samme indholdsfortegnelse som den, du laver på UserBase og for at linkene skal fungere i Docbook er der et par retningslinjer, som skal følges:
For at den automatisk dannede Docbook skal få samme indholdsfortegnelse som den, du laver på UserBase og for at linkene skal fungere i Docbook er der et par retningslinjer, som skal følges:
Line 32: Line 36:
* Indholdsfortegnelsen i Docbook vil indeholde alle afsnit og underafsnit, uanset om de har deres egen side eller ej. Omvendt vil under-underafsnit ikke blive medtaget i Docbooks indholdsfortegnelse, ikke engang hvis de har deres egne sider.
* Indholdsfortegnelsen i Docbook vil indeholde alle afsnit og underafsnit, uanset om de har deres egen side eller ej. Omvendt vil under-underafsnit ikke blive medtaget i Docbooks indholdsfortegnelse, ikke engang hvis de har deres egne sider.


* Alle sider skal starte med en overskrift som det aller første på siden, enten et afsnit (== ... ==), et underafsnit (=== ... ===) eller et under-underafsnit (==== ... ====); ellers vil Docbook-strukturen blive ødelagt.
* Alle sider skal starte med en overskrift som det allerførste på siden, enten et afsnit (== ... ==), et underafsnit (=== ... ===) eller et under-underafsnit (==== ... ====); ellers vil Docbook-strukturen blive ødelagt.


* Titlen på et afsnit/underafsnit skal være præcis det samme som sidens navn, eller vil links ikke fungere i Docbook.
* Titlen på et afsnit/underafsnit skal være præcis det samme som sidens navn, eller vil links ikke fungere i Docbook.


* Subsection titles must be written like this: <code>==='''''title'''''===</code>, even if it is the top level on a page. Otherwise the Docbook structure will be messed up. Similarly, if you have a very long subsection with subsubsections on pages of their own, these pages must have their titles written like this: <code>===='''''title'''''====</code>.
* Titlen på et underafsnit skal skrives således: <code>==='''''titel'''''===</code>, selv hvis det er det højeste niveau på siden; ellers bliver strukturen af Docbook ødelagt. Tilsvarende, hvis du har meget lange underafsnit med under-underafsnit på egne sider, så skal disse under-underafsnits titler skrives således: <code>===='''''titel'''''====</code>.


* Subsubsections that should not appear in the contents page and should not appear on a page of its own in the Docbook must be level 4 or below, i.e ==== or more.
* Under-underafsnit, som ikke skal med i indholdsfortegnelsen og som ikke skal have deres egne sider i Docbook skal være på niveau 4 eller lavere, dvs. ==== eller mere.


* Links to pages in the manual must exactly match the page name (i.e. no links via redirects!)
* Links til sider i manualen skal passe præcist med sidernes navne (dvs. ingen links via omdirigeringer!)


* If you link to a subsection of a page, you must have an anchor at the target location. Failing that will mess up Docbook links as well as translations.
* Hvis du vil linke til et underafsnit på en side, så skal du have et anker ved linkets mål. Har du ikke det, så vil linket hverken virke i Docbook eller i oversættelser.


{{Note|1=Every subsection (===) gets a page of its own in the Docbook, even if it is part of a longer page on UserBase. This means that a section (==) that contain a number of subsections, but no text before the first subsection gets a Docbook page that contains nothing but links to the subsections.}}
{{Note/da|1=Hvert underafsnit (===) får sin egen side i Docbook, uanset om det er en del af en længere side på UserBase. Dette betyder, at et afsnit (==), som indeholder et antal underafsnit men ingen tekst før det første underafsnit får en Docbook-side, som ikke indeholder andet end links til underafsnittene.}}


{{Remember|1=If at some point you decide to change the title of the main (sub)section of a page (the first headline), it is important that you also change the name of the page accordingly, and also that all links to that page are modified to match the new name.}}
{{Remember/da|1=Hvis du på et tidspunkt beslutter dig for at ændre titlen på en sides første (under)afsnit (den første overskrift), så er det vigtigt, at du også ændrer navnet på siden til det samme og også, at du ændrer alle links til siden, sådan at de passer med det nye navn.}}


{{Remember/da|1=<span  style="color:red;">Undgå enhver brug sætningstegn i sidenavne</span> &mdash; sætningstegn som spørgsmålstegn og punktummer giver alvorlige problemer for wikisoftwaren, ikke mindst for oversættelsessystemet.}}
{{Remember/da|1=<span  style="color:red;">Undgå enhver brug sætningstegn i sidenavne</span> &mdash; sætningstegn som spørgsmålstegn og punktummer giver alvorlige problemer for wikisoftwaren, ikke mindst for oversættelsessystemet.}}
Line 78: Line 82:
* Vær konsistent i formatteringen af programnavne (undgå at skrive '''Amarok'''s, skriv '''Amarok's''' &mdash; på dansk dog '''Amaroks''').
* Vær konsistent i formatteringen af programnavne (undgå at skrive '''Amarok'''s, skriv '''Amarok's''' &mdash; på dansk dog '''Amaroks''').


<span class="mw-translate-fuzzy">
* Sørg for, at ''alle'' billeder er i PNG-format (du kan også bruge JPEG, men i så fald bør de konverters til PNG ved hjælp af scriptet). Gør dit arbejde nemmere ved at konvertere dem fra begyndelsen af [[Image:Smiley.png|16px]].
* Sørg for, at ''alle'' billeder er i PNG-format (du kan også bruge JPEG, men i så fald bør du konvertere dem til PNG senere). Gør dit arbejde nemmere ved at konvertere dem fra begyndelsen af [[Image:Smiley.png|16px]].
</span>


<!--{{-->* Fjern alle blanktegn fra billednavne.}}
<!--{{-->* Fjern alle blanktegn fra billednavne.}}
==== Formatteringshensyn ====
For at din manual skal kunne overføres til Docbook-format er der nogle begrænsninger, som skal overholdes.
* [[Special:myLanguage/Toolbox#Notes and Warnings|Noter og advarsler]] understøtter ikke alternative titler i Docbook. Skriv ikke sådan noget som  <br /><code><nowiki>{{Remember|2=Don't Forget This!|1=You can use...}}</nowiki></code><br /> Argumentet <code>2=...</code> har ingen mening i Docbook og programmet, som omformer wiki-siderne til Docbook kan blive meget forvirrede. Skriv kun <br /><code><nowiki>{{Remember|1=You can use...}}</nowiki></code>
* [[Special:myLanguage/Toolbox#Embed a Video|Indlejring af video]] har nogle begrænsninger i sin nuværende implementering: Kun YouTube og Vimeo er understøttet og der kan kun gives en værdi som argument (videoens id).


=== Søgning i manualen ===
=== Søgning i manualen ===
Line 91: Line 101:
<DPL>
<DPL>
   titlematch = %Appname/Manual%
   titlematch = %Appname/Manual%
   namespace = Draft
  nottitleregexp = .*((/[a-z][a-z](.|-..)?)|([ _][(][a-z][a-z](...)?[)]))$
   namespace = | Draft
   include = *
   include = *
   includematch = /string to search for/
   includematch = /string to search for/
  includemaxlength = 0
   resultsheader = Manual Pages:
   resultsheader = Manual Pages:
   format = ,\n* [[%PAGE%|%TITLE%]]\n,,
   format = ,\n* [[%PAGE%|%TITLE%]]\n,,
Line 100: Line 112:


Du kan finde flere eksempler på brugen af DPL på [[User:Claus_chr/DPL]].
Du kan finde flere eksempler på brugen af DPL på [[User:Claus_chr/DPL]].
{{Note/da|1=Hvis du arbejder på Amaroks manual, så vær opmærksom på, at nogle af siderne afviger fra den normale navngivningskonvention. For at finde alle matchende sider fra Amaroks manual brug {{Input|1=titlematch = %Amarok/QuickStartGuide%{{!}}%Amarok/Manual%}} (Bemærk, at der ikke må være mellemrumstegn før eller efter '{{!}}'-tegnet)}}


== Forbered manualen for oversættelse ==
== Forbered manualen for oversættelse ==


* Den nødvendige tilpasning af markup'en er beskrevet på [[Special:myLanguage/Edit Markup|Preparing a Page for Translation]]. Følg denne guide, da nogle gamle markup-stile ikke længere er relevante.
* Den nødvendige tilpasning af markup'en er beskrevet på [[Special:myLanguage/Edit Markup|Preparing a Page for Translation]]. Følg denne guide, da nogle gamle markup-stile ikke længere er relevante.
== Hvordan man laver en DocBook-manual ==
Når du er færdig med din manual, så kan du få den overstat til DocBook-format, sådan at dit arbejde kan bruges som enhver anden KDE-maunual. Proceduren er beskrevet på [[Special:myLanguage/How_To_Convert_a_UserBase_Manual_to_Docbook|denne side]].


[[Category:Bidrag/da]]
[[Category:Bidrag/da]]

Latest revision as of 20:00, 7 July 2019

Other languages:

Bemærkninger

Manualer vil blive inkluderet som undersider af programmets hovedside. For nemheds skyld vil jeg omtale hovedsiden som Prognavn. Strukturen bliver så noget i retning af:

  • Prognavn
    • Prognavn/Vink og tips
  • Prognavn/Manual # Indholdsfortegnelse
    • Prognavn/Manual/En introduktion til Prognavn
    • Prognavn/Manual/Konfigurationsmuligheder
    • Prognavn/Manual/Første gang du bruger Prognavn
    • Prognavn/Manual/afsnit 1
    • Prognavn/Manual/afsnit xxx
    • Prognavn/Manual/Vink og tips
    • Prognavn/Manual/Fejlløsning
    • Prognavn/Manual/Programfejl
    • Prognavn/Manual/Involver dig #link til techbase etc

Hvis dine afsnit bliver for lange, så kan du placere underafsnit på separate sider. Det kunne se sådan ud:

  • Appname/Manual # Indholdsfortegnelsen
    • Appname/Manual/An Introduction to Appname
    • Appname/Manual/Configuration Choices
    • Appname/Manual/The First Time you use Appname
    • Appname/Manual/afsnit 1
      • Appname/Manual/afsnit 1/underafsnit 1
      • Appname/Manual/afsnit 1/underafsnit 2

og så videre.

Information

Sidenavnene behøver ikke at følge dokumentets struktur tæt! I eksemplet ovenfor kunne du blot bruge Prognavn/Manual/underafsnit 2 i stedet for Prognavn/Manual/Afsnit 1/underafsnit 2 og tilsvarende for under-underafsnit (når blot denne fremgangsmåde ikke giver anledning til gentagelse af sidenavne ).


Husk!

Prøv at holde dine sidenavne korte og undgå lange stier. Meget lange sidenavne er besværlige at skrive når du linker til dem og de ser ikke godt ud på wiki-siderne. Og husk altid: Sidenavnene og deres struktur har overhovedet ingen indflydelse på den færdige håndbog! Den bestemmes helt og holdent af overskrifterne i den faktiske tekst.


For at den automatisk dannede Docbook skal få samme indholdsfortegnelse som den, du laver på UserBase og for at linkene skal fungere i Docbook er der et par retningslinjer, som skal følges:

  • Indholdsfortegnelsen i Docbook vil indeholde alle afsnit og underafsnit, uanset om de har deres egen side eller ej. Omvendt vil under-underafsnit ikke blive medtaget i Docbooks indholdsfortegnelse, ikke engang hvis de har deres egne sider.
  • Alle sider skal starte med en overskrift som det allerførste på siden, enten et afsnit (== ... ==), et underafsnit (=== ... ===) eller et under-underafsnit (==== ... ====); ellers vil Docbook-strukturen blive ødelagt.
  • Titlen på et afsnit/underafsnit skal være præcis det samme som sidens navn, eller vil links ikke fungere i Docbook.
  • Titlen på et underafsnit skal skrives således: ===titel===, selv hvis det er det højeste niveau på siden; ellers bliver strukturen af Docbook ødelagt. Tilsvarende, hvis du har meget lange underafsnit med under-underafsnit på egne sider, så skal disse under-underafsnits titler skrives således: ====titel====.
  • Under-underafsnit, som ikke skal med i indholdsfortegnelsen og som ikke skal have deres egne sider i Docbook skal være på niveau 4 eller lavere, dvs. ==== eller mere.
  • Links til sider i manualen skal passe præcist med sidernes navne (dvs. ingen links via omdirigeringer!)
  • Hvis du vil linke til et underafsnit på en side, så skal du have et anker ved linkets mål. Har du ikke det, så vil linket hverken virke i Docbook eller i oversættelser.

Note

Hvert underafsnit (===) får sin egen side i Docbook, uanset om det er en del af en længere side på UserBase. Dette betyder, at et afsnit (==), som indeholder et antal underafsnit men ingen tekst før det første underafsnit får en Docbook-side, som ikke indeholder andet end links til underafsnittene.


Husk!

Hvis du på et tidspunkt beslutter dig for at ændre titlen på en sides første (under)afsnit (den første overskrift), så er det vigtigt, at du også ændrer navnet på siden til det samme og også, at du ændrer alle links til siden, sådan at de passer med det nye navn.


Husk!

Undgå enhver brug sætningstegn i sidenavne — sætningstegn som spørgsmålstegn og punktummer giver alvorlige problemer for wikisoftwaren, ikke mindst for oversættelsessystemet.


Du vil få brug for en testområde til at eksperimentere med afsnitoverskrifter og sider. Du kan enten bruge din personlige UserBase-side eller diskussionssiden knyttet til det område, hvor du arbejder. Det er en stor hjælp, hvis du fjerner alt, hvad du ikke længere skal bruge, når du er færdig med det.

Udvikling af en manual

Under udviklingen af din manual er det som regel bedst at holde den adskilt fra de almindelige UserBase-sider. Nogle foretrækker at redigere deres udkast som undersider til deres Talk:-side. Vi har også et særligt navnerum, Draft:, til dette formål.

For at lave indholdssiden til din manual skriver du blot http://userbase.kde.org/Draft:Appname/Manual i browserens adresselinje eller skriver linket [[Draft:Appname/Manual]] på en side og klikker så på det. På begge måder kommer du til en side, som siger, at den ønskede side ikke eksisterer, men at du kan oprette den ved at klikke på et link.

Indhold

  • Når du har lavet din plan (det kan være en langvarig proces), så lav links til alle de sider, du vil skrive i indholdsfortegnelsen. Du kan selvfølgelig altid indsætte et afsnit senere, hvis du opdager, at du har glemt noget.

Skriv manualen

  • Brug de røde links til at lave siderne og skriv et afsnit ad gangen.
  • På diskussionssiden kan du notere alt det, som du skal kigge på senere, så som links, der ikke kan laves endnu.

Husk!

Det er vigtigt at være konsistent, ikke mindst i manualer, så her er nogle almindelige regler:
  • Vær omhyggelig med overskriftniveauer — vi starter på andet niveau med == (Mediawiki bruge topniveauet til sidenavne)
  • Vær konsistent i formatteringen af programnavne (undgå at skrive Amaroks, skriv Amarok's — på dansk dog Amaroks).
  • Sørg for, at alle billeder er i PNG-format (du kan også bruge JPEG, men i så fald bør de konverters til PNG ved hjælp af scriptet). Gør dit arbejde nemmere ved at konvertere dem fra begyndelsen af .
  • Fjern alle blanktegn fra billednavne.


Formatteringshensyn

For at din manual skal kunne overføres til Docbook-format er der nogle begrænsninger, som skal overholdes.

  • Noter og advarsler understøtter ikke alternative titler i Docbook. Skriv ikke sådan noget som
    {{Remember|2=Don't Forget This!|1=You can use...}}
    Argumentet 2=... har ingen mening i Docbook og programmet, som omformer wiki-siderne til Docbook kan blive meget forvirrede. Skriv kun
    {{Remember|1=You can use...}}
  • Indlejring af video har nogle begrænsninger i sin nuværende implementering: Kun YouTube og Vimeo er understøttet og der kan kun gives en værdi som argument (videoens id).

Søgning i manualen

Før eller siden kan du få brug for at finde noget, som du skrev tidligere, men ikke kan huske hvor. Wiki'ens søgeboks er nok ikke ideel, medmindre den streng, du søger efter er meget specifik. Du kan få meget bedre kontrol over søgningen ved at bruge udvidelsen DPL. Hvis du for eksempel skal finde de sider i din manual, som indeholder en vis streng, så kan du føje følgende til hvilken side som helst: 

<DPL>
  titlematch = %Appname/Manual%
  nottitleregexp = .*((/[a-z][a-z](.|-..)?)|([ _][(][a-z][a-z](...)?[)]))$
  namespace = | Draft
  include = *
  includematch = /string to search for/
  includemaxlength = 0
  resultsheader = Manual Pages:
  format = ,\n* [[%PAGE%|%TITLE%]]\n,,
</DPL>

Du kan finde flere eksempler på brugen af DPL på User:Claus_chr/DPL.

Note

Hvis du arbejder på Amaroks manual, så vær opmærksom på, at nogle af siderne afviger fra den normale navngivningskonvention. For at finde alle matchende sider fra Amaroks manual brug 
titlematch = %Amarok/QuickStartGuide%|%Amarok/Manual%
(Bemærk, at der ikke må være mellemrumstegn før eller efter '|'-tegnet)


Forbered manualen for oversættelse

  • Den nødvendige tilpasning af markup'en er beskrevet på Preparing a Page for Translation. Følg denne guide, da nogle gamle markup-stile ikke længere er relevante.

Hvordan man laver en DocBook-manual

Når du er færdig med din manual, så kan du få den overstat til DocBook-format, sådan at dit arbejde kan bruges som enhver anden KDE-maunual. Proceduren er beskrevet på denne side.

Retrieved from "https://userbase.kde.org/index.php?title=Writing_an_Application_Manual/da&oldid=432959"