[ En Français ] [ In English? ] [ En Espanol? ] [ Deutsch ]

---

Cette page est pour la doc' utilisateur : comment on va utiliser le wiki pour en extraire le contenu, liste des fonctionnalités nécessaires, architecture logicielle, un peu de reprise de ce qu'il y a déjà sur OrganisationSite?, ce qu'on a regardé de similaire...
La page concernant les développements en tant que tel est DevFaqEagleFr (pour internationaliser aussi, on sait jamais s'il y a des contributeurs intéressés, commencer par DevFaqEagleUS...)

But

Permettre un travail collaboratif en ligne (style wiki) de production de documentations (docbook, le standard).

DocBook: devient la référence en matière de documentation technique dans le monde des logiciels libres entre autre (GNOME, KDE, LDP, ...). A partir de ce format, on peut envisager de produire toute sorte d'autres formats facilement.

Wiki: famille d'outils permettant un travail collaboratif en ligne. Chaque utilisateur/lecteur peut devenir contributeur/rédacteur au bénéfice de tous.

Contraintes

L'outil doit être facilement hébergeable. Pour ce faire, le couple PHP/MySQL est retenu vu son utilisation dans la plupart des offres d'hébergement ainsi que la popularité du langage.

• Langage de programmation: PHP
• Backend SQL: MySQL

Proposition

• Wikini:
  • Plus:
    • Facilement déployable
    • Syntaxe simple
    • Déjà utilisé pour eagle-usb
  • Moins:
    • Syntaxe inadapté pour la richesse du docbook
    • Support d'autres syntaxes non prévu
  • Avis:
    • FrankJ: Cette solution n'est pas satisfaisante au vu des "Moins", on est obligé de bricoler des règles pour faire les FAQs et on serait obligé d'en inventer d'autres pour simuler un prompt, screen etc... sous docbook. Ca devient pénible, frustrant et la solution actuelle tient plus du bricolage que d'une réelle solution.

• WikiText:
  • Plus:
    • Syntaxe étudié spécifiquement pour produire du docbook (WikiText-HOWTO.wt)
    • Mélange de raccourci facile style syntaxe wiki + balises docbook pour des utilisations bien spécifiques (<screen><prompt>...)
    • Syntaxe utilisé par le project de documentation linux LDP.
  • Moins:
    • aucun parseur en php connu (uniquement un programme de conversion wt=>db en perl), une implémentation s'impose donc
    • ce n'est qu'une syntaxe, il faut un environnement wiki qui accepte plusieurs langages grace à des modules/plugins
    • la connaissance de certaines balises docbook s'impose pour produire du docbook "correcte"
  • Avis:
    • FrankJ: Je veux bien essayer de porter le script de conversion en php mais il faut trouver un wiki comparable à wikini mais qui accepte en extension différents langage/parseur. Une telle solution serait une très bonne contribution aux logiciels libres car la documentation pose toujours un problème à beaucoup de projets.
    • BenoitAudouard : j'ai signalé sur wikini.net l'exportation DocBook que tu as réalisée. Ils avaient de bonnes intentions de traiter les moins de wikini identifiés ici (autres syntaxes notamment si j'ai bien compris), il est vrai qu'aujourd'hui on est obligé de prendre un sous-ensemble de la syntaxe de wikini organisé spécifiquement pour le DocBook (manuellement, pas de vérification, pas de "template" de saisie), pas de tableaux, pas d'internationalisation, ... (même si ça n'en est pas très loin). A voir ce qu'ils en pensent. Mon souci est vraiment de trouver ce qui puisse convenir sans un trop grand effort de développement / test / intégration / recette / mise en production. ça vaut tout de même le coup de voir les alternatives.

• Autre: http://phpwiki.sourceforge.net/phpwiki/MultiLingualWiki
  • Plus: Vérifier qu'il gère bien l'internationalisation
  • Moins: j'ai l'impression qu'il est "abandonné"...
  • Avis:

• Autre: http://baud123.free.fr/wacko => lien vers wacko qui est en Russe... fork de wakkawikki aussi (comme wikini) hachement plus avancé sur la gestion de l'international
  • Plus: Vérifier compatibilité avec wikini (si oui je copie/colle tout ou je récupère un script de migration...)
  • Moins: le site où tout se passe est en Russe !
  • Avis:
    • FrankJ: Faire des proposition de solutions, d'outils qui pourraient être compatibles avec le but.

• DocBook Wiki : http://doc-book.sf.net
  • Plus:
    • permet d'éditer en ligne une documentation DocBook complète.
    • ne nécessite pas de connaître la syntaxe DocBook.
    • toutes les modifications sont sauvegardées au format DocBook : on peut réutiliser directement les documents et DocBook demeure la source unique de la documentation.
    • permet de visualiser directement le résultat en HTML, texte brut, PDF, RTF, DocBook, LaTex, PostScript, etc.
  • Moins:
    • son développement n'en est qu'à la phase béta, il ne semble pas encore utilisé par ailleurs.
    • requiert xmlto et swish-e qui ne sont généralement pas présents sur la plupart des hébérgements. Enquête à mener pour en savoir plus ?
  • Avis:
    • À moins de réunir les conditions d'hébergement requises, cette solution n'est pas envisageable.

• Autres demandes similaires
  • https://linuxfr.org/forums/41/19896.html

---

La solution mise en place à l'heure actuelle

C'est une solution "rapide" qui prend en compte les contraintes d'hébergement facile (PHP pour le langage et MySql pour le backend SQL) ainsi que l'utilisation de wikini comme moyen de travail collaboratif style wiki.

Paramètres

- Liste des FAQ à prendre en compte

• préférer une page "sommaire" en wiki à l'édition d'un fichier xml : évol' future... pour l'instant le xml est suffisamment lisible.
• la liste correspond aux Nom Wikini des pages

- Langue : uniquement utilisé pour les sections supplémentaires
- Type de document en sortie : DocBook actuellement, texte, html, PDF pour après

Formatage

- ajout de sections standardisées : license (d'après la langue sélectionnée)
- ajout d'une table des matières : titre section / questions de la section
- le DocBook pour WikiText sépare en sections que l'on peut assimiler à chacune de nos pages (cf. visualisation en html)
- chaque formatage wiki est remplacé par son équivalent DocBook (c'est possible ? oui c'est dans wakka2callback)

• bold = ** = '<emphasis role="bold">' : '</emphasis>'
• italic = // = '<emphasis role="italic">' : '</emphasis>'
• underline = __ = '<emphasis role="underline">' : '</emphasis>'
• "code" or "commande" or "path" = monospace = ## = '<emphasis role="highlight">' : '</emphasis>'
• escaped text ("as is" text or html...) = double-quoted = well, text as is ?
• urls = "<ulink url=\"$url\" />" + complicated cases... + wiki links
• indented text "<div class=\"indent\">" "</div>" + complicated cases...
  • "<itemizedlist>\n";
  • "<orderedlist type=\".

- l'encodage des caractères doit respecter le DocBook (faut-il faire un remplacement des é ? comment ça marche pour le Polonais ?)

Lancement

Ceci génère le fichier xml au format DocBook :
http://faq.eagle-usb.org/eagle-faq.php?page=DocBookFr (la page que l'on veut en fait)

http://faq.eagle-usb.org/eagle-faq.php?page=DocBookUs in English

http://faq.eagle-usb.org/eagle-faq.php?page=DocBookEs en Espanol

Conversions

Une fois la page xml obtenue, la sauvegarder.
Des explication ainsi que des liens pour savoir comment générer la documentation dans différents formats sont fournis sur la page DocBook.

Architecture Logicielle

Si j'ai bien compris, en fait je souhaiterais quelquechose du genre :
- lancement par l'appel à une URL du programme avec en paramètre la page wiki

• interface utilisateur = page wiki pour entrée des paramètres
• interface interne = transformation page wiki en fichier xml de paramétrage

- moteur d'obtention des pages / conversion à la volée wiki vers DocBook pour génération fichier xml
- lancement convertisseur DocBook vers ce qu'on veut (c'est avec openjade par exemple ?) ok précisé dans DocBook
Je ferai un beau schéma avec dia dès que je peux... -- BenoitAudouard 20031126 ok précisé dans DocBook

---

20031126
Je te propose de faire comme ça pour gérer les titres de chaque section et la page wiki associée :

<qandadiv id="FaqGeneralFr">
<title>Questions générales sur le driver Eagle-USB</title>
</qandadiv>

Comme ça, ca se fond un peu plus dans la syntaxe docbook. Qu'est-ce que tu en dis ? -- FrankJ


Nope, j'ai pas un moteur de conversion wiki vers DocBook mais un simple script qui parse un certain formatage wiki pour le reformater avec quelques balises xml de DocBook, y'a une grande différence.
En fait, le script est juste un 'quick hack' pour nous permettre d'avoir les FAQs en docbook rapidement (enfin, relativement...), mais je pense qu'il faudrait avoir un outil mieux adapté pour cette tâche, toujours en collaboratif style wiki. Pour ça, WikiText est assez intéressant. Reste à l'évaluer. Je ne me suis pas encore penché dessus, si ce n'est l'outil de conversion style WikiText->DocBook qui se trouve sur le CVS de http://www.tldp.org (écrit en perl).
Je pense donc que dans un premier temps, mieux vaut se contenter d'un fichier template en xml à éditer et de fournir plutôt du temps pour réfléchir sur une solution plus efficace, une solution qui pourrait être réutilisée pour maintenir la partie docs en ligne par exemple, faire des tests etc...
-- FrankJ 20031126


Je ne suis pas pour utiliser le script de transformation wikitext => docbook en perl mais pour se renseigner sur les différentes solutions possibles qui seraient plus adaptées à notre cas, à savoir, je pense, permettre un travail collaboratif en ligne (style wiki) de production de documentations (docbook, le standard) que ce soit une FAQ ou bien un guide d'installations sur une distribution particulière. Je suis tout à fait d'accord sur les contraintes actuelles (langage php, backend Mysql).

Si je comprends bien, tu incluerais également comme contrainte l'utilisation de wikini bien qu'il ne soit pas vraiment prévu pour autre chose que la production de pages html basiques d'après une syntaxe brute simple. Je ne penses pas qu'on puisse atteindre le but de produire de la documentation docbook "correcte" avec wikini (tel qu'il est actuellement) de façon simple et assez intuitive.
Mais si tu aimes bien les produits étagères, pourquoi vouloir privilégier wikini qui nous demandera soit de "bidouiller" pas mal les sources ou bien de demander aux contributeurs de se plier à des règles très particulières et spécifiques mais non moins contraingnantes ?

Pour les docs en lignes, je ne pensais pas remplacer spip, bien entendu, mais utiliser la solution retenue pour la FAQ (création en ligne de docs de manière collaborative style wiki) afin de compléter, corriger, reformuler, préciser un peu plus les docs qui se trouvent sur spip. En gros, ce que je verrais bien, c'est que le wiki contient toujours la partie en développement active et constantes des docs (FAQ et guides d'install) et de manière ponctuelle (quand une release survient, un changement majeur a été apporté, etc...) on extrait les docs du wiki sous forme de docbook, et on place sur spip les formats dérivées du docbook. Ainsi tout un chacun peut participer, préciser les docs (j'ai bien galéré la première fois que j'ai installé les drivers car rien n'était précisé dans la doc d'install sur trick --noapic --acpi=off par exemple, j'aurais bien voulu noté ma "découverte" dans la doc après avoir passé pas mal de temps à chercher sur le web pour éviter à certain d'avoir la même chose à faire)

Sinon je t'ai fais parvenir un update du script pour gérer les derniers tags wikini (**,//,__,##, les liens et les listes), largement repris du code de wikini/wakka, à tester.
-- FrankJ 20031128
-- BenoitAudouard 20031128

---

20031127
Sinon les conversions de format wiki vers DocBook t'as une fonction miracle comme htmlspecialchars ? (wikispecialchars !?), faut gérer les liens externes aussi (entre crochets) -- BenoitAudouard
Pas de fonction spécial mais un resucé de la fonction wikini/wakka qui fait le formatage. C'est dans la dernière fournée. --FrankJ

Tests

---

20031124
Je prends ton essai par défaut :
http://faq.eagle-usb.org/eagle-faq.php?page=DocBookFr
ce serait pas mal d'ajouter un titre pour les sections plutôt que simplement le nom de la page prise en compte ?

achtung klein bug 20031124_001 (clos) : Erreur de parsing XML : pas bien formé
Emplacement : http://faq.eagle-usb.org/eagle-faq.php?page=DocBookFr
Numéro de ligne 400, Colonne 54 :Ne pas utiliser Drakconnect (Mandrake) actuellement <= 1.0.4e : cela ne sera supporté que par la prochaine version

>         // Convert special chars to entities; (&,<,>,',")
>         $body = htmlspecialchars($body, ENT_QUOTES);

Je crée une autre page DocBook2Fr : http://faq.eagle-usb.org/eagle-faq.php?page=DocBook2Fr
ok ça marche bien

-- BenoitAudouard 20031124

---

20031123

Premier test d'extraction : http://faq.eagle-usb.org/eagle-faq.php

Pour tester ce que ca donne une fois transformé: docbook-xsl contient des feuilles de style : http://sourceforge.net/projects/docbook/

---