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 mb til data på din harddisk. Dette svarer til den nuværende størrelse på arkivet. 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 mb for mappen /english .

Delvis 'checkout'

Mange behøver ikke hele CVS-træet webwml, der nogle gange fører til 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 at du har alle krævede filer (såsom .wmlrc-filer) før du klager til os.

Hvad er det for nogle linjer som begynder med '#'?

I WML begynder kommentarlinjer med '#'. Disse foretrækkes fremfor almindelige HTML-kommentarer da de ikke viser sig i den endelige side.

Læs venligst om at bruge 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 — eller vil make returnere med en fejlmeddelelse.

Brug letforståeligt engelsk

Da Debians websider læses af folk som 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, sjældne ideomatiske udtryk og gammeldags engelske ord.

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

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 på det pågældende område.

Adskil indholdsændringer fra formateringsændringer

Foretag altid separate rettelser eller commits af 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 sider 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, hvis 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 specielt krævende for oversætterne, selv at gøre arbejdet, og det kan være upraktisk for engelsk-talende 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 par dusin mennesker 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 øverst 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 etsprog, 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 paremetret 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 resulterer i en omstilling (redirection - 301, 302, en <meta>-omstilling, 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, som linket siger), så ret linket og fortæl om det på debian-www så oversætterne bliver gjort opmærksomme på. 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! :-)

Nye forhandlere tilføjes af en af webmasterne ved at ændre i vendors.CD. Næste gang websiderne opdateres vil alle oversættelserne automatisk blive genopbygget. (En ajourført opdatering helt gratis! :-)

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 speciel skabelon lavet til denne sektion, for eksempel nyhederne eller sikkerhedsbulletinerne.

Vores skabelonerne giver dig mulighed for at definere bestemte variable som vil påvirke de oprettede sider. Dette 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 GNU/Linux --"-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"
Sætter datoen på resultatfilerne til de genererede filers tidsstempling i stedet for kilde-filens 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 som har deres egne sidehoveder. ports/arm/index.wml bruger:

#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 som 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 script 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 (der 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. Dette forvirrer programmet make og siderne i den 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. Dette 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