The Notebook App uses Tcl as a markup language. This is certainly an easy way of storing and retrieving information, but how is it regarded considering cleanliness of coding? Is it considered bad practice?
Well, I have always found markup languages, in general, to be obtuse if not actually hostile to use.
Some people prefer the verbosity and complexity of TeX related markup. Some are satisfied with HTML. Some want some variation of SGML/XML--Linuxdoc and DocBook, for example, are SGML and XML applications celebrated for their use in Linux documentation [L1 ].
But SGML based markup is pretty wordy, if not obtuse when trying to do various combinations.
In the Tcl man page world, the original docs were formatted with *roff markup. The reason for this was that the reference pages were installed in the same hierarchy tree as other system documentation, allowing one to use the man command to read the docs.
Later, when Windows was supported, doc was provided on that platform in some kind of help file format.
Extension writers tended to use the *roff for most docs, though a few (including bwidget) distributed their documentation in html.
A few efforts have occurred over the years to use something more cross platform. For instance, see the tmml for one effort to use an xml like format for tcl man pages. There is also the lightweight system Aida [L2 ] [L3 ] which has translators to many common formats.
Then, as a part of the tcllib effort, the doctools module was created so that tcllib module documentation could be more easily created. A developer using this notation can generate documentation files in a variety of formats.
I believe that [someone PLEASE replace this comment with the appropriate reference!] even tried the tcl commands as markup approach as well. Perhaps check this page's category list to see if you can turn up something.
RS: Of course Tcl can work as a markup language - see expand or entities, for instance.
EMJ: and expand is what lives inside the Notebook App mentioned at the top of the page!
"Some people prefer the verbosity and complexity of TeX related markup." - As a former TeX user, I feel that I must complain about the thought expressed here. TeX users don't prefer complexity; they prefer control (or need it), and are willing to live with the complexity in order to achieve it. One of my favorite TeX documents creates a table of the first n primes, where you get to choose n as you create the input file. The rest of the program not only formats a table with the n answers, it calculates the answers as well. Try doing that in HTML or other markup language. Tex is a solution to some very difficult formatting problems that would be hard to achieve any other way. At the time it was designed, it answered many problems that have since found other solutions. However, for the highest quality computer typesetting, I have not really found anything superior. (I truly love having fonts with the "ffi" ligature that can be used where it is appropriate.) - escargo 17 Sept 2004