Last edited 8nov15

Advice on Documenting a Project

To adapt this page for your own purposes, you must look at its code.

Here are a number of common problems encountered when you prepare the documentation of your project, either as a printable webpage (HTML), a LaTeX .pdf document (LaTeX), or the hybrid called the Pudding, which uses JavaScript to translate LaTeX code to MathML in suitable browsers. The problems are listed in the order encountered, not in the order of importance.


In the original version of this webpage only straight HTML is used. Here, I use the Pudding because LaTeX was invented for technical writing, and the Pudding combines just enough of each, HMTL and LaTeX, to get by with some elegance.


OK, there is a lot of confusion about this issue. A citation is a mark in document, for instance a super-script 1, which refers the reader to a reference. The reference is often part of a bibliography, consisting of many more potential references than you actually cite in the document. The rule is never to put into the rerences what you don't cite. LaTeX, with its BibTeX feature, is the ideal way to construct your citations. But in HTML there is the internal reference tag which works quite well. Recall that a tag in HTML is anything between angle brackets. Be careful never to try using the left-angle-bracket as a less-than sign.


Note how I have used capital letters in the above itemization. That's memorable but ugly. For example, I'm defining what I mean by jargon by using it in a sentence. There's better examples of this in the previous paragraph. In technical writing one uses a different font the first time the technical meaning of common word is used. Thereafter, you may use the word without special decoration, provided you never again use with its common meaning. For example, in VPython there is the scene class, which is used to create and manage various scenic events and phenomena. Note, my use of word "scenic" in the previous sentece is very bad form. It This sentence declares the intention of using "scene" exclusively for the so-named class in VPython, and then uses the vulgar use of the word as part of its definition ... ?!. Don't you do this in your writing. In the above paragraphs on citations, I used "tag" early on, assuming that the reader knew I was talking about HTML tags. But I help the less experienced reader in the last sentence. In email, when all you have (or should use) is ascii characters, sometime you will see intended underlining, like this scene . But that's a matter of taste. All such decorations are intended to prevent confusion.


This being a mathematics course, you can't get away with badly formatted formulas. To do it right, do it like it's in the text books. Obviously, LaTeX is preferable. But in a pinch, you could form your equations in texPad, make a picture of it, and insert it into the webpage, like this:

Code in HTML is a problem

It is very difficult to find the right trick for inserting code fragments in a webpage. It's easier in LaTeX, and that is what Jared Schaber and Brent Nelson's \textit{Pudding} is for. Here is some math: \begin{eqnarray*} x & \leftarrow & \frac{z-x}{2}\\ y & \leftarrow & y \\ z & \leftarrow & \frac{z+x }{2} \\ \end{eqnarray*} Remember, their Javascript file translates only a small portion of math codes and formats into MathML, so it shows up in a browser. That, there are browser vendors who do not subscribe to this feature and do not endow their browsers with this capacity. Todate this includes Chrome and IE-Eplorer. Safari, I understand, now does work.


There is a ton of advice in Advice for this course on the subject of making figures, and including them liberally into documents. But on was skipped, namely how to invert a bit-map image so that black becomes white, even though intermediate collors look different. Recall that a color is described by a three-byte hexadecimal like ff0aff for 255 red, 10 green and 255 blue, which is a very slightly desaturated magenta. Its inverse (every 0 becomes a 1 and every 1 becomes a 0) would be (I have to calculate a=1010, not(a) = 0101 or 5 in hex) so 00f500 which is a nearly fully saturated green. OK? since we don't really care about colors unless you refer to them in your text, this quick an dirty way of printing blackish pix is OK.

... in Windows

Just use Paint, it has an inversion feature. But I can't tell you about it here.

... on the Web

Here is an (untested) link . Please try it, and tell me how to run it, and I'll put it here 2 .

Also, note how the Image tag of HTML can resize figures so as not to take up all the real-estage on your printout.


Although true LaTeX has a very elegant tool, BibTeX, for citations and bibliographies, this feature is not part of the Pudding. The following is a sort of citation in HTML.