stl-statilque-litterateur/var/lib/stl/help/Comment-écrire-en-STL.md

# Écriture d'un article STL (.stl)

## Métas
Les métas utilisent le format suivant :
Séparation des champs par ' : '

```
valeur: Champ 1 : Champ 2 : Champ 3
```

### Métas Obligatoires (uniques)

Les métas obligatoires à renseigner dans votre article : 
Note: Ne pas mettre le signe `"` dans les metas

```
date: YYYY-MM-DD
title: Mon titre
author: auteur
about: Informations concernant l'article
tags: tag,tag 2,tag 3
```

### Métas Optionnelles (non uniques)
Ces métas permettent de définir vos liens ainsi que leur description
pour vos fichiers et vos textes.

```
image: NAME : (URI)FILENAME : ALT-TEXT
abbr: COURT : Long text : écriture (Champ 3 optionnel)
file: NAME : (URI)FILENAME : ALT-TEXT
link: NAME : URL : ALT-TEXT*
code: NAME : (URI)FILENAME : ALT-TEXT
brut: NAME : (URI)FILENAME
```

- NAME peut être un numéro ou un nom à reprendre dans l'article
- (URI)FILENAME est le nom du fichier
- - Ne pas commencer (URI) par `/`
- - Commençant par @ : le fichier est dans le dossier files ou images
- - - /articles/images/ # Pour le marqueur `image:`
- - - /articles/files/ # Pour tout autre marqueur
- - - Sous-dossiers possibles (ex: /articles/images/logos/, à créer vous-même)
- ALT-TEXT est utilisé pour la balise HTML `title="ALT-TEXT"`


```
# Exemple de (URI)
image: 1 : @logos/gnu.png : Logo de GNU
# L'image gnu.png se trouve dans le dossier /articles/images/logos/

file: Doc : @xmpp/1.pdf : Documentation XMPP
# le fichier 1.pdf se trouve à partir du dossier de l'article .stl dans
# le sous-dossier xmpp. Exemple :
# /articles/documentations/index.stl
# /articles/documentations/xmpp/1.pdf

``` 

## Contenu de l'article
Sont postées dans les exemples en commentaires les classes CSS utilisées
pour chaque module. "xxx_" (xxx) représente la valeur choisie lors de la
configuration du domaine (```stl domain new```)

### Séparateur de contenus (metas, article)
Dans l'article, mettre après la dernière meta, une barre d'au moins 5 `-`,
servant de repère pour détermier le début du contenu de l'article qui
sera repris dans la page HTML.


### Écrire des titres
Dans l'article placez ```#X``` ou X est compris entre 1 et 6 :

```
#2 Titre 1 #
#3 Titre 2 #
mon contenu

# Classe CSS utilisée : xxx_title xxx_title-X

# Note
Le titre <h1> est inclut dans l'entête de la page. Il est recommandé
de commencer par #2
```

Noter qu'entre les titres une balise `<div>` est créée seulement si,
il y a du contenu avant le titre suivant.

```
#2 Titre 1
#3 Titre 2
mon contenu

# Sortie HTML
<h2 class="xxx_title xxx_title-2">Titre 1</h1>
<h3 class="xxx_title xxx_title-3">Titre 2</h2>
<div class="xxx_content xxx_content-h3"
mon contenu
</div>

# Classe CSS utilisée : xxx_content xxx_content-hX
```


### Écrire des paragraphes
Dans l'article :

```
(
ceci est un paragraphe simple
)

# Classe CSS utilisée : xxx_p

( maclasse
ceci est un paragraphe personnalisé en CSS.
)

# Classe CSS utilisée : xxx_p maclasse
```


### Écrire un lien vers une URL
En méta (2 premiers champs obligatoire) :

```
link: ce super site : https//... : Ce site parle de ça
```

Dans l'article :

```
Tout est marqué sur _ce super site et c'est top !

# Classe CSS utilisée : xxx_link
```


### Liens vers un fichier interne
En méta (2 premiers champs obligatoire) : 

```
file: cette documentation : (URI)FILENAME : Ouvrez le fichier
```

Dans l'article :

```
Reportez vous à __cette documentation

# Classe CSS utilisée : xxx_link-file
```


### Afficher des Images
En métas (Les 3 champs sont obligatoires) :

```
image: 1 : STL_file_conf.png : Utiliser 'stl read conf'
image: 2 : @avatar-1.png : Image réutilisable dans d'autres articles
image: logo : @logos/STL.png : Image réutilisable dans le dossier logos
```

Dans l'article :
Chaque marqueur d'image doit se trouver sur sa propre ligne.

- Le marqueur `_image:CHAMP1` est obligatoire
- Les valeurs suivantes sont optionnelles (séparées par un espace)
- - t=(TARGET)
- - - t=+ # Ouvre l'image affichée en taille originale, ou
- - - t=http|ftp # Pointe l'image vers le site http|ftp
- - c=(CLASS)
- - - c=maclasse # Définir la classe CSS "maclasse" : xxx_image maclasse
- - - c=d ou c=r # Classe CSS right
- - - c=g ou c=l # Classe CSS : left
- - - c=c # Classe CSS : center (défaut si non définie)
- - w=(WIDTH) # Si pas d'unité, défaut = 'px'
- - - w=480 # Affiche l'image avec une largeur de 480px
- - h=(HEIGHT) # Si pas d'unité, défaut = 'px'
- - - h=30% # Affiche l'image avec une hauteur de 30%

Si WIDTH ou HEIGHT renseigné uniquement, affiche l'image avec
HEIGHT ou WIDTH adapté

#### Quelques exemples de marqueurs d'images

```
_image:1 c=echolib w=720 h=360 t=https://blog.echolib.re/
# Affiche l'image 1, avec une largeur de 720px et une hauteur de 360px
# pointant vers le site https://blog.echolib.re/
# Classe CSS utilisée : xxx_image echolib

_image:2 c=d t=+ w=50%
# Affiche l'image 2, avec une largeur de 50%, et une hauteur adaptée
# cliquable vers sa taille originale
# Classe CSS utilisée : xxx_image right

_image:logo h=10em
# Affiche l'image logo avec une hauteur de 10em et une largeur adaptée
# (non cliquble)
# Classe CSS utilisée : xxx_image center


# Pour afficher les images les unes en dessous des autres, utiliser des
# paragraphes '()' ou le signe '|' pour définir un <br />. Sans, les
# images s'affichent les unes à côté des autres

(
_image:1
|
_image:2
)
```


### Abréviations
En métas (2 premiers champs obligatoire) :

```
abbr: POUET : Descriptif : Pouets

# "POUET" doit être écrit en majuscule
# 3ème champ optionnel : écrit "Pouets" au lieu de POUET
# 3ème champ vide : écrit le 1er champ "POUET"
```

Dans l'article :

```
Des POUET très instructifs

# "POUET" doit avoir un espace, avant ou après pour être pris en compte
# "Descriptif" est utilisé dans la balise title HTML
# Classe CSS utilisée : xxx_abbr
```


### Écrire en gras
Dans l'article, entourer le ou les mots par :

```
+_Ceci est en gras_+

# Classe CSS utilisée : xxx_bold
```


### Écrire en très gras (strong)
Dans l'article, entourer le ou les mots par :

```
*_Ceci est en super gras_*

# Classe CSS utilisée : xxx_strong
```


### Écrire en italique
Dans l'article, entourer le ou les mots par :

```
\_Ceci est en italique_\

# Classe CSS utilisée : xxx_em
```


### Écrire un ou plusieurs mots en classe personnalisée (cross)
Dans l'article, entourer le ou les mots par :

```
×_Géniale, cet affichage de ces mots_×

# × : combinaisaon de touche altgr + shift + ; sur clavier FR défaut
# Classe CSS utilisée : xxx_cross
```


### Écrire en "barré"
Dans l'article, entourer le ou les mots par :

```
C'est ~_vrai_~ faux !

# Classe CSS utilisée : xxx_del
```


### Écrire du code en ligne
Dans l'article, entourer le code par :

```
Recopiez ce code : _`code python, html ou autres *...`_

# Classe CSS utilisée : xxx_icode
```


### Écrire des citations
Il y a 2 sortes de citations disponibles. Les citations simples, et les
citations avancées. Une citation doit être définie et entourée par 3
`-` au début d'une ligne. Si besoin d'utiliser une classe CSS
personnalisée, il suffit de définir le nom de cette classe après les 3
`-` (et un espace).

#### Citations simples
Dans l'article :

```
---
Ceci est une citation simple sans classe CSS personnalisée
---

# Classe CSS utilisée : xxx_quote (sur <blockquote>)

--- maclasse
_lang: fr
Ceci est une citation définie en français simple avec la classe CSS maclasse
---

# Classe CSS utilisée : xxx_quote maclasse (sur <blockquote>)
```

#### Citations avancées
Il est possible de définir plusieurs références à la citation. Définir
son auteur permet d'avoir un rendu HTML utilisant les balises
`<figure>` et `<figcaption>`

Dans l'article :
Même si cette citation est réelle, noter que les références "_year" et
"_book" sont fictives, et ne sont là qu'à titres d'exemples.

```
--- Stallman
_cite : Richard Matthew Stallman
_link : https://stallman.org/
_lang : en
_year : 1995
_book : Le mouvement du logiciel libre
(
In the free/libre software movement, we develop software that respects
users' freedom, so we and you can escape from software that doesn't. I
could have made money this way, and perhaps amused myself writing code.
But I knew that at the end of my career, I would look back on years of
building walls to divide people, and feel I had spent my life making the
world a worse place
)
---

# Classe CSS utilisée : xxx_quote Stallman (sur <figure>)
```

### Écrire des listes
Pour définir une liste, elle doit être entourée de ```<<``` et ```>>```
Il est possible de personnaliser la classe de sa liste ```<< maclasse```

Il y a 2 marqueurs pour les listes.
- ```=``` pour les listes simples
- ```+``` pour les listes ordonnées

Les listes sont infinies, et dépendent du nombre de marqueurs par itmm.
Il est possible de mixer les marqueurs, sous condition de respecter la
logique du nombre de marqueurs.

Dans l'article :

```
# Liste avec classe personnalisée "couverture"

<< couverture
= Livre 1
+ Chapitre 1
+ Chaptire 2
++ Résumé du Ch 2
++ Citation du Ch 2
= Livre 2
+ Chapitre 1
>>

# Classe CSS utilisée : xxx_list xxx_list-ul couverture couverture-ul
# Remplace ul par ol si la liste commence par "+"
# Chaque item <li> utilise la classe : xxx_li xxx_li-X
# où X est le nombre de marquurs

# La sortie de cette liste en HTML, avec le préfix CSS choisi "a-lec" :

<ul class="a-lec_list a-lec_list-ul couverture couverture-ul">
  <li class="a-lec_li a-lec_li-1">Livre 1</li>
<ol>
  <li class="a-lec_li a-lec_li-1">Chapitre 1</li>
  <li class="a-lec_li a-lec_li-1">Chaptire 2</li>
  <ol>
    <li class="a-lec_li a-lec_li-2">Résumé du Ch 2</li>
    <li class="a-lec_li a-lec_li-2">Citation du Ch 2</li>
  </ol>
</ol>
  <li class="a-lec_li a-lec_li-1">Livre 2</li>
<ol>
  <li class="a-lec_li a-lec_li-1">Chapitre 1</li>
</ol>
</ul>

#--------------------------------
# ! Ce qu'il ne faut pas faire :
# Changer de marqueur, en ajoutant 1
<<
= livre 1
++ Chaptire 1
>>
```


### Affiche un code source depuis un fichier
En métas (2 premiers champs obligatoires) :

```
code: python : (URI)FILENAME : alt-text 
```

Dans l'article:
Chaque marqueur de block code doit se trouver sur sa propre ligne.

```
_code:python

# Classes CSS et balises HTML utilisées :
# <pre> : xxx_code-block code-block-python
# <span> (line number) : xxx_code-line
# <span> (content) : xxx_code-content
# </pre>

# <div> : xxx_code-div
# <a> : xxx_code-link
# 
```


### Retour à la ligne simplifié
Vous pouvez écrire en HTML ```<br />``` mais, afin de faciliter la
lecture dans l'article original, placez au tout début de la ligne ```|```

Dans l'article :

```
(
Ceci est un long paragraphe
|
Ici, une nouvelle ligne dans ce paragraphee.
)
```