Saturday, June 17, 2017

Updating Doxyfile

Depuis 2014, je n'utilise apparemment plus que d'anciennes versions de mon code sur ma liseuse Cybook. Du coup, l'utilité s'en trouve assez bien réduite. En cause ? le comportement du nouveau doxygen (1.8.11 contre le 1.7.6 qui avait donné des résultats plus satisfaisants à force de bricole).

Pendant un moment, je me suis dit que je ferais mieux de passer par DocBook (dont je ne sais pas grand-chose excepté le fait qu'il s'agit d'xml). En fait, ce ne serait pas la bonne approche:
  1. le générateur de documentation DocBook de doxygen ne fournit pas les "fragments de code" qui sont essentiels pour mon utilisation
  2. s'il existe des epub-tools pour faire la conversion docbook->epub, le contenu même du format e-pub c'est ... de l'HTML.

It looks like the last time I updated code shown on my cybook e-ink reader was in 2014. The reason is the newer doxygen that came with with ubuntu since then produces HTML code that makes much less usable epubs.

I realize that CSS support on cybook is picky on what works and what doesn't. Plus there are now 'tooltip' additional information that calibre unrolls between each function. And line numbers, which I don't need in this context either and impede readability.

J'ai donc repris point par point les choses qui posent problème dans la sortie de doxygen 1.8.11
  • les modifications pour que le code ressemble à du code et ne soit pas trop grand ne marchent plus. La faute à un nouveau jeu de règles CSS. Mais en réalité, les modifications que j'avais apportées à ces règles sont assez peu nombreuses, et je devrais donc pouvoir faire l'équivalent sur le nouvea fichier CSS.
  • les blocs indésirables en fin de fragment de code sont en réalité les tooltips, rendus visibles soit par calibre (le logiciel que j'utilise pour la conversion HTML->epub), soit par mon remplacement sauvage du .css de doxygen 1.8 par un .css modifé venant de doxygen 1.7 ... quoi qu'il en soit, définir SOURCE_TOOLTIPS=NO permet de les évincer du code HTML sans devoir y aller à coup d'expressions régulières. Et si rien ne m'indiquait que c'était possible dans mon DoxyFile, c'est tout simplement que je travaillais dans un fichier 1.7 où la fonction était indisponible ^^"
  • les indentations déviantes s'expliquent par une largeur de tabulations de 3 dans les règlages de Doxygen alors qu'elles sont définies à 8 caractères dans mon éditeur. Et que malheureusement il y a toujours dans le code un mélange d'espaces et de tabulations pour indenter le code >_<
  • Enfin, pour les numéros de lignes, je n'ai rien trouvé pouvant les supprimer, mais ils ont heureusement une structure très prévisible dans le code HTML. Un sed -ie "s:[ 0-9]*::g" *.html, et on en sera quitte.
Et je préparais un commentaire désobligeant sur la lenteur de conversion à laquelle calibre m'avait habitué, mais il semble que la version présente sur Ubuntu 16.04 a réglé ça. Voyons donc ...

Verdict : il y a encore du travail. Lors de la conversion, je me farcis un retour à la ligne chaque fois qu'on passe à un autre type d'élément syntaxique connue (un mot-clé, un type de donnée, une variable reconnue, une chaîne littérale, etc.)

    No comments: