Last edited 8nov15
Advice on Documenting a ProjectTo adapt this page for your own purposes, you must look at its code.
- ITEMIZATION makes reading a list easier and more memorable.
- JARGON: distinguish between technical and vulgar uses of a word.
- CITATIONS are required in scholarly work.
- EQUATIONS and math formulas need to be properly formatted.
- FIGURES may have to be color inverted to avoid too much black.
- MARGINS and headers make a document look professional.
- CODE should appear in typewrite font, just like it looks.
HTMLIn 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.
CitationsOK, 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.
JargonNote 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.
EquationsThis 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:
FiguresThere 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 WindowsJust use Paint, it has an inversion feature. But I can't tell you about it here.
... on the WebHere 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.
ReferencesAlthough 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.
-  Observe that this isn't really a citation at all, but just a cross reference that is used like a citation here.
-  with your name replacing "ivanhoe"