Manualer, Subversion, UDO

Denne side beskriver hvordan vi håndterer vores kildestof til manualer med Subversion og UDO.

Der er intet der er ældre end din udskrevne manual fra i går.

Manualer er nødt til at følge trop med den fortsatte udvikling af programmerne. Derfor kan det anbefales at anbringe alt dit kildestof på en delt server, at give alle forfattere og oversættere direkte adgang til materialet. Vi mener at Subversion er det perfekte værktøj for dette job.

Subversion håndterer filerne for samtidig redigering

Takket være Subversion (herefter kaldet SVN) kan vi give vores manual forfattere og oversættere direkte adgang til vores manualer og samtidig sikre at ingen kan ødelægge kilderne, flere forfattere kan arbejde samtidig på filerne og alle filer vil altid have en unik tilstand.

Som en manual forfatter, behøver du ikke at forstå SVN komplet, kun disse begreber:

1. Repository
   En manuals data er opbevaret i et 'lager' på vores SVN server. Lageret viser altid den aktuelle tilstand af disse data for alle forfattere.
2. Checkout
   Hvis du henter data fra SVN serveren til din computer (checkout), opretter du en ''Arbejdskopi' på din harddisk, som du kan redigere i så meget som du vil.
3. Commit
   Når du sender dine ændringer tilbage til SVN serveren (commit), vil de herefter være tilgængelige for alle andre forfattere.

Et lukket samfund!

Kun vores udviklere, manual forfattere og oversættere får adgang til vores SVN server. SVN serveren gemmer og håndterer flere forskellige lagre men hvert lager har dets egne adgangsregler.Vores holdning: For meget frihed kan bringe dig i vanskeligheder. Hvis du ønsker at få adgang til et bestemt lager på vores SVN server, skal du bruge en SVN konto, og et SVN password. Begge kan fås fra os på admodning.

Hvordan får jeg fat på filerne?

OS X

Hvis du arbejder med Apple's udviklingsværktøj Xcode, behøver du ikke at installere andre værktøjer, idet Xcode understøtter SVN automatisk. Du behøver kun at aktivere det. Se hvordan i Xcode manualen.

Ellers er Subversion og et grafisk brugerinterface (GUI) for SVN nødvendigt, for at gøre det lidt sjovere at bruge Checkout og Commit end fra command-linjen.

• Subversion
• SVN GUI: SmartSVN
• alternativt: SVN GUI: svnX

Windows

Subversion og et grafisk brugerinterface (GUI) for SVN nødvendigt, for at gøre det lidt sjovere at bruge Checkout og Commit end fra command-linjen. Vi anbefaler GUI værktøjet TortoiseSVN.

• Subversion
• SVN GUI: TortoiseSVN

Hvordan ser manual-kilderne ud?

Vi skriver vores manualer i UDO format, et universelt format med en let tilgang. Lagrene er grundlæggende organiseret som følgende eksempel (som refererer til OS X programmer):

/cs.lproj/
/cs.lproj/<Help Book name>/
/da.lproj/
/da.lproj/<Help Book name>/
/de.lproj/
/de.lproj/<Help Book name>/
/en.lproj/
/en.lproj/<Help Book name>/
/fr.lproj/
/fr.lproj/<Help Book name>/
/it.lproj/
/it.lproj/<Help Book name>/
/nl.lproj/
/nl.lproj/<Help Book name>/
/UDoSource/
/UDoSource/_INCLUDE/
/UDoSource/<various folders>
/UDoSource/<ProjectName>_main_cs.u
/UDoSource/<ProjectName>_main_da.u
/UDoSource/<ProjectName>_main_de.u
/UDoSource/<ProjectName>_main_en.u
/UDoSource/<ProjectName>_main_fr.u
/UDoSource/<ProjectName>_main_it.u
/UDoSource/<ProjectName>_main_nl.u

Mappestrukturen (*.lproj) som vist herunder er en kopi af de sprogafhængige projektmapper for programmet. De indeholder Apple Help Book mapper som kan kopieres direktet til program kilden.

Mappen UDoSource indeholder alle data som skal oversættes. Vi har defineret vores egen nomenklatur for fil-typer, såsom disse:

• .cs = Tjekkiske tekst filer
• .da = Danske tekst filer
• .de = Tyske tekst filer
• .en = Engelske tekst filer
• .fr = Franske tekst filer
• .it = Italienske tekst filer
• .nl = Hollandske tekst filer

• .u = UDO command files
• .ui = UDO include files
• .uli = UDO library include files

Selvfølgelig behøver lagrene ikke præcist at indeholde disse viste mapper og sprog.

UDO Format, hvad er det for noget?

UDO anvender en meget simpel syntaks til at strukturere teksten, tilføje tekst egenskaber, inkludere billeder, links o.s.v. Det gode i UDO er det's virkelig nemme tilgang, selvom det giver mange forskellige muligheder. Vi prøver at undgå 'overflods-smartness' i vores manualer og bruger kun enkelte af UDO's syntaks elementer.Her er nogle eksempler:

Strukturering af tekst

!begin_node starter et nyt afsnit.
!end_node slutter et afsnit.
# i starten af en linje, adviserer UDO om at ignorere hele linjen (kommentar-linje).
!hline viser en vandret linje.
(!nl) tvunget linje-skift. (Grundlæggende slutter UDO et tekstafsnit når det møder to linjeskift.)

Tekst egenskaber

(!B) og (!b) slår fed skrift til/fra.
(!I) og (!i) slår kursiv skrift til/fra.
(!U) og (!u) slår understregning til/fra.

(Der er mange andre egenskabs-kommandoer; vi ignorerer de fleste af dem.)

Lister

!begin_itemize og !end_itemize omfatter en usorteret liste.
!begin_enumerate og !end_enumerate omfatter en nummereret liste.
!begin_description og !end_description omfatter en beskrivende liste.
!item opretter et liste-punkt.

(Der er mange flere layout-kommandoer; vi ignorerer de fleste af dem.)