pixdox

bon, je voudrais réintégrer une partie des images de ce blog à l'intérieur de la documentation Doxygen pour avoir un document de type "e-book" un peu plus complet. C'est particulièrement le cas avec les screenshots d'interface graphique pour les éditeurs, parce que redessiner les positions des boutons quand je veux comprendre pourquoi certains ne s'activent pas à chaque fois, ça devient vite lassant.

j'ai déjà fait un essai avec un fichier pour libgeds, qui s'était rangé dans 'pixdox/html' et qui était invoqué avec un \image html InspectorWidget.png dans InspectorWidget.cpp, moyennant IMAGE_PATH=pixdox dans le fichier Doxyfile pour libgeds... reste à faire pareil pour les autres.

Et il faudra copier les images de 'pixdox/html' à l'intérieur de dox/html ...

edit: oui, pendant quelques jours, ce post a bloqué tout le reste du blog. La faute à un copier-coller trop aggressif qui s'est terminé par une image encodée directement en base64 dans le post... J'imagine que les buffers de google n'ont pas apprécié.

Doxygen on Onyx

I don't exactly know what I have changed, but using the "Neo Reader" application on the Boox today, my doxygen-to-epub-through-calibre file now renders as expected. I thought that could be linked to the disabling of "cache reflow bitmap" cryptic option in the advanced settings (see the small icon pointed by the stylus on the picture), but re-enabling it doesn't change anything (or it only has an effect when restarting the application ?)

Qu'est-ce que j'ai changé ? Je n'en sais plus trop rien. J'ai "torturé" le morceau de code qui apparaissait dans la version e-pub de mon blog pour essayer de trouver ce qui faisait la différence entre un rendu correct (white-space: pre-wrap ? utilisation de
<pre>plutôt que <div>? de <tt> plutôt que <span>?

Rien n'a semblé avoir d'effet. Puis ce midi, en jetant un coup d'oeil à mon code converti par doxygen et calibre, surprise! tout est impecablement rendu.

Plus de numéro de lignes indésirables, changements de polices, traitement correct des espaces ... tout y est.

Est-ce que ça vient du réglage "cache reflow bitmap" que j'avais changé ? difficile à dire. Le désactiver ne semble pas avoir d'effet immédiat, mais ils auraient pu omettre de dire qu'il fallait redémarrer l'application ...

One major drawback, though: Neo Reader application is the only one for which I find no way to hop back to the place I was before following a link in the epub document. And that will make navigation extremely annoying, I'm afraid.
Neo Reader v2.0 had nice backtracking feature, and that one gets interesting behaviour on my test epub document.

• When using <span> or <div> with the CSS classes associated with working 'code-style' elements, nothing happens
• When using <pre> or <tt> with the same elements, code is rendered as it should (as printed on dot-matrix ;-)
• The style applied to "English section" (using <en>) doesn't go italic, while emphasis directly using <i> in the French part goes italic.
• skipping CSS classes altogether has no impact (given that you're using
  
  pre/tt tags)
• embedding the whole stuff in "blockquote" doesn't seem to have much effect
• trying to use tables with colspan and some cells containing only a few whitespaces failed miserably. I think all cells are just sitting in a vertical list, not laid out on a table at all. 

I got a Boox

J'ai reçu mon nouveau gadget à base d'encre électronique, donc. Même si au prix où il était, j'espère qu'il sera plus proche d'un ordi que d'un gadget, évidemment. Il s'agit d'un Onyx Boox 9.6" combinant un stylet magnétique et un écran capacitif.

I jumped completely out of my comfort zone and ordered online a device I never had in hands before at a price well over that of a Nintendo DS: the Onyx Boox N96, combining magnetic stylus (afaik), capacitive screen and e-ink display for roughly the size of a A5 sketchpad.

Malgré une boîte tout-en-chinois un peu intimidante, l'appareil a des menus en bon Anglais et la prise en main s'est faite assez facilement. Ma grande inquiétude, évidemment, c'était de savoir si je pourrai m'en servir pour mes documents "doxygen" si utile pour faire du développement intermittent.

The device feels right in hand, is quite a hybrid between an androïd tablet (unfortunately only 4.0, making applications for twitter, picasa and blogger unusable >_<), but what was really stressing me was to know whether I could use it for epub+doxygen code browsing I've been usiing sooo much for the last years to progress on my pet projects. And unfortunately, out of the 4 embedded readers, none of them got the layout right. No indentation, useless line numbers, incoherent spacing ... all of the issues I had fixed earlier this summer -- and some I never heard of before -- were back to haunt me.

Ce n'est pas gagné: sur les quatre lecteurs e-pubs embarqué, aucun n'a un système "styles de l'éditeur" comme mon regretté Cybook. Et sur chacun d'eux, le code produit a tous les défauts d'une mauvaise conversion: pas d'indentation, numéro de ligne inutiles, tailles incohérentes, etc.

J'avais compté sur l'installation de FBReader, testé avec succès sur la tablette de ma fée, mais c'était compter sans une dernière roublardise d'androïd: Il y a en réalité une version plus ancienne de FBReader dans le pack d'applications préinstallées, ce qui m'empèche d'installer une version plus récente pour cause d'erreur -104. (j'aurai peut-être plus de chances après une recompilation ?)

My plan was to use the open-source FBReader if such thing occured, but unfortunately, I couldn't install it from Google Play: interference between the pre-installed FBReader (older version) in the firmware makes it fail with error -104.

I was hesitating between sending it back and switching to some pure html-based doxygen crawling when a post in one of my blog-on-epub conversion caught my attention.

Bref, je m'apprétais à devoir me rabattre sur une utilisation de pages webs moins pratiques (pas d'annotations, pas de marqueur 'vous êtes ici' d'une lecture à l'autre, etc.) lorsqu'au détour d'un post de ce blog converti en fichier e-pub, je constate que l'un des lecteurs par défaut (je ne me souviens pas duquel il s'agit :P) que les styles sont tout à fais satisfaisants pour mes besoins:

• le bloc de code est en police monospace alors que le texte du post est en police classique,
• les indentations ont fonctionné correctement,
• (bin y'a pas denuméro de ligne, forcément, vu que je n'en ai pas mis. Haha.)

Le jeu, ça va être maintenant de comprendre la différence entre ce bloc-là et ce que j'avais dans mon document doxygen pour faire des doxygens qui marchent mieux.

See ? It's all there. Indentation, font switching... The CSS reading is there. The rendering works. It's all a matter of making the doxygen stuff damn simple enough so that it couldn't possibly fail. That's something I can handle. The boox may stay here.

UML_LOOK = YES ?

Voilà un des schémas que Doxygen peut produire si je le mets en mode UML (ce qui est sympa, parce que du coup, je peux comprendre les flèches) pour une des classes de mon éditeur de niveaux. Je peux limiter le nombre de "champs" pour chaque catégorie (histoire de garder la taille des boîtes sous contrôle), mais malheureusement pas la profondeur d'exploration. Résultat, le graphe devient vite immense, inutilisable.

When I come back to some code I've been writing long time ago (hey, the project is 10+ years old, now, remember?), I usually take some time with my cybook to study the code through doxyge-rendered documents and sketch in UML what is meaningful for the feature I want to add/change. So it would make sense to have doxygen do some UML for me, wouldn't it ?

Well, doxygen indeed has an UML_LOOK setting that turns available as soon as you declare to have the "dot" graph tool from graphviz package on your (linux) system. Neat. It also has -- took me some time to find them -- settings to reduce the amount of classes that are explored, and the amount of items that are reported for each class.

This is all quite nice, but I'm afraid it will not work nicely with cybook viewing. Whatever I do, the collaboration graph remains very large, both in pixels (and I'm unsure the cybook could pan in a bigger image) and in bytes (10x bigger than doxygen's defaults -- which had only inheritance graph, I admit).

Non configurable ? vraiment ? Voyons, et DOT_GRAPH_MAX_NODES, alors ? et DOT_GRAPH_MAX_DEPTH ?

Eh bien ils font plutôt du bon travail, mais je reste avec près de 3Mo de fichiers .svg pour LEDS, contre 500Ko de .png quand je reste aux graphes de base. Pour la lecture sur tablette, je crois que je préfère ne pas prendre le risque.

What would the perfect feature set be ?
- having the inspected class at the center of the diagram
- be able to specify a canvas size, instead of a maximum amount of nodes
- don't say "and ## more items" when you drop some items
- have a separate "depth" setting for inheritance and for structure/composition
- only show "meaningful" methods/fields of surrounding classes
- still show when a class has relationships with multiple classes of the graph
- don't show "obvious" common ancestors (e.g. the Widget class for all the widgets)
- don't show "obvious" type of data that everyone uses (e.g. std::vector) as a compound.

But let's be pragmatic: this is not the job of a heuristic filter: this is the job of an interactive exploring program. Sure I wish such an interactive tool could be running on my e-ink device, but this is not part of Cybook's business plans, unfortunately. And it is unclear that this could be achieved solely through e-pub documents structure. (would more require an HTML5 canvas or dynamic SVG + JavaScript)

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.)

Bowels of the Memory Manager ...

With cases stacking up, I got used to ignore all those testimonies that pretend that "Malloc is the killer, I've seen him". I wouldn't trade Malloc's skin for my oldest pair of gloves, as he's always the first one people blame.
Bah. People. What do they know about crime, after all...

Hopefully, I have other noses for such cases, so I paid tracemem.pl a visit and showed him the shots Coroner GDB gave me from the victim.
At first, Tracemem pretended to know nothing about that laying frame... he always does, until I provide him hexadecimal evindence he can't deny, as the victim's and suspects addresses.
"Free(man) is cheating you", he finally dropped, panting. "Look at those figures: these are not even addresses. I have no idea what this is, but this is certainly not addresses".
"When you've got no idea, Tracemem, it usually means you've seen them last week. I don't need idea, I need info. Tell me what you know".
"Okay, okay" he added "take it easy... You shouldn't mess up with those guys, really. They're trading bare hex they compile themselves in a hideout they name "AnimEDS". They say they can make you move in ways you've never experienced before. I don't have anything to do with these guys, right ? I just serve drinks when people order. I don't want any trouble".

I'd lost almost half a week, and all I know is that the last address where Free had been seen is fake, and actually a room in a building owned by someone else in the AnimEDS gang. Not yet enough to get the cavalry moving. I had need for another vision of the problem. I went to Doc Xygen and showed him the remains of GameScript. "I want descriptions", I insisted, "don't puzzle me with line numbers". I didn't tell him that pictures in malloc.h were made up from archives, but that's the best way to make him sing. With his usual frenzy, Doc Xygen started to show all the connection he could find. Among the expected ones, however, there were surprising exchanges. "Wait, SpriteSet got some cans from Malloc and directly sell them back to Free ?" I asked.
"Elementary", the Doc said, "SpriteSet is low on stack. With only 16K brutto, he's got to rent space to Malloc&Free for his loading activities on the docks.
Nothing to worry about. But ... hmmm ... *this* is interesting", he said, drawing a red circle around a triangle of pictures among the boxes and arrow he had scribbled all over the desk. "Interresting?"
"Clearly", he said. "Look, GobAnim and GameScript both tried to sell back some cans to Free, a few cycles from each other! Both pretending that they had the exclusivity on products by A'n'Im Eds"
"So they would have a tussle next to Free's place just as Malloc was going out!?"
"Of course", added the Doc. "Malloc gets back the cans that Free buys to the dockers, optionnally clears them and sells them back to other dockers. Everyone blame them, but noone else has cans to provide ..."

I fixed my hat and thanked the doctor: Malloc & Free's dubious activities are none of my business. I had a name to give to my client, and he'd be able to deliver his new product in due time. Happy clients make larger checks.

Doxygen & Cybook : round 2

That's for sure: doxygen output on a cybook is a great thing to plan the next update on my tools. I can do that any time while commuting, take simple notes and then just commit the changes into code when I get to a keyboard-enabled computer :)

Still, that requires a bit of tweaking of my Doxyfile configuration:

COLS_IN_ALPHA_INDEX    = 3
ALPHABETICAL_INDEX     = YES
REFERENCES_LINK_SOURCE = NO
REFERENCED_BY_RELATION = YES
FULL_PATH_NAMES        = NO

Au fil des mois, mon cybook odyssey se révèle de plus en plus un puissant allié pour la programmation de projets-hobby. Toujours en poche (ou presque), il me permet de planifier les évolutions de mon projet à tête reposée, dans mon fauteuil, sans nécessiter de réimprimer à chaque fois la dernière version du code. Il a évidemment fallu un peu chipoter pour avoir des documents "pratiques" sur cet écran 600x800, en enlevant les numéros de ligne ici, changeant la structure du document là, etc. Mais le résultat est plutôt satisfaisant.

J'aimerais juste que l'Odyssey soit capable de détecter les "clics" sur les schémas en mode "image map" (cf. p. 1629, par exemple) et que doxgen propose un mode "epub" natif qui m'éviterait de faire tourner "calibre" pendant près de 10 minutes pour la conversion html->epub.

Once the doxygen files have been created, I need to post-process them to strip out line numbers in the code. There's unfortunately no configuration setting to do that *in doxygen* itself, and I lost the patch that forced doxygen to avoid generating them altogether.
fe class*.html "mv % /tmp/% ; sed /tmp/% -e 's:/a>0[0-9]*:/a>:g;' > % ; echo % stripped"

Last step is to get rid of <namespace>:: prefix in some classes name (in the class index) so that it actually fits 3 columns.
mv classes.html /tmp/ ; sed /tmp/classes.html -e "s/>[A-Z][a-zA-Z]*::/>/g;" > classes.html

Unfortunately, calibre is still über-slow processing this, and it looks like the Cybook Odyssey doesn't support clickable image maps. Anyway, if you want to give it a try (and have the hardware as well), here's the file.

10: GOTO 10

To be honest, I didn't expected it to be that complicated to fix, with a lot of trials and source reading (on my shinynew Cybook) to figure out why the code behaved differently than I expected. But at last, AnimEditor is now able to set "sticky limbs" on the first frame of an animation as well, which in turn enables me to craft a walking animation for Bilou in the editor.

I took the time to document the thing a bit more, too. The trick is that I have two representation for the animation: the tlist that is a sequence of TIFrame at specified time positions. This is just perfect for editing, as each frame fully encode the state without any reference to past/future state. The game engine needs just the opposite: a list of commands that instructs it to move that limb, change the sprite used by this one, then move the whole sprite by x,y pixels and wait for 3 vertical refreshes. All these commands are encode()d into flat 32-bit integers that are easy to read and write to files. When exporting them, frames are compared and updates are generated when required. When importing, the last generated frame is copied after every delay and altered to reflect the new state. So far so good.

Bien. Voilà un deuxième point règlé dans ma "roadmap de l'été": je peux créer une animation qui déplace le personnage à chaque "frame", y compris entre la dernière et la premère image, lors du "rebouclage". Je vais (enfin?) pouvoir améliorer la marche de Bilou grâce à AnimEDS :) Ça ne fut pas aussi simple que je l'avais pensé, celà dit ... croyez-moi (ou apprenez l'Anglais :)

It gets a little more complicated with the "sticky limbs" thing. The editor needs to know which limb sticks at the same place on-screen. You do that by selecting one of the limbs on the leftmost "limbtable" and then pressing the "time/move" button just between the frame editor and the animation preview (highlighted on screenshot), which initially just reads 'time'. If you decide to move dumblador's sticky foot further to the right, dumblador will move faster, and if you move the foot closer to dumblador's body, it will slow down its walk.

At the export, the offset of the sticky limb compared to the previous position of that limb is used to generate a "I_MOVETO" command. Devil was in the details, as always: when should the information be cleared when reading back, how to handle the commands when a TIControl item is selected, and whether the additional I_MOVETO has to be stored at the end of the serialised animation or before all the other update commands.

Well, I got it more or less sorted out now. All I'll need is improve the walk animation itself and patch bilou.cmd so that it makes good use of it.

cybook + doxygen = long

Le Sprite Editor est en rade, mon fichier d'images pour la school zone de plus en plus mal en point ... et pourtant je "perds mon temps" à essayer d'avoir du contenu 'bilou' sur mon nouveau gadget: le Cybook Odyssey. Encre électronique, écran tactile, ce n'est pas la noteslate que j'espérais, mais au moins il existe ... et avec un peu de chance, il me permettra d'avoir les yeux moins fatigués en fin de journée, au boulot.

L'appareil supporte les fichiers HTML en natif, donc les choses auraient dû être assez simples ... Sauf qu'en mode "lecture de fichier offline", les liens sont ignorés dans le mode HTML. Il me faut donc passer au format dédié "epub".

Je me suis perdu dans des tentatives de conversion doxygen xml -> docbook -> epub en passant par les feuilles de styles XSL de la bibliothèque boost ... alors qu'il suffisait de prendre un fichier HTML et de le passer à calibre pour qu'il me fasse un "joli" epub prêt à l'emploi (en près de 5 minutes quand-même :P), récupérant lui-même les pages inter-dépendantes, etc.

I wasn't much into amazon library, but I managed to purchase a french e-ink device to get some publications shown without having to print things all over the time: the Cybook Odyssey. It has a touchscreen (that was a must for me) and WiFi, and while it is not the NoteSlate I hoped to purchase, it should help me avoiding eye strain at the end of the day.

Since it natively supports HTML content, showing bilou-ish things on it should have been trivial, but unfortunately, if you check some HTML in offline mode, many things don't work. Hyperlink, for a start. And annotations. If I want to have some doxygen on it, I'll have to convert it to the dedicated e-book file format: epub.

Et là-dessus, je n'ai toujours pas corrigé plus SEDS ... et il est temps d'aller souhaiter bonne fête à mon papa ^^"

EDIT: note pour les autres utilisateurs de cybook: il y a malgré tout moyen d'avoir les annotations, surlignage et signets pour les fichiers PDF même si ça n'apparaît pas directement dans le menu contextuel. Tapottez un coup dans le coin supérieur droit de votre cybook (comme vous pouvez d'ailleurs le faire sur les .epub) pour avoir directement le menu "annotations" qui apparaît. C'est un peu hésitant (toucher/relâcher ne marchera pas, ni un petit glissement. Il faut vraiment une petite touche du bout du doigt comme si vous vouliez vérifier que la casserole n'est pas trop chaude sans risquer de vous brûler. Par contre, si votre pdf est un vieux document numérisé sans reconnaissance de caractères (au hasard, un mode d'emploi de C64 ? :P), oubliez tout ce qui nécessiterait un surlignage pour l'instant: le cybook prend vraiment trop longtemps à essayer de trouver le texte à surligner dans ce cas-là.

After some aborted attempts to go through docbook format, I realised that there was a tool (calibre) that could do straight HTML->epub conversion, producing some decent output. It takes a while to process the file, though. Easily up to 5 minutes. 

Oh, and you could have annotations and 'highlighting' with PDF files too, although it doesn't show up in the contextual menu. Just double-tap the upper-right corner to get the annotations menu showing up.