In Python code that processes some geometrical data I want to explain what each variable like w1, w2, h2, h3, etc, means in the geometrical objects. In such situation I don't use longer and more clear variable names because in geometry I'm used to use short vertex/line/length names, finding them more readable in the various formulas. Complex formulas full of long names become huge and not much readable anyway.
To explain what those w1, w2, h2, h3 mean I can use text, or sometimes ASCII art. But ASCII art is very low-resolution, so I have found that a single little image can explain the meaning of lot of variables (and other details) in a short space. Leaving the explanations to normal textual comments. So in this situation I have sometimes created a quite small image (1 bit/pixel) that encoded in png image format may require just few hundred bytes. With Python I encode is binary data string in base64, and I paste that as a string into the Python souce code. It probably takes only 4-7 lines or so. With one or two more lines of Python I can decode that string it and save as png again (usually this image decoding line is commented out or executed only if a debugging global variable is true). So far I have never used SVG vector images for such purpose, but they are another possibility (the SVG ones may need to be bzipped2 before the base64 encoding). This way there's no risk of losing the essential image, because it's embedded into the Python code. Have you ever done this? Do you think such "documentation picture" (analogous to a docstring) is an acceptable practice? I don't need to do that often enough, so I think it doesn't deserve to become supported by Python itself. While I presume emacs and similar "advanced" editors can be programmed to recognize such string pictures and show them inlined... :-) Bye, bearophile -- http://mail.python.org/mailman/listinfo/python-list