One of the things we’ve mentioned wanting to do but not having time to do is making man pages for Tranquility. We then realized this is a wonderful opportunity for you all to get more experience with man pages and documentation. For 5 points extra credit on Project 2, write a man page for your favorite built in function in Tranquility or for the Tranquility compiler.
Alongside your project 2 submission, submit a plain text file named [function.txt] where [function] is the function you wrote your man page about. Instead of a header with your name, user id, and lab section, use the AUTHOR section at the end of your man page. You may also use the formats listed in man(7), but it’s not required.
Recall that in Question 5 on Lab 1, we introduced a small selection of commands you may find yourself using frequently on Tux. Back in Week 1 when Tux, Unix, and the command line was brand new, this section was most likely very overwhelming and confusing. Now that we’ve spent a few weeks on Tux, let’s revisit this question with a new perspective. Pro Tip: It’s always smart to revisit old material you struggled with, no matter how long it’s been since you last looked at it.
In Question 5, one of the commands we introduced was man. This command brings up the manual pages for other commands. By typing man mkdir, we get the manual page for mkdir. Go through some commands you use frequently and see if you understand their man pages now that you have a better grasp on Tux. Some man pages get quite hefty and overwhelming, but with practice, you’ll know how to find exactly what you’re looking for. Some commands with easy to read man pages include mkdir, cat, and wc.
Section 1 of the man pages contains the manuals for “Executable programs or shell commands”. Section 3 of the man pages contains the manuals for “Library calls (functions within program libraries)”. For those familiar with (or have heard of) the C Programming Language, you’ll be able to find the documentation for C in the third man section. This section will be the most useful when writing your man page. The following command brings up the man page for the C function puts which can be found in the third section:
man 3 putsSome commands can be found in many sections. For example, man is found in both section 1, and section 7. Section 1 focuses on how to use the man utility, while section 7 focuses more on writing man pages. You’ll see these referenced to by man(1) and man(7).
Given access to all the man pages on Tux and the Tranquility Programmers Manual, you should have everything you need to write an effective man page for your favorite Tranquility built-in function. If you can’t choose a favorite, try writing one for the tranqc compiler.
You may collaborate on the extra credit in ONE WAY ONLY. You are not allowed to collaborate when writing the man page, but you are allowed to collaborate to test them. These man pages are for you and your peers. If you’re worried about whether or not your man page is “good enough”, ask your peers to read it. “Hello [friend]. last week you struggled with [function]. This is what I wrote about [function]. Does this help clear up your confusion?” If your [friend] understands the material conveyed, then you’re doing a good job.
You will recieve credit based on how accurately you applied the standard man page formats and how accurate the information you provided is. If we think you did an exceptional job, we’ll include your man page in the Tranquility documentation we use in the future (with credit of course).
Submit a plain text document named [function].txt where [function] is the name of the function you wrote your man page about. For example, tranqc.txt or setcellcolor.txt. Instead of a header with your name, user id, and lab section, use the AUTHOR section at the end of your man page. You may also use the formats listed in man(7), but it’s not required.