Homework 2 (optional)
Spring 2013
This optional homework is to demonstrate how to use doxygen to generate documentation from documentation (doc) comments. By default, doxygen produces documentation in two formats: HTML and LaTeX (pronounced 'lay-TEK'). HTML is the hyper-text markup language, which one uses for writing Web pages. LaTeX is a typesetting program widely used to produce technical publications. After producing documentation in these formats, you will generate a PDF file using the documentation in LaTeX and publish a Web page using the documentation in HTML.
Note that in order to complete this homework you need to fix any problems with your doc comments. When you run doxygen on your source code, it prints error messages for the problems it finds.
I created a screencast to accompany this exercise:
cs-class% cd p2 cs-class% doxygen *.h *.ccIf you used extensions other than .cc, just substitute .cpp for .cc. This command grabs and processes the doc comments present in all of your .h and .cc files.
You should see an obscene amount of output, but eventually you should return to the cs-class prompt, and after listing the contents of the directory, you should see two new directories: html and latex. We'll first generate a PDF file from documentation in LaTeX, and then we'll publish the HTML documentation on the Web. A transcript of my session appears below.
cs-class% cd latex cs-class% lsYou'll see a bunch of files, but you should see your friend Mr. Makefile.
Be bold and type 'make'. You will again see an obscene amount of output, but when it stops, again list the contents of the directory. You should see a number of files with the root 'refman', which is an abbreviation for reference manual. There should be a file named refman.pdf. You can transfer that file to your laptop and view it like any other PDF file.
The following is a transcript of my session. Bold type denotes commands I typed.
cs-class% cd p2
cs-class% ls
bike.cc bikes.dta delivery.h main.cc Makefile.dep
bike.h bikes.h factory.cc main.h urban.cc
bikes.cc delivery.cc factory.h Makefile urban.h
cs-class% doxygen *.h *.cc
Searching for include files...
Searching for example files...
...
Generating page index...
Generating graph info page...
cs-class% ls
bike.cc bikes.dta delivery.h html/ main.h urban.cc
bike.h bikes.h factory.cc latex/ Makefile urban.h
bikes.cc delivery.cc factory.h main.cc Makefile.dep
cs-class% cd latex
cs-class% ls
annotated.tex classBikes.tex classDelivery.tex doxygen.sty
classBike.eps classBike.tex classUrban.eps hierarchy.tex
classBikeFactory.tex classDelivery.eps classUrban.pdf Makefile
classBike.pdf classDelivery.pdf classUrban.tex refman.tex
cs-class% make
echo "Running latex..."
Running latex...
latex refman.tex
This is TeX, Version 3.14159 (Web2C 7.4.5)
...
Transcript written on refman.log.
...
echo "Rerunning latex...." ;\
latex refman.tex ;\
latex_count=`expr $latex_count - 1` ;\
done
cs-class% ls
annotated.tex classBikes.tex classUrban.aux Makefile refman.out
classBike.eps classBike.tex classUrban.eps refman.aux refman.pdf
classBikeFactory.aux classDelivery.aux classUrban.pdf refman.idx refman.tex
classBikeFactory.tex classDelivery.eps classUrban.tex refman.ilg refman.toc
classBike.pdf classDelivery.pdf doxygen.sty refman.ind
classBikes.aux classDelivery.tex hierarchy.tex refman.log
cs-class% ls refman.pdf
refman.pdf
cs-class%
Log on to cs-class.
The first step is to open two directories to the Web server. Unix has three types of privileges: u for user privilege, g for group privilege, and o for other privilege. For files and directories, each type has three permissions: r is for read permission, w is for write permission, and x is for execute permission.
If you do a long listing of the files in your directory by typing 'ls -l' at the prompt, the string in the first column of the listing shows the privileges of the files and directories (e.g, -rw-rw----). There are 10 positions. The first position indicates whether the file is a directory. Normal files have a hyphen in the first position; directories have a 'd'. The next nine positions show the read, write, and execute access for users, groups, and others, respectively. There are three types and three permissions for each type.
To set file and directory privileges, we use the chmod command, which changes the mode of files and directories.
To specify the mode for directories and files, we use a string that consists of references, an operator, and modes. References designate the type: u for user, g for group, o for other, and a for all. An operator is either +, which adds permissions, or -, which removes permissions. Finally, the modes are the permissions: r is for read, w is for write, and x is for execute. X sets execute privilege for directories, but not files. (We call also use three octal digits where each digit corresponds to user, group, and other, and each digit's bits correspond to read, write, and execute.)
As an example, if we wanted to give everyone execute privilege to the directory test, we would write 'chmod a+x test'. If we wanted to turn off all group and other privileges for all files in a directory, then we would write 'chmod go-rwx *'.
To set the privileges for your home directory, type:
cs-class% cd <-- Takes you to your home directory cs-class% cd .. <-- Moves up to the parent directory cs-class% chmod o+rx <your-netid> <-- Adds read and execute permission for other cs-class% ls -l | grep <your-netid> <-- Lists the files and searches (greps) for your netid drwxr-xr-x 20 <your-netid> <your-netid> 4096 Feb 9 14:57 <your-netid>/If you don't see the the permissions string drwxr-xr-x, then something didn't work, and you should come see me before proceeding.
The next step is to create the directory for your Web pages. By default, the Web server on cs-class always serves pages from the user directory public_html. Once created, you'll need to set the correct permissions, which must be read and execute for others. To do this, type the following:
cs-class% cd <-- Takes you to your home directory cs-class% mkdir public_html <-- Makes the directory public_html cs-class% chmod o+rx public_html <-- Adds read and execute permission for otherTo test that you've configured your Web directory correctly, descend into the public_html directory, copy the simple Web page from my cosc052 directory, and set the file's permissions so others have read permission:
cs-class% cd public_html <-- Descends into public_html cs-class% cp ~maloofm/cosc052/index.html ./ <-- Copies the Web page into the current directory cs-class% chmod o+r index.html <-- Adds read permission for other cs-class% ls -l index.html <-- Displays the long listing of the file -rw-r--r-- 1 <your-netid> <your-netid> 37 Jan 18 22:12 index.htmlNext, go to your favorite Web browser, and see if cs-class will serve you the page. Type the following URL with the appropriate substitution into the address bar:
http://cs-class.uis.georgetown.edu/~<your-netid>The string "Hello!" should appear in your browser, along with a dead link to "P2 Documentation." If this doesn't work, guess what? Come see me.
The next step is to make a directory for your documentation, copy it from your p2 directory, and set the proper file and directory permissions. Use pwd to make sure you're in the public_html directory. If you are not, then type:
cs-class% cd cs-class% cd public_htmlOnce in the public_html directory, type
cs-class% mkdir p2docs <-- Makes a directory named p2docs cs-class% cd p2docs <-- Descends into the directory p2docs cs-class% cp -r ~/p2/html/* ./ <-- Copies recursively the contents of p2/html to the current directory cs-class% cd .. <-- Moves up to the directory public_html cs-class% chmod -R o+rX p2docs <-- Adds read and execute permissions recursively for other for the directory p2docsAssuming that your documentation is in the directory $HOME/p2/html, you should be able to use your browser to click the link to "P2 Documentation". Click around and check it out.
N.B. At this point, the directory public_html is a public directory, so do not put anything in that directory that you don't want everyone on the Internet to access. After completing this step, if you want to take down your Web pages, you can change the permissions of the files and directories:
cs-class% cd <-- Takes you to your home directory cs-class% chmod -R o-rx public_html <-- Recursively removes read and execute privilege for other for public_html and all files and directories thereinIf you want to completely remove these directories and files, type the rather dangerous command:
cs-class% cd <-- Takes you to your home directory cs-class% rm -r public_html <-- Recursively removes public_html and all therein
My documentation: P2 Documentation.
A transcript of my session follows:
cs-class% cd cs-class% cd .. cs-class% chmod o+rx maloofm cs-class% ls -l | grep maloofm drwxr-xr-x 19 maloofm maloofm 4096 Feb 9 16:09 maloofm/ cs-class% cd cs-class% mkdir public_html cs-class% chmod o+rx public_html cs-class% cd public_html cs-class% cp ~maloofm/cosc052/index.html ./ cs-class% ls -l index.html -rw-rw---- 1 maloofm maloofm 103 Feb 9 16:11 index.html cs-class% chmod o+r index.html cs-class% ls -l index.html -rw-rw-r-- 1 maloofm maloofm 103 Feb 9 16:11 index.html cs-class% pwd /home/maloofm/public_html cs-class% mkdir p2docs cs-class% ls index.html p2docs/ cs-class% cd p2docs cs-class% cp -r ~/p2/html/* ./ cs-class% ls annotated.html classDelivery-members.html hierarchy.html bike_8h_source.html classes.html index.html bikes_8h_source.html classUrban.gif installdox* classBikeFactory.html classUrban.html main_8h_source.html classBikeFactory-members.html classUrban-members.html search/ classBike.gif delivery_8h_source.html tab_b.gif classBike.html doxygen.css tab_l.gif classBike-members.html doxygen.png tab_r.gif classBikes.html factory_8h_source.html tabs.css classBikes-members.html files.html urban_8h_source.html classDelivery.gif functions_func.html classDelivery.html functions.html cs-class% cd .. cs-class% chmod -R o+rX p2docs cs-class%
Copyright © 2019 Mark Maloof. All Rights Reserved. This material may not be published, broadcast, rewritten, or redistributed.