Hur man arbetar på Debians webbsidor

Allmän information

Resurskrav

Om du vill arbeta på vår webbplats bör du vara beredd på att lagra åtminstone 250 Mbyte data på din disk. Detta tal gäller den aktuella storleken för källkodsarkivet, om du (av misstag) bygger samtliga sidor behöver du det dubbla. Om du gör en delvis uthämtning kan du behöva betydligt mindre utrymme, t.ex 50 Mbyte för english/.

Delvisa uthämtningar

Många hämtar inte ut hela webwml-CVS-trädet, vilket ibland leder till saknade filer och trasiga byggningar om en viktig ny fil läggs till och man inte gör en komplett cvs update i katalogen. Kom ihåg att kontrollera om att du har samtliga krävda filer (som .wmlrc-filer) innan du klagar till oss.

Vad är raderna som börjar på ’#’ för något?

I WML är en rad som börjar på ”#” en kommentar. Dessa föreslås framför html-kommentarer eftersom de inte syns på den färdiga sidan.

Läs sidan om att använda WML för mer information om WML.

Etikett för redaktörer

Kan jag modifiera den här sidan?

Det beror på. Om du ser ett litet fel, exempelvis en felstavning, så rätta till det.

Om du tycker att någonting är fult och måste skrivas om, skriv om det på debian-www så att det kan diskuteras. Vi håller antagligen med dig.

Om du upptäcker ett problem i en mall (dvs. en fil i katalogen webwml/english/template/debian), tänk igenom ändringen innan du lägger in den, eftersom ändringar i mallar ofta gör att stora delar av webbplatsen måste byggas om.

När du lägger till nya kataloger, lägg även till Makefile

Man bör ha viss omsorg vad det gäller att lägga till nya kataloger till CVS-trädet. Om den nya katalogen listas i ../Makefile måste du lägga in en Makefile i den - i annat fall kommer make att ge ett felmeddelande.

Använd tydlig och enkel engelska

Eftersom Debians webbsidor läses av personer som inte har engelska som modersmål och översätts till andra sidor är det bäst att skriva på tydlig och enkel engelska och undvika att använda slang, obskyra uttryck och ord från gammalengelska.

Om du använder något sådant, lägg till en kommentar till filen som förklarar vad det betyder.

Se README-filerna

Några av katalogerna innehåller README-filer för att hjälpa dig förstå hur katalogen är organiserad. Dessa bör tillhandahålla den specifika information som krävs när du jobbar med det området.

Skilj ändringar i innehållet från ändringar i formateringen

Gör alltid separata ändringar och inläggningar för ändringar av innehållet och av formateringen. Om båda ändras samtidigt är det mycket svårare för översättarna att hitta ändringen. Om du kör cvs diff vid den här typen av blandade ändringar kan du själv se röran.

I allmänhet bör du undvika slumpmässiga ändringar av formateringen. Att anpassa äldre delar till XHTML/XML bör inte göras samtidigt som andra ändringar läggs in. (Nya saker kan och bör självklart göras rätt från början.)

Uppdatera även översättningar, om det går

En del ändringar är oberoende av det språk som används i WML-filen, till exempel ändringar av webbadresser eller inbäddad Perlkod. Rättning av skrivfel faller också in i samma kategori eftersom översättare vanligtvis har ignorerat dem vid översättningen. Vid sådana språkoberoende ändringar kan du utföra samma ändringar i alla översatta filer utan att faktiskt kunna de andra språken, och på ett säkert sätt öka versionen i translation-check-huvudet.

Det är inte särskilt svårt för översättarna att göra samma arbete själva, och det kan vara besvärligt för engelsktalande redaktörer att ha en komplett uthämtning att jobba i. Vi rekommenderar dock fortfarande att man gör detta för att slippa störa två dussin personer med att göra något som snabbt kan göras av en enda person.

För att göra sådana ändringar enklare att lägga in kan du även använda skriptet smart_change.pl från översta katalognivån i CVS-modulen webwml.

Använda smart_change.pl

smart_change.pl [flaggor] origfil

För närvarande tillåts endast filer i /english/ som origfil. smart_change.pl tar följande flaggor:

-s, --substitute=REGEXP
Ange ett reguljärt uttryck för Perl att applicera på källfiler (kan användas mer än en gång). Exempel: 
$> ./smart_change.pl -s "s,http://oldurl/,http://newurl/,g" english/devel/index.wml
$> cvs diff -u */devel/index.wml | less
$> cvs ci -m "1.23: Updated oldurl to current location" */devel/index.wml
Det första kommandot utför ändringen, det andra kommandot är för att kontrollera den engelska originalfilen och alla översättningar av den. Du bör göra det för att kontrollera de faktiska ändringarna innan du sänder in dem. Om allt ser ut som du tänkt dig sänder du in ändringarna med det tredje kommandot.
-l, --lang=STRÄNG
Jobba på detta språk (kan vara mer än ett). Om inget språk anges kommer alla tillgängliga språk att hanteras.
-n, --no-bump
Uppdatera inte versionerna i translation-check-huvudena. Normalt ökas versionen i varje translation-check-huvud med ett i de översatta filer som är ā jour, och lämnas kvar i de som inte är det. Om denna flagga anges kommer inte translation-check-huvuden att röras. Se hålla översättningar ā jour för en förklaring av translation-check-huvudet.
-p, --previous
Visa föregående CVS-version. Detta är huvudsakligen användbart när den engelska filen redan lagts in och du vill jämföra translation-check-huvudena mot föregående version.
-h, --help
Visa kortfattad information om hur skriptet används.
-v, --verbose
Visa pratsamma meddelanden under körning.

Länkar

Det här länken ser fel ut. Ska jag ändra den?

På grund av det sätt som webbservrarna är konfigurerade (med innehållsförhandling, eng. content negotiation) ska du inte behöva ändra någon av de interna länkarna, faktum är att vi föreslår att du inte gör det. Skriv till debian-www om du anser att en länk är felaktig innan du ändrar den.

Rätta länkar

Om du upptäcker att en länk till en extern webbsida ger en omdirigering (301, 302, en <meta>-omdirigering eller en sida som säger Denna sida har flyttat), berätta det för debian-www.

Om du hittar en trasig länk (404, 403, eller en sida som inte är vad länken säger att det skall vara), rätta den och berätta för debian-www så att översättarna är medvetna om det. Eller ännu bättre, rätta länken i alla andra översättningar, och uppdatera translation-check-huvudet om möjligt. :-)

Vad gör foo.def- och foo.data-filerna?

För att göra det enklare att hålla översättningarna uppdaterade plockar vi ut de generella delarna (data) från de textuella delarna (text) av dylika sidor. Normalt sett behöver översättarna bara kopiera och översätta textdelen av dessa sidor, de generella delarna läggs till automatiskt.

Ett exempel för att göra det lättare att förstå; det behövs flera filer för att generera sidan med försäljare i CD/vendors:

index.wml:
Texten överst på försäljarsidan finns i denna fil. En översatt kopia av denna läggs i din språkkatalog.
vendors.CD.def:
Denna fil innehåller de textdelar som behövs för varje försäljarpost. Översättningarna läggs in via <språk>/po/vendors.xy.po.
vendors.CD:
På grund av det stora antalet försäljare ligger själva försäljardata i en separat fil. Du behöver inte röra denna fil.

När en av personerna bakom cdvendors@debian.org lägger in en ny försäljare lägger de till den till debiancd.db, omvandlar den till WML-format som vendors.CD (via getvendors.pl), och låter WML och makefilerna utföra sin magi. Alla översättningarna byggs om med existerande översatt text men med ny försäljardata. (En uppdaterad översättning utan extra kostnad! :-)

Lägga till nya sidor

Att lägga till nya sidor till Debian är rätt så enkelt, allt arbete med att få sidhuvud och -fot rätt görs med wml. Allt du behöver göra är att inkludera en rad ungefär som denna överst i den nya filen: 

#use wml::debian::template title="SIDTITEL"

följd av sidkroppen. Alla sidor bör använda mallen wml::debian::template, såvida de inte använder en specialmall för just den sektionen, t.ex nyhets- eller säkerhetssidorna.

Mallarna vi har tillåter dig definiera vissa variabler som påverkar sidan som skapas, vilket bör minska nödvändigheten av att skapa olika mallar för varje situation, och gör det enklare att implementera förbättringar. De variabler som för närvarande finns tillgängliga är:

BARETITLE="true"
Tar bort ”Debian GNU/Linux --”-delen som vanligtvis läggs till i början av alla <title>-märken.
NOHEADER="true"
Tar bort det inledande sidhuvudet från sidan. Ett speciellt sidhuvud kan naturligtvis inkluderas i sidkroppen.
NOMIRRORS="true"
Tar bort spegelvallistan från sidan. Det är normalt inte rekommenderat att använda detta, förutom på en handfull sidor.
NOHOMELINK="true"
Tar bort länken tillbaka till Debians huvudsida, vilken normalt sett läggs in nederst på sidan.
NOLANGUAGES="true"
Tar bort länken till de olika språkversionerna, vilka normalt sett läggs in nederst på sidan.
GEN_TIME="true"
Sätter datumet i den resulterande filen till datumstämpeln på den genererade filen, istället för datumet på källfilen.
NOCOPYRIGHT="true"
Tar bort upphovsrättsinformationen nederst på sidan.

Notera att du kan använda vilken sträng som helst som värde för dessa variabler, true, yes, löksoppa, det spelar ingen roll.

Ett exempel på hur detta används finns på anpassningssidorna vilka har sina egna sidhuvuden. ports/arm/index.wml använder: 

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

Om du vill göra något som inte kan göras med de existerande mallarna bör du först överväga om det går att utöka en existerande. Om det inte är möjligt att göra det på ett bakåtkompatibelt sätt, försök göra en ny mall som har en existerande som delmängd, så att de sidor som använder den gamla kan konverteras till den nya vid nästa större uppdatering (vilket förhoppningsvis inte behöver ske oftare än var sjätte månad).

Om du skapar en sida som genereras av ett skript, eller som inte har så mycket brödtext bör du överväga att använda <gettext>-märken för att göra det enklare att hålla översättningarna uppdaterade.

Inkludera andra filer

Om du vill dela upp delar av din sida i en specialfil (som sedan inkluderas i din huvudfil) skall du använda filtillägget .src om filen innehåller text som skall översättas, eftersom din inkluderade fil då kommer spåras för ändringar på samma sätt som vanliga .wml-filer. Om du använder något annat filtillägg, till exempel .inc, kommer inte översättare att lägga märke till ändringar och olika språk kan komma att få olika innehåll.

Lägga till nya kataloger

Observera: Skapa inte kataloger med namnet install, då detta ställer till problem med make vilka leder till att sidorna i den katalogen inte kommer att uppdateras automatiskt.

Nedan följer ett förklarat exempel om hur nya kataloger läggs till webbplatsen: 

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

Redigera Makefile i moderkatalogen, och lägg till katalogen du just skapade i SUBS-variabeln, vilket kommer att lägga till katalogen till byggcykeln när make körs.

Slutligen lägger du in alla ändringar du just gjort i CVS-trädet genom att skriva 

  cvs commit Makefile foo