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.  




 HTML 

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.


Citations

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.


Jargon 

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.


Equations



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. 


 Figures 

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. 


 References 

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.