La doc
- Concepts de Base de l'outil BookStack
- La navigation dans le site
- Les Fonctions de l'éditeur
- docs exenteded Hacking BookStack
Concepts de Base de l'outil BookStack
Principes : les éléments de base
BookStack, "Pile de Livre" en Anglais, est un outil qui organise nos informations à l'image d'une bibliothèque physique.
-
On dispose d'autant "d'Étagères" que l'on veut, dans lesquelles
-
on range autant de "Livres" que l'on veut,
-
qui contiennent autant de "Pages" simples que l'on veut,
-
et on peut regrouper ces pages en "Chapitres"
La seule particularité avec une bibliothèque physique est qu'ici un livre peut être rangé, référencé dans plusieurs étagères, (ce qui n'est ni le cas de chapitres, ni le cas des pages)
C'est presque tout ce qu'il faut savoir pour commencer à utiliser l'outil.
Les boutons 
renvoient respectivement aux Catalogues des étagères et celui des livres déjà créés.
Principes : Les autorisations et le Collaboratif !
La question que l'on se pose toujours, c'est qui peut voir (lire), commenter, modifier, créer et supprimer les documents que l'on ajoute.
Sur chaque éléments (pages, chapitres, livre ou étagère) BookStack offre la possibilité de cocher les types d'autorisation spécifiques que le propriétaire (l'auteur) souhaite lui donner :
Il est donc possible de faire des éléments complètement "privés" que seul le créateur (et l'admin) peuvent voir. Cela peut-être commode pour des brouillons de travail qu'on ne veut pas encore partager en cours d'élaboration par exemple ; il est aussi possible de permettre la lecture seule mais pas la modification par les autres de ce type de document.
Comme l'organisation, la hiérarchie, des éléments est
Étagère <- Livre <- Chapitre <- Page, BookStack offre un mécanisme d'héritage (transfert) par défaut des droits du parent (contenant) aux enfants (contenus).Mais ce mécanisme d'attribution des droits d'accès n'est jamais prioritaire sur les droits définis directement sur l'élément.
Par exemple on peut créer un livre partagé avec tous, dans lequel certaines pages ou chapitres sont partagés avec tous par héritage des droits et seulement certaines pages ou chapitres sont rendus invisibles (privés) en cochant les droits plus spécifiques que l'auteur veut leur attribuer.
BookStack propose de travailler avec avec des "Rôles" qui sont attribués à chaque utilisateur.
Commençons par les Utilisateurs.
Il y a par défaut 4 type de rôles : Administrateur, Éditeur, Lecteur, Public
Les DIfférents Rôles par défaut
Administrator of the whole application
61 permissions
User can edit Books, Chapters & Pages
39 permissions
The role given to public visitors if allowed
9 permissions
User can view books & their content behind authentication
9 permissions
Le Public, c'est par défaut un visiteur qui n'a pas de compte sur le site et donc qui ne peut voir que les documents dont l'accès à été donné au public, qui n'a que le droit de 'voir' - lecteur
Par défaut, tous les utilisateurs connectés avec leur compte sont logiquement dans cette catégorie aussi.
Il est donc possible, par exemple, d'attribuer à toute une étagère le fait d'être ou ne pas être visible par le public qui consulte le site.
Les Lecteurs peuvent voir les documents et écrire des commentaires, en fonction des autorisations précisées le cas échéant sur l'élément lui-même.
Les Éditeurs, en plus de voir les documents, ont la possibilité de créer, d'éditer, des nouveaux éléments et de modifier des éléments existants, et dans une certaine mesure de les supprimer.
Il faut donc, comme toujours, être précautionneux et bien sûr de ce que l'on fait au moment de valider la suppression d'un élément !
La fonction ÉDITEUR est la fonction de base la plus intéressante pour l'objet de ce site : partager des informations, des documents, écrire en collaboration des textes, commenter le travail en cours, etc.
La fonction Administrateur est celle de faire vivre, organiser, créer les comptes, etc.
Pour le début, il y en a un, mais il serait bon qu'il y ait entre 2 et 3 personnes qui découvre en profondeur l'outil pour que Nicolas de soit pas seul dans cette fonction, pour des raisons de sécurité, pérennité et ... démocratie !
La navigation dans le site
BookStack ne propose pas comme la plupart des sites un menu/sous-menus en haut de la fenêtre de navigation .
La navigation est assurée en parcourant les Étagères, le Livres et pour cela BookStack affiche 3 types de zone d'informations :
Notez qu'en fonction de la taille de la fenêtre ou du facteur de zoom, ces zones e déplace ou sont mises en onglets :
 |
 |
Navigation :
Notez aussi l'affichage du chemin de navigation en haut du document, ou tous les éléments sont des liens actifs
Notez aussi la zone de recherche dans les mots clés et tout le texte (recherche plein-texte) !
-
Navigation entre les Pages d'un livre : Notez le bas le chaque page affichée, les boutons "Précédent/Suivant", "Ajouter un commentaire" et l'ajout puis l'affichage de commentaires
Actions et Détails de l'élément :
- Détails : Informations concernant cet élément
- Actions : Les ACTIONS autorisées sur cet élément ; au maximum :
- Nouveau/Nouvelle {page, chapitre, livre, étagère}
- Éditer : entrer dans le mode modification.
⚠️ BookStack étant un outil collaboratif, toute modification enregistrée le sera pour tout le monde.
Ceci dit, le mécanisme de gestion des Révisions intégré permet de garde l'historique des révisions et de revenir à une version précédente le cas échéant. - Copier : l'Action copier ne fonctionne pas tout à fait comme le Copier/Coller du clavier. En fait, il duplique l'élément (page, chapitre, livre ou étagère) à l'emplacement ou il se trouve. Libre à l'auteur de la copie de le renommer, déplacer, etc.
- Déplacer : La suite logique de la copie si nécessaire ou au besoin pour réorganiser.
Noter qu'on peut aussi déplacer certains éléments comme les pages et chapitre en les faisant "glisser" à leur nouvelle place à l'intérieur d'un livre. - Révisions : afficher, puis agir éventuellement sur l'historique d'édition du document
- Supprimer : Supprime l'élément sélectionné ou affiché.
⚠️ L'action de supprimer est définitive !
- Actions complémentaires :
-
- Suivre : Suivre les modifications, commentaires qui seraient fait sur cet élément. Très utile pour suivre l'avancée d'un travail. Cette fonction n'est pas disponible pour tous les éléments
- Favoris : Ajout l'élément à la liste de ses favoris pour un accès rapide et personnalisé
- Exporter : Dans sa conception Open Source, BookStack favorise l'exportation simple de tous les documents créés et donc propose des formats d'export courant comme pdf, doc, etc.
-
Les Fonctions de l'éditeur
Fonctions d'édition
Sauf à être ressorti hier de la grotte du banquier après y être entré au néolithique, tout le monde aujourd'hui connait les principes de base d'une éditeur de texte, surtout lorsqu'il est réduit à sa plus simple expression comme ici.
Un rappel tout de même : comme dans beaucoup de traitement de texte, la touche Entrée (Return) créer une nouveau paragraphe, tandis que Contrôle-Entrée (Ctrl-Return) passe à la ligne dans le même paragraphe.
(ici, un crtl-Return) ce qui est très utile pour gérer les espacements entre lignes et paragraphes, notamment.
BookStack offre peu de fonctions d'édition et c'est un de ses atouts : du coup, tous les textes rédigés ou mis en forme ici ont tous un "air de famille" quel qu'en soit le rédacteur, ce qui participe énormément à l'agrément de lecture.
Le mieux est d'aller dans une page de test du 'Bac-à-sable' et de tester toutes les options de mise en forme, les unes après les autres.
Sinon, quelques explications pour les récalcitrant de l'auto-découverte :
Mise en forme de texte
Barré | Exposant | Indice | Mise en bloc | Effacer le formatage
La mise en bloc signifie que cette partie du texte se comporte comme si elle était intégrée dans un carde invisible ; à partir de ce moment là, si on clique sur n"importe quel zone du bloc, il est selectionné dans son intégralité.
C'est utile pour les commentaires, les légendes de schéma, etc
Pour "Effacer tous les formatages de la sélection", il faut prendre soin de bien vérifier que la sélection contient les début et fin du formatage, sinon, rien ne se passera !
Mise en forme de Paragraphe
Retrait à gauche | à droite sont grisés quand le texte est au bord de la la marge gauche | droite du paragraphe
Mise en forme des objets
La gestion des liens
|
|
Quand on sélectionne un morceau de texte, en cliquant sur le symboles d'édition des liens :
|
 |
|
Editeurs
docs exenteded Hacking BookStack
doc API dans le site :
https://wiki.aubaygues.fr/api/docs
Reference Links