HTML gebruiken voor de webpagina's van Debian

Deze pagina is nog een concept.

Voorwoord

Deze pagina is gemaakt om redacteuren en vertalers te helpen bij het maken van pagina's waarin tags op een goede manier gebruikt worden. Ze bevat hints over het gebruik van tags en hoe u nieuwe pagina's kunt maken en deze gemakkelijker kunt vertalen.

Enkele algemene wenken

Voor nieuwe pagina's of vertalingen volgt hier een lijst met algemene adviezen

gebruik geen lange regels
De wml-bestanden en andere bestanden moeten regels hebben die in een normaal terminalvenster passen. Dit is gemakkelijker te bewerken in vi, beter te doorzoeken en gemakkelijker te vertalen. Dit is ook belangrijk omdat het moeilijker is om allerlei problemen op te lossen in lange regels.
houd indien mogelijk tags op afzonderlijke regels
De meeste HTML-tags kunnen op afzonderlijke regels worden gehouden. Enkele daarvan zijn: <div>, <p>, <table>, <ul>. Om het de vertalers gemakkelijker te maken, moet u alle tags die op deze manier kunnen worden gebruikt, op aparte regels houden. Anders kunnen vertalers per ongeluk tags verwijderen en vergeten ze na het vertalen terug te plaatsen.
gebruik geen spaties of regeleinden in tags die binnenin een tekstregel moeten staan
Sommige tags produceren een spatie als ze op een aparte regel staan. Een ervan is de tag <q> die voor kleine aanhalingen of citaten gebruikt wordt. U mag ze alleen scheiden op een regel in één geheel samen met inhoud. Anders zou er in de HTML-pagina achteraf een spatie kunnen staan tussen inhoud en tag. Tussen woorden binnen deze tags mag u zoveel regeleinden of spaties hebben als u wil.

Afkortingen en acroniemen

Voor afkortingen en acroniemen moet de HTML-tag <acronym> worden gebruikt. Er zijn twee redenen waarom het gebruik van de tag <abbr> niet wordt aanbevolen: ten eerste ondersteunen niet alle browsers dit en ten tweede zijn de definities over wat een acroniem en wat een afkorting is, inconsistent.

Een acroniem wordt aan de pagina toegevoegd in de volgende syntaxis: <acronym lang="taal-code" title="Volledige definitie van het acroniem">ACRONIEM</acronym>. De titel bevat de volledige woorden zoals in de spreektaal. Indien het acroniem is opgebouwd uit de beginletters van woorden, moeten die letters in de titel in hoofdletter staan. Het attribuut lang is alleen nodig als het acroniem of de afkorting uit een vreemde taal afkomstig zijn.

Er is al een reeks veelgebruikte acroniemen opgenomen in de wml-sjablonen om deze in uw pagina te gebruiken; u moet een regel toevoegen om acronyms te gebruiken in het wml-bestand. Bijvoorbeeld de wml-tag voor DD is <acronym_DD />.

Citaten en aanhalingen

Er zijn verschillende regels over wat in verschillende talen een citaat of een aanhaling is. Als u een kort citaat in de tekstregel heeft, moet u de tag <q> gebruiken. De weergave van de inhoud wordt afgehandeld door de taal CSS. <q>-tags mogen geen spatie of regeleinde hebben tussen de openende en sluitende tag en de inhoud.

Voor langere citaten wordt de tag <blockquote> gebruikt. Een <blockquote> omsluit een of meer alinea's tekst, die worden gemarkeerd met <p>. Gebruik de <blockquote>-tags niet voor het centreren van een tekstblok dat geen citaat is. Blockquotes zijn uitsluitend bedoeld voor citaten en zullen in de toekomst worden weergegeven door taalspecifieke CSS-code.

Er bestaat in HTML ook een tag <cite>. De tag <cite> wordt niet gebruikt voor de geciteerde tekst zelf. Hij wordt gebruikt voor de bron van een citaat. Dit kan de naam zijn van de persoon van wie het citaat afkomstig is en wordt in de vorm van een URL als attribuut toegevoegd aan een <blockquote>.

Namen van programma's en code

Voor namen van programma's en computercode is er een tag genaamd <code>. Browsers weten normaal gesproken hoe ze code en namen van programma's moeten weergeven, maar de weergave kan ook aangepast worden met CSS. Het is geen goed idee om in plaats daarvan <tt> te gebruiken, omdat dit niets zegt over de inhoud.

Voorbeelden van computeruitvoer

Voor computeruitvoer op het scherm is er een speciale tag genaamd <samp>. Als u een groter blok computeruitvoer heeft, moet u ook eens in het CSS-bestand kijken of er geen speciale klasse voor bestaat.

Invoer vanuit het toetsenbord

Als er voorbeelden zijn waarbij de gebruiker iets op het toetsenbord moet typen, wordt de tag <kbd> gebruikt voor de invoer van de gebruiker. Zie ook het hoofdstuk over variabelen voor de wijze waarop het invoeren van variabelen getagd wordt.

Variabelen

Soms is het nodig om de nadruk te leggen op de invoer van een variabele, zoals een speciaal IP-adres of de gebruikersnaam die moet worden gegeven in een programma-aanroep op de commandoregel. Voor een dergelijke invoer van een variabele wordt de tag <var> gebruikt.

Vooraf opgemaakte inhoud

De tag <pre> wordt alleen gebruikt voor vooraf opgemaakte tekst. Regellengte, spaties en andere zaken blijven behouden. Uiteraard kan deze tag de meeste andere HTML-tags niet bevatten.

Afbeeldingen

Als er afbeeldingen worden toegevoegd op de pagina, is het niet nodig om een ongeldige border=0 toe te voegen als attribuut. Maar indien mogelijk moeten de afbeeldingsgrootte en een alt-attribuut worden toegevoegd. Indien de grootte niet vermeld wordt, wordt deze toegevoegd door wml, maar dat vergt compilatietijd. Het attribuut alt moet iets bevatten dat gebruikers die met lynx browsen en blinden vertelt wat er in de afbeelding staat.

Links

Als u van plan bent een link te plaatsen naar een pagina uit de documentatie binnenin https://www.debian.org, gebruik dan variabelen die voor elke taal gedefinieerd zijn in het bestand .wmlrc. Bijvoorbeeld moet de URL in de tag
<a href="https://www.debian.org/devel/website/htmlediting">htmlediting</a>
worden vervangen door de variabele DEVEL zoals hierna gedemonstreerd wordt: <a href="$(DEVEL)/website/htmlediting">htmlediting</a>.