Mot-clé - docbook

Fil des billets - Fil des commentaires

jeudi, février 15 2007

Générer seulement la table des matières avec DocBook

Je cherche à générer la table des matières du livre PostgreSQL. Seulement la table des matières, toute la table des matières. Si quelqu'un a une idée, je suis preneur.

Je sais bien comment générer un seul chapitre, ou comment sélectionner les parties à afficher dans un ou plusieurs chapitres. Je connais aussi le coup du maketoc.xsl. Mais tout cela ne me donne aucune idée sur la façon de générer seulement cette foutue table des matières.

dimanche, mai 7 2006

Manuel de PostgreSQL, le retour

Après avoir expliqué rapidement ce que l'équipe de traduction française avait réussi à faire suite au passage du SGML au XML, j'ai remarqué qu'il me manquait les solutions à deux problèmes pour faire de même avec la documentation originale.

Tout d'abord, la documentation originale comprend des insertions conditionnelles. En effet, le chapitre d'installation est aussi un document spécifique généré pour être inclus dans le package des sources de PostgreSQL. Ce fichier contient le mot document quand il fait partie de la génération du fichier INSTALL et contient le mot chapitre quand il fait partie de la génération complète du manuel. Parfois, ce sont des sections entières qui sont intégrées ou ignorées. Comment faire pour obtenir le même résultat en XML Docbook ? Il existe un moyen simple : les attributs de profile. Il existe des attributs standards comme os. En indiquant <para os="linux">linux-2.6.16</para><para os="windows">Windows XP</para>, vous obtiendrez un paragraphe contenant le texte « linux-2.6.16 » avec le profile os=linux et vous obtiendrez un paragraphe contenant le texte « Windows XP » avec le profile os=windows. Sans profile, vous n'aurez pas de paragraphe. Vous pouvez aussi créer des attributs personnalisés. Comme aucun des standards ne me convenait, j'ai créé un attribut que j'ai ajouté à chaque élément conditionnel. Vous trouverez ici la liste des modifications. J'arrive donc maintenant à générer un document autonome concernant l'installation.

Mon deuxième problème est la génération des pages man. Je n'ai pas encore terminé mais j'ai réussi à générer une page man... pas très belle, mais elle se génère. Toutes les infos sont disponibles ici grâce à l'excellent « Guide complet de Docbook XSL », malheureusement en anglais. Il serait temps qu'il se trouve un traducteur :)

samedi, avril 29 2006

PostgreSQL manual in PDF

We have three major releases of the PostgreSQL manual in french : 7.4, 8.0 and 8.1. They are all written in SGML Docbook. We use openjade to convert thems in HTML files, and htmldoc to convert the big HTML file in PDF.

Three weeks ago, friends start talking about migrating to XML Docbook. They mostly did it. I just had some mistakes and a few tags to fix. This done, we used LFS makefile and XSLT files to build the HTML manual. It worked great. But then I told to myself that I should look into building a better PDF manual. htmldoc did a great job with the HTML file we provide but the result was kind of ugly. So I started working on it : fixing some issues in the XML files, adding icons, updating the XSL filters, upgrading FOP.

It took me two weeks to create this PDF manual but I'm very proud of it.

vendredi, avril 21 2006

Génération superbe pour LFS, suite des aventures pour PG

J'ai fait un petit break sur le manuel de PostgreSQL et j'ai terminé celui de LFS. J'ai repris les scripts de génération et les feuilles de style de la version originale. Après personnalisation (principalement le remplacement des URL vers internet par des chemins locaux), j'arrive enfin à ce que les images et la feuille de style soient prises en comptes sur la génération HTML et sur la génération du PDF. J'ai aussi fait quelques corrections pour avoir un document XML valide.

Je suis retourné ensuite au manuel de PostgreSQL. migus a découvert que les sources XML n'étaient pas valides. J'avais pourtant bien utilisé xmllint mais j'avais seulement demandé une vérification de la syntaxe XML, pas une validation par rapport à la DTD DocBook. Un « xmllint --valid » plus tard et je me retrouve avec plus de 1300 erreurs ! La correction a été assez longue, principalement des balises mal positionnées par rapport aux autres, une erreur invisible en SGML. Malheureusement, ça n'a pas suffit. Arrivé à la page 422, la génération s'arrête pour la même erreur qu'avant... m'en fous, je finirais bien par l'avoir !

jeudi, juin 2 2005

Petite anecdote pour tous les damnés du format DocBook

Tristan Nitot relate dans son blog une petite anecdote lors du forum XTech 2005 avec Norman Walsh, inventeur du format DocBook

J'ai aussi une petite anecdote à propos de Norman Walsh, inventeur de DocBook. Il faut savoir qu'en 2002, alors qu'on préparait OpenWeb, on s'est demandé dans quelle syntaxe on allait écrire nos articles. J'étais plutôt partisan de XHTML, mais il nous manquait un peu de sémantique pour un certain nombre d'éléments. Un fantasme à peine camouflé était de pouvoir générer des documents PDF directement depuis nos documents Bêtement, j'ai laissé Fabrice imposer DocBook à l'équipe. Depuis, on traîne ce format surpuissant comme un boulet : DocBook est peut-être très bien pour écrire des ouvrages hautement structurés en plusieurs volumes, mais pour un site Web, c'est doucement overkill, comme on dit chez les ricains. Bref, je vais serrer la louche à Norman Walsh, et je lui raconte cette histoire. Très gentil, il me suggère de prendre la photo de lui prise par Daniel, d'en faire un tirage papier format poster, et de s'en servir comme cible pour fléchettes à chaque fois qu'on maudit DocBook :-D. En plus d'être très brillant, Monsieur Walsh a de l'humour, qu'on se le dise (et qu'on se le rappelle à chaque fois que l'on peste sur la complexité de son format) !

Si donc, comme le dit Tristan, vous pestez contre le format DocBook, vous savez ce qu'il vous reste à faire :)

samedi, avril 16 2005

En vrac

Allez, un peu coup de « en vrac », même si certaines infos sont assez importantes :

  • extension Firefox : FxIF (Firefox exIF) vous permet d'accèder aux données EXIF contenues dans les images JPEG à partir de l'élément Propriétés du menu contextuel des images sur Firefox (la plupart des appareils photos numériques ajoutent des données, comme le zoom, l'exposition, le nom de l'appareil, aux images que vous prenez) ;
  • extension Thunderbird : FolderpaneTools permet de personnaliser l'affichage du panneau des dossiers (par exemple en changeant l'ordre des comptes ou bien en modifiant le dossier de démarrage, ce premier point étant important pour moi au travail) ;
  • docbook wiki : je n'ai aucune idée de ce que ça vaut, mais je tiens à conserver un accès à ce site :) ;
  • la distribution Kubuntu 5.04 est sortie, d'où des revues comme ce test de Kubuntu par frlinux.net (j'aime bien kubuntu mais certains défauts me pèsent... peut-être un futur billet en préparation) ;
  • nouvelles fonctionnalités sur gmail : interface en français et saisie de style (gras, italique, ...) dans un mail.

jeudi, novembre 4 2004

Fin de la traduction des .po de PostgreSQL

Hier soir, j'ai pu envoyer le dernier .po de PostgreSQL. La page d'internationalisation de Peter Eisentraut montre clairement un taux de 100% sur tous les fichiers français, si on laisse de côté le dernier fichier que je viens d'envoyer. Il est donc maintenant certain que la prochaine version de PostgreSQL sera entièrement disponible en français :-)

Quant au manuel, je continue la traduction de func.sgml, le plus gros fichier du manuel. J'ai aussi traduit aujourd'hui les fichiers page.sgml, gist.sgml et plhandler.sgml. Demain, j'ai dû en prévoir six autres.

De toute façon, la traduction du manuel devrait se faire plus rapidement. En effet, il me reste assez de RTT pour me permettre d'en prendre un par semaine jusqu'à la fin de l'année. Je vais donc bosser sur cette documentation un jour par semaine... en plus de ce que je fais déjà :)

En attendant, le plus dur sera de trouver un moyen pour générer cette documentation. Depuis mon passage à Debian, j'ai quelques soucis avec les outils DocBook. Je vais essayer de règler ce problème ce week-end car cela commence à être vraiment handicapant.