Skip to content

Tips voor opmaak

Jump to bottom
Redmer Kronemeijer edited this page Jun 20, 2022 · 5 revisions

Met ReSpec kun je je specificaties schrijven in HTML of met Markdown. Markdown heeft enkele primitieven die de <haken> opmaak van HTML wat eenvoudiger maakt, maar uiteindelijk wordt Markdown ook in HTML gecompileerd. Je kunt ook HTML-codes in Markdown gebruiken, als er bijvoorbeeld <dfn> definities opgemaakt moeten worden: dat kent Markdown niet.

Dit is een samenvatting van wat beschreven staat op respec.org/docs/.

Structurele/semantische opmaak

Kopjes en paragrafen

Paragrafen maak je door een lege witregel tussen tekst te zetten. Omgekeerd betekent dat je een enter achter elke (bij)zin kunt zetten, zodat de leesbaarheid in Git beter wordt, zonder dat dit uitmaakt voor de weergegeven tekst. Kopjes maak je door voor een regel een # te zetten. Het volgende niveau kopje maak je met een ##, etc.

## Vlees noch vis

Dit is een paragraaf.
Hier gaan we het niet hebben over vlees.

Dit is ook een paragraaf.
Hier gaan we het niet hebben over vis.

Lijsten

Er zijn drie soorten lijsten in HTML: ol (geordend), ul (ongeordend), dl (definitielijst). In de eerste twee kun je ook sublijsten aangeven, door de sublijst in te laten springen met drie spaties.

1. De geordende lijst schrijf je
1. met punten achter een cijfer.
1. Het daadwerkelijke getal maakt
1. niet uit.
- Een ongeorderdende lijst
- heeft streepjes of sterretjes
- als herkenningsteken.
<dl>
  <dt>Term in een definitielijst</dt>
  <dd>Dit is de betekenis van de term.</dd>
  <dt>Volgende term</dt>
  <dd>Diens betekenis</dd>
  <!-- De laaste dd (definitie) moet je afsluiten met </dd> -->
</dl>

Als de geordende lijst een algoritme beschrijft, gebruik dan <ol class="algorithm">. Als de <dl> definiërend is, gebruik dan <dl class="def">.

Tabellen

| Sleutelwoord   | Betekenis      |
| -------------- | -------------- |
| Rij 1          | Rij 1, kolom 2 |
| Rij 2          | Rij 2, kolom 2 |
| { .data .def } |

In de laatste rij, eerste kolom is het mogelijk om opmaakcommando's (CSS klasses) mee te geven tussen { }.

Sleutelwoord Betekenis
.data Voor tabellen die data bevatten.
.def Voor tabellen die zaken definiëren.
.index Voor tabellen die eigenschappen, e.d. opsommen.

Code

Sleutelwoorden, zoals klassenamen of identifiers, kun je met ` aangeven. Wanneer de code meer dan 1 regel lang is, gebruik je codefences, met drie backticks:

```py
def hello(name: str): return f"hello {name}"
```

Ondersteunde taalidentifier (py in bovenstaande voorbeeld) zijn:

  • js
  • json
  • ttl
  • sparql
  • css
  • html

Citaten, notities, voorbeelden, opmerkingen

Citaten maak je met > voorafgaand aan de regel. In een citaat kun je vervolgens weer alle opmaak gebruiken. De markdownopmaak van een citaat kun je (bij het CROW-profiel) ook gebruiken voor een voorbeeld, notitie of opmerking. Zie de tabel hieronder:

TYPE Betekenis
NOTE Notitie
EXAMPLE Voorbeeld van hoe het moet
ILLEGAL Voorbeeld van hoe het niet moet
ADVISEMENT Advies of opmerking
ISSUE Melding in de GitHub issue tracker, nummer met #__.
EDNOTE Editorial note = redactionele opmerking.
DEF Bedoeld voor een definitie, vereist nog <dfn> etc. 
> TYPE #nummer "titel"

Links en verwijzingen

Linkjes naar andere webpagina's maak je zo: [beschrijvende tekst](doel). De beschrijvende tekst moet niet "klik hier" of dergelijk zijn.

Verwijzingen naar bronnen in de bronnenlijst, naar standaarden, etc. geschiedt door middel van [[SPEC-ID]], waarbij SPEC-ID de code is van een refentie die je op https://www.specref.org/ vindt of aan ReSpec's metadata.json toevoegt:

  localBiblio: {
    WEREWOLF: {
      title: "Tremble Puny Villagers",
      href: "https://w3.org/werewolf",
      status: "RSCND",
      publisher: "W3C",
    },
  }

Licentie

Er zijn een aantal ingebouwde standaardlicenties, geschikt voor open documentatie. Als je onderdelen van Wikipedia herbruikt, is dat onder CC BY-SA. Als je het niet weet, maar het open wil laten zijn: CC BY. Als je het echt niet weet, laat je adviseren.

CC0 plaatst de documentatie in het publieke domein.

ID URL
"cc-by" https://creativecommons.org/licenses/by/4.0/
"cc-by-sa" https://creativecommons.org/licenses/by-sa/4.0/
"cc0" https://creativecommons.org/publicdomain/zero/1.0/

Om een aangepaste licentie te gebruiken, voeg dan in config.js het volgende toe. Open licenties worden aanbevolen.

  license: {
    name: "Name of license, visible on hover",
    name_nl: "Naam van licentie, uitleg bij `short` titel",
    url: "", // link naar licentie, laat `""` bij licenties zonder webadres
    short: "copyright"
  },

Presentationele opmaak

Markdown Resultaat
**vetgedrukt** vetgedrukt
_cursief_ cursief
Clone this wiki locally