Detta är ett försök att beskriva syntax och struktur på Inbyggd Frihets sida. Ett fåfängt försök i en komplex miljö. När du bidrar med innehåll, är bidraget det viktiga. Kolla annars hur vi gjort i övrigt, och ring om du är osäker.

Wikin genereras med ikiwiki. Syntaxen är markdown. Vi hänvisar till John Grubers Daring Fireball, Ikiwikis formateringsguide och John MacFarlanes Pandoc utökningar för detaljer i syntaxen.

Varje wiki ska ha en sandlåda, vilket också denna har.

I övrigt följer vi följande principer

Terminologi

  • Begreppen artikel, dokument och fil används synonym åsyftande en sida på wikin.

  • Med indexsida/indexdokument åsyftas huvuddokumentet i en subhierarki av sidor.

Språk

Wikin är i allmänhet svenskspråkig, men också engelska förekommer. Eftersträva svenska. Viktigare dock, är att vara entydig och konsekvent inom en artikel. Vissa artiklar/dokumnet förekommer i flera språk. Markera detta per flera versioner, t.ex. styleguide-sv.mdwn och styleguide-en.mdwn.

Döp dokument – filens namn

Dokumentets filnamnet reglerar URL:en (Universal Resource Location), men titeln bestäms enligt nedan. Välj något passande. Detta dokumentets filnamn är t.ex. “styleguide” (där föredrogs engelska) trotas att titeln är “Wikins stilguide”

Rubrikhierarkier i dokumenten

Avsnitt avdelas med avsnittsrubriker. Dessa markeras med “#”. Använd i första hand förstahierarkin. Varje avsnitt ska också ha minst ett stycke. Exempel:

Första stycke i ett dokument


# Först nivå underrubrik markerar avsnitt

Första stycke i detta avsnitt beskriver avnittets syfte och
innehåll. Här presenteras typiskt underliggande avsnittshierarki och
dess betydelse.

## Andra-nivå avsnittrubrik

Dessa stycken förtydligar och fördjupar överhierarkiska avsnitt.

## Ännu en andranivårubrik

Med stycke.


# Ytterligare förstanivå avsnittsrubriker

Som sagt varje avsnitt ska också ha *minst* ett stycke

Titel i dokument

Välj en titel som passar. Inför den per Pandocs initiativ “%”-syntaxen:

% Dokumentets titel
% Författare
% Datum

Första stycke


# Först hierarki underrubrik markerar avsnitt

Första stycke i detta avsnitt ...

Använd alternativt YAML-versionen:

---
title: Dokumentets titel
author: Författare
date: datum
subtitle: Undertitel, vilket bl.a. möjliggörs av YAML-konstruktionen
...

Första stycke


# Först hierarki underrubrik markerar avsnitt

Första stycke i detta avsnitt ...

Dokumenthierarkier

Ikiwiki har stöd för hierarkier. Det är användbar struktur i många sammanhang. Innbyggd frihets wiki är en strukturerad samling information som ofta snarare återspeglar en traditionell hemmsida än en encyklopedi. Där lämpar sig ofta att använda hierarkier. Dock finns risk för överanvändning av hierarkisk struktur framför andra strukturtekniker, som t.ex. taggar, kategorier, och index.

Konstruera hierarki såhär:

wiki/
  index.mdwn
  guider.mdn
  guider/
    grub.mdwn
    libreboot.mdwn
    etc.

Från hemsidan (index.mdwn) hänvisas till indexsidan “Guider” (guider.mdwn) som i sin tur har undersidor, “Guide för GRUB” (grub.mdwn), “Liebreboot” (liebreboot.mdwn), etc. Dokumentets filnamnet reglerar URL:en men titeln bestäms enligt ovan.

Läs också mer om länkningsregler, Ikiwiki.

Undvik avsnitt i indexsidor. En indexsida, t.ex. guider.mdwn, är en sida med undersidor. Det faktum att du vill ha riktiga undersidor innebär ett visst behov av hierarki. Låt då den strukturen stå för sig själv och använd dessa undersidors titel som nästa undernivå. Kolla hur vi gjort i övrigt om du är osäker.

Vertikalt mellanrum

Vertikalt mellanrum, det tycker vi om. Goda exempel:

### KGPE-D16

**General.** (Libreboot-20160907)

  * RAM is sensitive, less is more likely to
    work. See
    [coreboot wiki](https://www.coreboot.org/Board:asus/kgpe-d16) for
    working configurations

  * Internal GPU works (for text mode only), note the hardware switch
    (see motherboard manual)

Moreover

  * North bridge (?) gets hot

     * A system with 2x 6276 CPUs draws between 200 and 400 watt
     * There are two ethernet ports and one IPMI (not used)
     * RAM order is important, see motherboard manual

  * Hardware jumpers for GPU, ethernet etc.

Radbrytning och mellanslag

Det är god sed att, om möjligt, ställ in din texteditor på att bryta vid 80 tecken e.dy. Då blir det lättare att tillgodogöra sig innehållet i text-form, jämfört med att raderna sticker iväg över hela skärmen.

Granska så att du inte stoppar in mellanslag där det inte ska vara (t.ex. i slutet på raden där det ofta smyger sig in). Sist tecken i varje dokument ska vara nyradstecken.

Emacsanvändare kan använda M-x whitespace-cleanup.