wiki/Syntaxe.md

200 lines
7.9 KiB
Markdown
Raw Normal View History

2018-02-14 13:45:06 +01:00
---
2016-09-18 00:15:33 +02:00
categories: network web
toc: no
title: Conventions pour le wiki Evolix
...
# Conventions de syntaxe
2016-09-17 23:33:48 +02:00
<http://daringfireball.net/projects/markdown/basics>
## Metadata
---
categories: network web
toc: no
title: Haskell and Category Theory
...
## Syntaxe
2016-09-18 00:16:11 +02:00
Voir [Help#markdown]()
2016-09-18 00:10:27 +02:00
2016-09-17 23:33:48 +02:00
Commandes Shell (sans output) :
~~~
2016-09-17 23:33:48 +02:00
$ apt-cache search foo
# apt install foo
~~~
Commandes Shell (avec output) :
~~~
$ dmesg
2016-09-19 19:35:48 +02:00
[8044916.823878] [IPTABLES DROP] : IN=eth0 OUT= MAC=00:00:00:28:71:00:00:54:00:8f:01:00:00:00 SRC=192.0.2.1 [...]
2016-09-17 23:33:48 +02:00
~~~
Fichiers avec coloration syntaxique si disponible (voir ci-dessous) :
~~~{.apache}
ServerName www.example.com
~~~~
~~~{.bash}
#!/bin/bash
echo toto
~~~~
2016-09-17 23:33:48 +02:00
Liens externes :
<http://www.example.com/>
[Lien vers Example](http://www.example.com/)
Liens internes :
[HowtoFoo]()
[HowtoFoo#name]()
[#name]()
2016-09-26 13:38:38 +02:00
### Syntaxes Markdown
*italique* **gras** ~~barré~~ H~2~O m^2^
Pour forcer un saut de ligne :
terminer sa ligne avec deux espaces !
2016-11-08 21:41:24 +01:00
Pour afficher le "symbole" `/!\`, il est important d'échaper le dernier caractère : `/!\\`.
2016-09-19 19:35:48 +02:00
## Conventions
2017-11-29 19:45:48 +01:00
### Conventions de syntaxe
2016-09-19 19:35:48 +02:00
Une commande lancée en root sera précédée de **#** ; en utilisateur elle sera précédée de **$**.
Dans la mesure du possible, le maximum de commande devra être lancée en tant qu'utilisateur.
~~~
2016-09-19 19:35:48 +02:00
$ apt-cache search foo
# apt install foo
~~~
2016-11-08 21:41:24 +01:00
Si on montre plusieurs commandes dans un seul bloc, et qu'on veut également montrer leur sortie, il convient de sauter une ligne entre chaque commande et la fin de la sortie de la précédente.
2016-09-19 19:35:48 +02:00
On évitera d'avoir des lignes trop longues dans les commandes Shell ou fichiers sur le wiki, car cela devient illisible en HTML.
On mettra ainsi les commandes Shell sur plusieurs lignes si besoin, on utilisera *[...]* si nécessaire, etc.
2016-09-26 14:42:40 +02:00
Si l'on doit afficher une commande courte dans le paragraphe du texte, par exemple `/etc/init.d/foo restart`, on utilise les backticks « \`/etc/init.d/foo restart\` ». On peut utiliser la même chose pour les noms de fichier, tel `foo.bar`.
2016-09-26 14:41:12 +02:00
2016-09-19 19:35:48 +02:00
Si l'on doit utiliser un utilisateur quelconque, on utilisera le login **jdoe** (pour John Doe).
Si l'on doit mentionner un mot de passe, on choisira **PASSWORD** (en majuscule).
2016-09-20 21:49:23 +02:00
Si l'on doit mentionner un fichier quelconque, on choisira **FICHIER** (en majuscule).
2016-11-30 17:39:36 +01:00
Si l'on doit utiliser un terme quelconque, on privilégiera **foo** et **bar** (puis baz, qux, quux, corge, grault, garply, waldo, fred, plugh, xyzzy, thud). Ainsi, pour un chemin quelconque, on utilisera par exemple `cp /foo/FICHIER /bar/`.
2016-09-20 21:49:23 +02:00
2019-06-26 13:59:44 +02:00
Si l'on utilise des adresses IP, on utilisera des IPv4 en **192.0.2.0/24**, **198.51.100.0/24**, ou **203.0.113.0/24** [RFC5737](https://tools.ietf.org/html/rfc5737#section-3) et des IPv6 en **2001:db8::/32** [RFC3849](https://tools.ietf.org/html/rfc3849).
2016-09-19 19:35:48 +02:00
Les adresses IPv6 et les adresses MAC auront leurs caractères alphabétiques en minuscule.
2018-02-14 13:44:33 +01:00
Si l'on utilise un système autonome, on utilisera un AS entre **64496 et 64511** ou entre **65536 et 65551** [RFC5398](https://tools.ietf.org/html/rfc5398).
2016-09-19 19:35:48 +02:00
Si l'on utilise des noms de domaine, on utilisera **example.com** [RFC2606](https://tools.ietf.org/html/rfc2606) notamment pour les emails, URLs ou serveurs à atteindre.
Pour relancer un service : `/etc/init.d/foo restart` OU `systemctl restart foo`. (??)
2016-09-21 17:36:15 +02:00
Pour installer un paquet sous Debian, on utilise la commande `apt``apt install foo`.
2016-09-26 14:31:12 +02:00
Par défaut on considère que l'on écrit de la documentation pour la version *stable* d'OpenBSD ou pour *Debian 9*. Des remarques **obligatoires** doivent être faites pour *Debian 8*. Des remarques éventuelles peuvent être faites pour les version précédentes (Debian 7, etc). Ces remarques devraient être mises sous forme de "notes" du type :
> *Note* : Pour Debian 7 et 8, on peut faire :
>
> ~~~
2017-07-23 00:17:29 +02:00
> # aptitude install foo
> ~~~
2017-11-29 19:45:48 +01:00
### Conventions de forme
* Il doit y avoir des metadatas avec au minimum "categories" et "title"
* La 2ème ligne de la documentation doit être un choix réfléchi de catégories en fonction des catégories déjà existantes
* Si une documentation officielle existe, elle doit être notée tout en haut sous la forme : Documentation : <lien>
* Si un rôle Ansible existe, il doit être noté avec le lien vers la branche stable sur la forge sous la forme : Rôle Ansible : <lien>
* La description doit être succinte (entre 3 et 10 lignes) ET subjective d'un point de vue Evolix
2017-11-29 19:47:23 +01:00
* Un lien vers le site officiel doit être positionné sur la 1ère occurence du nom de la techno dans la description.
2017-11-29 20:32:29 +01:00
* Une section installation doit être présente. On considère que l'on utilise la dernière version de Debian et/ou d'OpenBSD par défaut, si besoin on précise les exceptions pour des releases précédentes comme précisé plus haut
2017-11-29 19:45:48 +01:00
* Dans la section installation, on montrer la commande apt d'installation, mais un moyen d'obtenir la version installée en temps qu'utilisateur non-root et l'état de l'éventuel démon avec sysctemctl status SAUF la ligne "active"
2017-11-29 19:53:41 +01:00
* En général, il doit y avoir au moins les titres : Installation / Configuration / Administration / Optimisation / Plomberie / Monitoring (avec sous-titres Munin et Nagios) / FAQ
* L'organisation des titres/sous-titres doit être cohérente quand on regarde la table des titres
2017-11-29 19:45:48 +01:00
* Les conventions de syntaxe doivent être appliquées partout (voir ci-dessous) notamment pour les adresses IP, les "Note :", les fichiers sous la forme `/etc/foo.conf` etc.
* Les exemples de code ou contenu de fichiers doivent utiliser la syntaxe avec trois tildes
2017-11-29 19:53:41 +01:00
* Si l'on mentionne des autres documentations, mettre des liens internes
* Objectif 0 faute d'orthographe / de grammaire
2017-11-29 19:53:41 +01:00
* Tout ce qu'on a mis en production sur des serveurs doit être mentionné
* Quand on mentionne des commandes avec des arguments, il faut mettre les versions longues (exemple: `--dry-run` au lieu de `-d` si possible)
2017-11-29 19:45:48 +01:00
* Si la doc est longue, on hésitera pas à avoir un titre "Configuration de base" et "Configuration avancée", ou alors un sous-titre "Utilisation de base" avec les commandes de base si l'on doit lire la doc en 1 minute
2017-11-29 19:47:23 +01:00
* Si la doc est très longue, elle peut être découpée en sous-pages à l'exemple du [HowtoMySQL]()
2017-11-29 19:45:48 +01:00
À titre d'exemple, on pourra prendre le [HowtoApache]()
2017-11-29 20:30:56 +01:00
Pour s'aider, on peut partir d'un template :
2017-11-30 00:13:38 +01:00
```
2017-11-29 20:30:56 +01:00
---
categories: voir https://wiki.evolix.org/_categories
title: Howto Foo
...
2017-11-30 00:13:38 +01:00
* Documentation : <https://foo.io/doc>
2017-11-29 20:30:56 +01:00
* Rôle Ansible : <https://forge.evolix.org/projects/ansible-roles/repository/show/foo>
2017-11-30 00:13:38 +01:00
[Foo](https://foo.io/) est un logiciel qui...
2017-11-29 20:30:56 +01:00
2017-11-30 00:13:38 +01:00
## Installation
2017-11-29 20:30:56 +01:00
2017-11-30 00:13:38 +01:00
~~~
2017-11-29 20:30:56 +01:00
# apt install foo
2017-11-30 00:13:38 +01:00
$ /usr/sbin/foo -v
2017-11-29 20:30:56 +01:00
# systemctl status foo
2017-11-30 00:13:38 +01:00
~~~
2017-11-29 20:30:56 +01:00
2017-11-30 00:13:38 +01:00
## Configuration
2017-11-29 20:30:56 +01:00
2017-11-30 00:13:38 +01:00
## Administration
2017-11-29 20:30:56 +01:00
2017-11-30 00:13:38 +01:00
## Optimisation
## Monitoring
### Nagios
### Munin
## Plomberie
## FAQ
```
2017-11-29 20:30:56 +01:00
2016-09-17 23:33:48 +02:00
## Coloration syntaxique
~~~
$ ./.cabal/bin/pandoc -v
pandoc 1.17.2
Compiled with texmath 0.8.6.5, highlighting-kate 0.6.2.1.
Syntax highlighting is supported for the following languages:
abc, actionscript, ada, agda, apache, asn1, asp, awk, bash, bibtex, boo, c,
changelog, clojure, cmake, coffee, coldfusion, commonlisp, cpp, cs, css,
curry, d, diff, djangotemplate, dockerfile, dot, doxygen, doxygenlua, dtd,
eiffel, elixir, email, erlang, fasm, fortran, fsharp, gcc, glsl,
gnuassembler, go, hamlet, haskell, haxe, html, idris, ini, isocpp, java,
javadoc, javascript, json, jsp, julia, kotlin, latex, lex, lilypond,
literatecurry, literatehaskell, llvm, lua, m4, makefile, mandoc, markdown,
mathematica, matlab, maxima, mediawiki, metafont, mips, modelines, modula2,
modula3, monobasic, nasm, noweb, objectivec, objectivecpp, ocaml, octave,
opencl, pascal, perl, php, pike, postscript, prolog, pure, python, r,
relaxng, relaxngcompact, rest, rhtml, roff, ruby, rust, scala, scheme, sci,
sed, sgml, sql, sqlmysql, sqlpostgresql, tcl, tcsh, texinfo, verilog, vhdl,
xml, xorg, xslt, xul, yacc, yaml, zsh
2016-11-08 21:41:24 +01:00
~~~