% Wikins stilguide

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](https://sv.wikipedia.org/wiki/Markdown). Vi hänvisar
till John Grubers
[Daring Fireball](https://daringfireball.net/projects/markdown),
[Ikiwikis formateringsguide](http://ikiwiki.info/ikiwiki/formatting)
och John MacFarlanes [Pandoc utökningar](http://pandoc.org/README.html)
för detaljer i syntaxen.

Varje wiki ska ha en [sandlåda](sandbox), vilket också denna har.

I övrigt följer vi följande principer

[[!toc]]


# 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](https://ikiwiki.info/ikiwiki/subpage/). 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](https://ikiwiki.info/ikiwiki/subpage/linkingrules/),
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`.