Thursday, July 14, 2011

Documentation and more


I continue to work on my documentation idea. So far, I've run into two problems. First, I'll need my code to HTML converter to recognize strings so that doesn't mistake comment characters in a string as a true comment: printf("// not a comment"). Second, the problem of initial spaces: how can I properly translate them? If a source file indents a comment by 4 spaces then the following line of code by 4 spaces, it looks fine. However, in HTML the code font and comment font will be different, so those 4 spaces cause things to look ugly either in HTML or (if the spacing works in HTML) in the code.

I can think of a couple ideas:
  1. Auto-space -- in code, indent a comment line to match the spacing of the next code line. This would work most of the time. In HTML, do the same; make the space characters the same as the code font to insure alignment.
  2. In HTML, always insert the same number of spaces as the code, in the code font. How would I detect these spaces and automatically remove them when going the other direction? Perhaps tagging the initial spaces as .
For correctly recognizing strings, I'll need some sort of lexer. Yuck. One option is to start with the Python tokenizer; its' source code (see link on that page) contains all the necessary regular expressions. Another is to use Pygments, which I'll want for syntax highlighting anyway. I may hack around this for now just to get some working code, then return to fix it. A related but simpler problem is dealing with C /* */ comments.

In working with the idea, I'm continually surprised by how much just writing about the problem has helped me to solve it. I believe that this will be a big help for me in all future projects, if I can actually find the time to implement it.

Other things
Do robots take people's jobs? No, they empower people and create jobs, as the arguments in this article show. It included some nice historical perspective and facts (did word processors eliminate secretaries?).

I found a list of the top 25 most dangerous software errors (from a security perspective). Interesting.

No comments:

Post a Comment