CS410: Documentation

W. Michael Petullo

University of Wisconsin–La Crosse

As of March 15, 2021 Documentation: FOSS Project Discussion

◮ What project did you select? ◮ What led you to select your project? Did you use any resources or websites to learn of entry-level work? ◮ How does the community surrounding your project seem to communicate? ◮ Have you talked to any members of your project’s community? How? ◮ What do you hope to contribute to your project? ◮ Did you encounter any surprises when you tried to build your project? ◮ What are you worried about? Documentation: README/README.md (Simple)

◮ Text remains the most basic documentation format ◮ There exist a number of markdown (a play on markup) syntax ◮ Markdown is lightweight and legible both as source and rendered

=== Underline for heading level one (or precede with #) --- Underline for heading level two (or precede with ##) **bold** Indicate text should be bold *bold* Indicate text should be italic > block quote Indicate block quote Pandoc will transform mark- * list item Bullet list item down into other formats, e.g., 1. list item Numbered list item pandoc -f markdown strict -t html f.md ‘code‘ Treat as programming code [link name](link URL) Insert link to external document Documentation: troff/man (Consistent)

Legacy format used for manual pages

.TH indicates title, date, and version .SH starts a section, such as NAME or SYNOPSIS .SS starts a subsection, such as Options .TP builds a name/value list, here used to indicate a list of options \fB sets the type to boldface \fI sets the type to italic \fR sets the type to Roman, which will cause it to be rendered differently than other text \fP restores the current font to the preceding font

groff -Tascii -man hello.1 or man ./hello.1 Documentation: HTML (Accessible)

HyperText Markup Language is the markup language of the web.

paragraph of text

text

Augmented by Cascading Style Sheets.

1 body { 2 background−color: blue; 3 }

Sometimes generated dynamically in browser by JavaScript from server. Documentation: LATEX(Beautiful) Lecture notes in Flight Dynamics (Italian) \ documentclass { article }

\ title {The Art of Computer Programming} \ author { Donald E. Knuth}

\ begin {document} \ maketitle

Hello , TEX world!

\ end {document}

Manage you document and team using Git!

© Agostino De Marco Documentation: Doxygen and so on (Inline with Code)

/∗! \ mainpage Index Page ∗ ◮ ∗ \ section intro s e c I n t r o Follow convention when writing ∗ comments, and Doxygen will extract ∗ This is the introduction. documentation ∗ ◮ Doxygen example: ∗ \ section install sec Install ∗ https://dbus.freedesktop.org/ doc/api/html/index.html ∗ \ subsection step1 1: ... ∗ ◮ Similar tools: gtk-doc (uses GObject ∗ etc ... introspection), Sphinx (Python) ∗/ Documentation: Assignments

Graded Homework Aquinas troff due next Tuesday Reading Read Bernstein documents before Thursday; see if you can find details on the Internet about “crypto wars” and some of the things Bernstein mentions; you do not need to read all of the supporting communication between Bernstein and the US layers, but you should glance at some of it

https://www.flyn.org/courses/cs410-2021-spring/schedule