Writing III Marie des Jardins mariedjcs umbc edu

Writing III Marie des. Jardins (mariedj@cs. umbc. edu) CMSC 601 March 3, 2009 3/3/09 September 1999 October 1999

Sources u Justin Zobel, Writing for Computer Science: The Art of Effective Communication. Singapore: Springer. Verlag, 1997. (Chapters 4 -6) u Leslie Lamport, La. Te. X: A Document Preparation System (2/e), Addison-Wesley, 1994 3/3/09 October 1999 September 1999 2

Outline u La. Te. X resources and formats u Punctuation (chapter 4) u Mathematics (chapter 5) u Graphs and figures (chapter 6) 3/3/09 October 1999 September 1999 3

La. Te. X Resources and Formats 3/3/09 September 1999 October 1999

La. Te. X Websites u The Simplified La. Te. X beginner’s guide and tutorial http: //www. ctan. org/tex-archive/info/simplified-latex/ u The La. Te. X Wikibook http: //en. wikibooks. org/wiki/La. Te. X u La. Te. X Project home page: http: //www. latex-project. org/ u The UK Te. X FAQ: http: //www. tex. ac. uk/cgi-bin/texfaq 2 html/ u CTAN: the Comprehensive Te. X Archive Network: http: //www. ctan. org/ u Peter Flynn's Beginner's La. Te. X: http: //158. 110. 32. 35/LATEX/beginlatex. pdf u The AMS Short Math Guide for La. Te. X: ftp: //ftp. ams. org/pub/tex/doc/amsmath/short-math-guide. pdf u Keith Reckdahl, Using Imported Graphics in La. Te. X 2 e ftp: //ctan. tug. org/tex-archive/info/epslatex. pdf 3/3/09 October 1999 September 1999 5

Conference/Journal Formats u JAIR format (jair. sty, theapa. bst) http: //www. cs. washington. edu/research/jair/submissio n-info. html#formatting u AAAI format (aaai. sty, aaai. bst) http: //www. aaai. org/Publications/Author/author. php u SIGGRAPH format (acmsiggraph. sty, acmsiggraph. bst) http: //www. siggraph. org/publications/instructions/ 3/3/09 October 1999 September 1999 6

Punctuation 3/3/09 September 1999 October 1999

Commas u Commas must appear on both sides of a parenthetical remark The equation, which was formatted badly, was confusing. 4 The equation that was formatted badly was confusing. 4 The equation which was formatted badly, was confusing. 4 The equation, that was formatted badly, was confusing. 4 u Use final commas in lists 4 Commas, colons and semicolons must be used properly. 4 Commas, colons, and semicolons must be used properly. 3/3/09 October 1999 September 1999 8

Commas: Example u “Sentences should usually be short but commas and other marks give text variety” (Zobel p. 60). u “Sentences should usually be short, but commas and other marks give text variety” (Zobel p. 60). u “Sentences should usually be short, but commas and other marks add variety to text” (Zobel p. 60). 3/3/09 October 1999 September 1999 9

Commas, Colons, and Semicolons u Colons connect related statements and introduce lists 4 I know one use of a colon, it joins related statements. 4 I know one use of a colon; it joins related statements. 4 I know one use of a colon: it joins related statements. A colon is usually used for two things, to connect related statements and introducing lists. 4 A colon is usually used for two things: to connect related statements and to introduce lists. 4 3/3/09 October 1999 September 1999 10

Commas vs. Semicolons: Example u “Reading of mathematics is difficult at the best of times, unpleasant work if the mathematics is badly presented, and pointless if the mathematics does not make sense. ” u “Reading of mathematics is difficult at the best of times: unpleasant work if the mathematics is badly presented, and pointless if the mathematics does not make sense. ” u “Reading of mathematics is difficult at the best of times; it is unpleasant work if the mathematics is badly presented; and it is pointless if the mathematics does not make sense. ” 3/3/09 October 1999 September 1999 11

Hyphenation u Hyphenate word combinations that serve as adjectives, especially when needed to avoid ambiguity Squad helps dog bite victim. n (Does the dog really need any help? ) 4 Squad helps dog-bite victim. n (That was nice of them. ) 4 u Don’t hyphenate word combinations that include adverbs . . . there are well-established conventions. . . ” (Zobel p. 69) 4 . . . there are well established conventions. . . ” (Zobel p. 69) 4 u Don’t hyphenate word combinations that serve as nouns High-speed memory is needed for real-time performance. 4 The memory runs at high-speed. 4 3/3/09 October 1999 September 1999 12

Remark: That vs. Which u “Mathematics. . . is the only symbolism invented by the human mind which steadfastly resists the constant attempts of the mind to shift and smudge the meaning. . . ” (quoted by Zobel, p. 69) u “Mathematics is the only symbolism invented by the human mind; it steadfastly resists. . . ” u “Mathematics. . . is the only symbolism invented by the human mind that steadfastly resists the constant attempts of the mind to shift and smudge the meaning. . . ” (quoted by Zobel, p. 69) 3/3/09 October 1999 September 1999 13

Don’t Use Exclamation Points! u Especially not two of them!! u Or even more!!!! 3/3/09 October 1999 September 1999 14

Pluralization u Machine learning became popular in the 1990’s. u Machine learning became popular in the 1990 s. 3/3/09 October 1999 September 1999 15

Capitalization u Be consistent 4 Either Use All Caps in Your Headings 4 Or use initial caps 4 But please Don’t mix initial caps and All Caps u Names of techniques are rarely capitalized 4 We introduce the Texture Mapping rendering method. 4 We introduce the texture mapping method of rendering. 3/3/09 October 1999 September 1999 16

Punctuation and Quotation Marks u I disagree with Zobel 4 He “place[s] a punctuation mark inside the quotation mark only when it was used in the original text”. 4 He “place[s] a punctuation mark inside the quotation mark only when it was used in the original text. ” 3/3/09 October 1999 September 1999 17

Mathematics 3/3/09 September 1999 October 1999

Theorems u Number all theorems u Theorems should stand alone (i. e. , not be part of the surround text) 4 Indent or otherwise mark them clearly u Give a summary of theorem and proof approach before launching into lemmas and detailed proof u Omit unimportant details 4 3/3/09 October 1999 Leave out arithmetic manipulations September 1999 19

Equations u Center or indent equations to stand out from the text u Avoid long sequences of mathematical formulae in the text u Number equations only if they are needed for later reference 4 Some people suggest numbering all equations for reviewing purposes u Treat displayed equations as part of the sentence in which they are embedded u Explain your math 4 3/3/09 October 1999 Avoid unnecessary notation and acronyms September 1999 20

Notation u Be consistent, standard, and simple! 4 Notation often requires several revisions before you get it right u Explicitly introduce your notation 4 Don’t just start using it u Try to avoid recursive subscripts or combined subscripts and superscripts u Avoid “obscure” Greek letters u Don’t reuse symbols for different meanings 3/3/09 October 1999 September 1999 21

Numbers u Spell out numbers less than 10 4. . . except when used mathematically 4. . . except for percentages u Make sure the semantics of percentages and units are clear and unambiguous There was a 5% increase in performance. 4 Performance increased by 5%, from 65 to 68 correct answers. 4 The performance accuracy increased by 5%, from 65% to 70%. 4 3/3/09 October 1999 September 1999 22

Graphs and Figures 3/3/09 September 1999 October 1999

Figures and Graphs u Figures are great, but only if they actually convey meaning 4 System architecture diagrams often add no information u Graphs are generally better than tables 4 Be selective in which data to include u Use clear legends, axis labels, and line types 4 Colored lines, different types of dashes, and different tick marks on lines generally won’t reproduce well in black and white 4 Different line thicknesses are generally good, if there are only two or three types 4 Be sure you inspect the graphs in their actual size and context 3/3/09 October 1999 September 1999 24

Algorithms u Use commented pseudocode 4 I find Zobel’s pseudocode too close to real code 4 I find his “prosecode” far too wordy u Don’t include unnecessary detail u Using a comment column is sometimes helpful 4 use “tabular” environment in La. Te. X u Use math mode, not verbatim u Try using the algorithm 2 e package in La. Te. X! 3/3/09 October 1999 September 1999 25

Generating Figures and Graphs u Figures: 4 xfig 4 dia 4 latex 4 Power. Point 4 Word plus screenshot u Graphs: 4 Matlab 4 Gnuplot 4 Excel 3/3/09 October 1999 September 1999 26

La. Te. X Figures u usepackage{graphicx} u begin{figure} centering includegraphics{figfile} caption{Put Caption Here} label{fig: key} end{figure} u Graphics formats: (at least) JPG, PNG, PDF… 4 (If you’re using pdflatex. With latex and dvips, only embedded Post. Script (eps) figures are supported. This can be confusing…) 3/3/09 October 1999 September 1999 27