Hvordan man arbejder på Debians websider

Generelle oplysninger

Pladskrav

Hvis du vil arbejde på vores websted, skal du være forberedt på at afsætte mindst 250 megabyte til data på din harddisk. Dette svarer til arkivets nuværende størrelse. Hvis du (fejlagtigt) genopbygger alle siderne, skal der bruges mindst to gange så megen plads. Foretager du en delvis checkout, skal du bruge langt mindre plads, for eksempel 50 megabyte for mappen /english .

Delvis checkout

Mange behøver ikke hele CVS-træet webwml, hvilket nogle gange medfører manglende filer eller opbygninger som ikke fungerer i tilfælde af at en ny, vigtig fil bliver tilføjet og man ikke kører den fuldstændige cvs update i den pågældende mappe. Husk at kontrollere, om du har alle krævede filer (så som .wmlrc-filer) før du klager din nød.

Hvad er det for nogle linjer som begynder med #?

I WML begynder kommentarlinjer med #. Disse foretrækkes frem for almindelige HTML-kommentarer, da de ikke medtages i den endelige side.

Læs om at anvende WML for flere oplysninger om WML.

Etikette for redaktører

Kan jeg rette denne side?

Måske. Hvis du opdager en lille fejl, såsom en tastefejl, så ret den bare.

Hvis du bemærker at der mangler nogle få oplysninger, så er du også velkommen til at rette det.

Hvis du mener at noget er helt forkert og bør skrives om, så tag det op på debian-www så vi kan diskutere det. Formentlig vil vi være enige med dig.

Hvis du opdager, at der er problemer med en skabelon (dvs. en fil i mappen webwml/english/template/debian), så overvej ændringen inden, du overfører den til CVS, da ændringer af skabeloner ofte medfører at store dele af webstedet genopbygges.

Ved tilføjelse af nye mapper skal der også tilføjes Makefiler!

Man skal være omhyggelig når man tilføjer en ny mappe til CVS. Hvis den aktuelle mappe er anført i ../Makefile så skal du oprette en Makefile i mappen — ellers vil make afslutte med en fejlmeddelelse.

Brug letforståeligt engelsk

Da Debians websider læses af folk, der ikke har engelsk som modersmål og oversættes til andre sprog, er det bedst at skrive på et letforståeligt engelsk, og undgå at bruge slang, smilyer og sjældne idiomatiske udtryk.

Hvis du bruger den slags, så tilføj en kommentar til filen som beskriver meningen.

Hvis du er det mindst i tvivl, eller for at få gennemlæst dit forslag, så kontakt holdet der lokaltilpasser til engelsk.

Kig efter README-filer

Nogle af mapperne indeholder en README-fil, som en hjælp til at forstå hvordan den pågældende mappe er organiseret. Disse filer skulle gerne indeholde eventuelle særlige oplysninger, som man skal bruge for at arbejde inden for det pågældende område.

Adskil indholdsændringer fra formateringsændringer

Foretag altid separate rettelser eller commits fra indholdsændringer og formateringsændringer. Når de kombineres, er det meget sværere for oversætterne at få øje på, hvad der er ændret. Hvis du kører cvs diff med sådanne blandede ændringer, kan du selv konstatere hvor uoverskueligt det bliver.

Generelt skal man undgå formateringsændringer. At få ældre dele af websider til at overholde XHTML-/XML-standarderne, bør ikke ske samtidig med at man commit'er andre ændringer. (Nye ting kan og skal naturligvis laves korrekt fra første færd.)

Opdatér også oversættelser, om muligt

Nogle ændringer er uafhængige af sproget i WML-filen, så som ændringer af URL'er eller indlejret Perl-kode. Rettelser af tastefejl hører også til denne kategori, da oversættere normalt ignorerer dem, når de oversætter. Med sådanne sproguafhængige ændriger, kan man foretage den samme ændring i alle oversatte filer, uden at have kendskab til de andre sprog, og trygt forhøje versionsnummeret i translation-check-linjen.

Det er ikke særligt krævende for oversætterne, selv at gøre arbejdet, og det kan være upraktisk for engelsktalende redaktører, at have en komplet checkout at arbejde på. Vi opfordrer dog stadig folk til at gøre dette, for ikke at ulejlige et 20-25 personer vedrørende ting, der hurtigt kan klares af en enkelt person.

For at gøre den slags ændringer nemmere at foretage, kan man desuden anvende skriptet smart_change.pl, der ligger i den øverste mappe i webwmls CVS-modul.

Anvendelse af smart_change.pl

smart_change.pl [parametre] original-fil

Pt. tillades kun filer i /english/ som original-fil. smart_change.pl kender følgende parametre:

-s, --substitute=REGEXP
Skriv et regulært udtryk i Perl, som vil blive kørt på kildekodefilerne (kan anvendes mere end én gang). Eksempel:
      $> ./smart_change.pl -s "s,http://gammel-url/,http://ny-url/,g" english/devel/index.wml
      $> cvs diff -u */devel/index.wml | less
      $> cvs ci -m "1.23: Updated gammel-url to current location" */devel/index.wml
      
Den første kommando foretager ændringen, den anden kommando kontrollerer den engelsksprogede originale fil og alle oversættelser af den. Du bør gøre dette for at gennemse de egentlige ændringer før du commit'er dine ændringer. Hvis alt ser ud som forventet, kan du commit'e ændringerne med den tredje kommando.
-l, --lang=STRING
Dette sprog behandles (kan anvendes mere end én gang). Hvis der ikke er angivet et sprog, vil alle tilgængelige sprog blive behandlet.
-n, --no-bump
Opdatér ikke translation-check-linjer. Normalt forøges versionen i hver translation-check-linje med én, hvis de oversatte filer er ajourførte, og ændres ikke i filer, som ikke er ført ajour. Hvis paremeteret er angivet, røres der ikke ved nogen translation-check-linjer. Se om at holde oversættelser ajour for en beskrivelse af translation-check-linjerne.
-p, --previous
Vis foregående CVS-revision. Dette er primært nyttigt, hvis den engelske fil allerede er commit'et og man ønsker at kontrollere translation-check-linjerne mod den foregående version.
-h, --help
Vis en kort brugsanvisning.
-v, --verbose
Vis alle meddelelser under kørsel.

Links

Dette link ser ikke rigtigt ud. Skal jeg ændre det?

På grund af den måde webservere opsættes (anvendelse af indholdsforhandling) bør du ikke ændre nogen af de interne links. Faktisk anbefaler vi, at du ikke gør det. Skriv først til debian-www, hvis du mener at et link er forkert.

Rettelse af links

Hvis du opdager at et link til et eksternt websted medfører en viderestilling (redirection - 301, 302, en <meta>-viderestilling, eller en side, der fortæller at Denne side er flyttet.) så fortæl om det på debian-www.

Hvis du opdager et link, som ikke virker (404, 403, eller en side som ikke viser det, linket oplyser), så ret linket og fortæl om det på debian-www, så oversætterne bliver gjort opmærksomme på det. Eller endnu bedre, ret linket i alle de andre oversættelser og opdater translation-check-linjen, om muligt.

Adskillelse af tekst fra data

Hvad er foo.def- og foo.data-filerne?

For at gøre det nemmere at holde oversættelserne ajour adskiller vi på nogle sider fælles ting (data) fra selve teksten. Oversætterne behøver kun at kopiere og oversætte selve teksten, de fælles ting vil automatisk blive tilføjet.

Et eksempel vil måske gør dette nemmere at forstå. Det kræver tre filer at generere siden med forhandlerlisten i CD/vendors:

index.wml:
Teksten øverst på siden er i denne fil. En oversat kopi placeres i hvert sprogmappe.
vendors.CD.def:
Filen indeholder alle de tekstbidder som er nødvendige i hver enkelt forhandlers post. Oversættelser tilføjes via <sprog>/po/vendors.xy.po.
vendors.CD:
Denne fil indeholder de egentlige forhandlerposter og er sproguafhængige, hvorfor oversættere ikke skal ændre noget i denne fil.

Når en af dem der har ansvaret for cdvendors@debian.org tilføjer en ny forhandler, føjer de forhandleren til debiancd.db, konverterer den til WML-format som vendors.CD (ved hjælp af getvendors.pl) og lader dernæst WML og makefilerne klare resten. Alle oversættelser bliver genopbygget med anvendelse af den allerede oversatte tekst, men med de nye forhandleroplysninger. (En ajourført oversættelse, kvit og frit!)

Tilføjelse af en ny side

Det er ganske nemt at føje nye sider til Debian. WML sørger for at sidehoved og -fod bliver korrekt. Alt du skal gøre er at indsætte en linje som den følgende øverst i den nye fil:

#use wml::debian::template title="NAVN PÅ SIDEN"

efterfulgt af sidens indhold. Alle sider skal anvende skabelonsfilen wml::debian::template med mindre de anvender en særlig skabelon lavet til denne sektion, for eksempel nyhederne eller sikkerhedsbulletinerne.

Vores skabeloner giver dig mulighed for at definere bestemte variabler, som vil påvirke de oprettede sider. Det forhindrer nødvendigheden af at skulle oprette forskellige skabeloner til enhver situation og gør det nemmere at foretage forbedringer. De pt. tilgængelige variabler og deres formål:

BARETITLE="true"
Fjerner "Debian --"-delen som normalt indsættes foran alle <title>-mærkerne (tags).
NOHEADER="true"
Fjerner det indledende sidehoved fra siden. Et særligt sidehoved kan naturligvis tilføjes i selve teksten.
NOMIRRORS="true"
Fjerner listen over webspejle fra siden. Det anbefales generelt ikke, bortset fra for en håndfuld siders vedkommende.
NOHOMELINK="true"
Fjerner linket til Debians hovedside, som normalt tilføjes nederst på siden.
NOLANGUAGES="true"
Fjerner links til udgaver af siden på andre sprog, som normalt tilføjes nederst på siden.
GEN_TIME="true"
Opsætter datoen på resultatfilerne til de genererede filers tidsstempling i stedet for kildefilens tidsstempling.
NOCOPYRIGHT="true"
Fjerner ophavsretbemærkningen nederst på siden.

Bemærk at du kan anvende enhver streng som disse variablers værdi, true, yes, foo, det spiller ingen rolle.

Et eksempel på hvordan dette kan bruges er på tilpasningssiderne, der har deres egne sidehoveder. ports/arm/index.wml anvender:

#use wml::debian::template title="ARM-tilpasning" NOHEADER="yes"

Ønsker du at lave noget, som ikke kan lade sig gøre med de eksisterende skabeloner, skal du først overveje om en af dem kan udvides. Hvis det ikke er muligt at udvide en skabelon og bibeholde bagudkompatibiliteten, så prøv at lave en ny skabelon, der indeholder alt hvad en eksisterende skabelon indeholder, således at siderne kan konverteres ved den næste større opgradering (forhåbentlig aldrig hyppigere end hver sjette måned).

Hvis du er ved at oprette en side, som genereres af et skript eller kun indeholder en smule tekst, kan du overveje at bruge <gettext>-mærker (tags) for at lette arbejdet med at holde oversættelserne ajour.

Inkludering af andre filer

Ønsker du at adskille nogle dele af din side i en separat fil (som dernæst inkluderes i din hovedfil), anvendes filudvidelsen .src, hvis din fil har indhold, der kan oversættes, da din inkluderede fil overvåges mht. ændringer som enhver almindelig .wml-fil. Hvis du bruger en anden filudvidelse, eksempelvis .inc, vil oversætterne ikke bemærke dine opdateringer og forskellige sprogudgaver kan indeholde forskelligt indhold.

Tilføjelse af en ny mappe

Bemærk: Opret ikke en mappe med navnet install. Det forvirrer programmet make og siderne i den pågældende mappe vil ikke automatisk blive opdateret.

Nedenfor er der et kommenteret eksempel på hvordan man tilføjer en ny mappe til webstedet.

   mkdir foo
   cvs add foo
   cd foo
   cp ../intro/Makefile .
   cvs add Makefile

Redigér filen Makefile i den overliggende mappe og tilføj mappen, du lige oprettede til variablen SUBS. Det vil føje mappen til opbygningen af siderne når programmet make køres.

Til sidst skal alle dine ændringer commit'es til CVS-arkivet med

  cvs commit Makefile foo