Homework 3 (optional)
Spring 2011
This optional homework is to demonstrate how to use doxygen to generate documentation from 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.
seva% 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 seva 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.
seva% cd latex seva% 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.
To produce a PDF file, type
seva% dvipdf refmanIf you do another listing, in addition to the previous files, you should see a new one: refman.pdf, which is the documentation for p2 in PDF. Use secure ftp to transfer that file to your desktop or laptop and use Adobe Reader to view it.
Following is a transcript of my session. Bold type denotes commands I typed.
seva% cd p2
seva% ls
flat.cc main.cc Makefile pasta.h pastas.h round.h
flat.h main.h pasta.cc pastas.cc round.cc
seva% doxygen *.h *.cc
Searching for include files...
Searching for example files...
...
Generating page index...
Generating graph info page...
seva% ls
flat.cc html/ main.cc Makefile pasta.h pastas.h round.h
flat.h latex/ main.h pasta.cc pastas.cc round.cc
seva% cd latex
seva% ls
annotated.tex classPasta.eps classRound.eps Helvetica.ttf refman.tex
classFlat.eps classPastas.tex classRound.tex hierarchy.tex
classFlat.tex classPasta.tex doxygen.sty Makefile
seva% 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
seva% ls
annotated.tex classPastas.aux classRound.tex refman.aux refman.log
classFlat.eps classPastas.tex doxygen.sty refman.dvi refman.tex
classFlat.tex classPasta.tex Helvetica.ttf refman.idx refman.toc
classPasta.aux classRound.aux hierarchy.tex refman.ilg
classPasta.eps classRound.eps Makefile refman.ind
seva% dvipdf refman
seva% ls
annotated.tex classPastas.aux classRound.tex refman.aux refman.log
classFlat.eps classPastas.tex doxygen.sty refman.dvi refman.pdf
classFlat.tex classPasta.tex Helvetica.ttf refman.idx refman.tex
classPasta.aux classRound.aux hierarchy.tex refman.ilg refman.toc
classPasta.eps classRound.eps Makefile refman.ind
seva%
Log on to seva.
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.
We will first make sure that any new files you create will not be accessible to your group or to others. If, for Homework 1, you copied my configuration file (mm.cshrc) to yours (.cshrc), then you do not need to worry about this step. You can skip ahead and test to make sure that the umask setting is working.
If you didn't copy over my configuration file, I won't explain the details of this command here, but it sets the default privileges for new files:
seva% umask 077Since you want to set the umask each time you log in, we need to include the command in your shell's configuration file. Determine your shell by typing:
seva% echo $SHELLIf echo reports '/bin/tcsh', then you're using the T-C-shell, and you should type:
seva% touch ~/.cshrc seva% echo "umask 077" >> ~/.cshrcIf echo reports '/bin/bash', then you're using the Bourne-again shell, and you should type:
seva% touch ~/.bash_profile seva% echo "umask 077" >> ~/.bash_profileThese commands will add the umask command to the file that controls your account's settings.
To test that umask is working, log out of seva, and then log back in. Create a test file and list its permissions by typing:
seva% touch test seva% ls -l test -rw------- 1 <your-netid> <your-netid> 0 Feb 9 14:57 testIf you see anything other than that, it didn't work, and you should come see me before proceeding.
The string in the first column of the listing shows the privileges of the file 'test' (i.e., -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.
Our next task is to ensure that all of the files in your directory have only user privileges. To do this, we'll use the chmod command, which changes the mode of files and directories. Since we want to change the mode of all files, we'll recurse through all of your directories and files using the -R switch.
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. 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, then we would write 'chmod go-rwx *'.
To set the file and directory privileges so only you, the user, have access, we first need to navigate to the directory that is the parent of your home directory and examine that directory's properties. Type the following, substituting your netid for <your-netid>:
seva% cd <-- Takes you to your home directory seva% cd .. <-- Move up to the parent directory seva% 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>/As before, the first column shows your directory's permissions. Your directory may not have these exact permissions, but that doesn't matter because we're about to change them. To change the permissions of all of the files in your directory, type, again substituting your netid for <your-netid>:
seva% chmod -R og-rwx <your-netid>To check that this worked, type
seva% cd <-- Takes you to your home directory seva% ls -l total 24 drwx------ 2 <your-netid> <your-netid> 4096 Dec 15 18:11 cosc071/ drwx------ 2 <your-netid> <your-netid> 4096 Jan 14 15:28 hw1/ drwx------ 2 <your-netid> <your-netid> 4096 Jan 22 20:04 p1/ drwx------ 2 <your-netid> <your-netid> 4096 Feb 9 08:45 p2/ -rw------- 1 <your-netid> <your-netid> 6183 Jan 14 10:29 submit.jarFor all of the files and directories, you should see non-hyphen characters only in the first four positions. If there are non-hyphen characters in positions 5–10, then something didn't work, and you should come see me before proceeding.
The next step is to open two directories to the Web server. The first is your home directory, so type:
seva% cd <-- Takes you to your home directory seva% cd .. <-- Move up to the parent directory seva% chmod og+rx <your-netid> <-- Adds read and execute permission for group and other seva% 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>/While similar, this command is different than the previous one. We are adding read and execute privileges for group and other, but we are not doing so recursively (note the absence of -R), so we're making the change only to your home directory. 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 seva 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 group and other. To do this, type the following:
seva% cd <-- Takes you to your home directory seva% mkdir public_html <-- Makes the directory public_html seva% chmod og+rx public_html <-- Adds read and execute permission for group and otherTo test that you've configured your Web directory correctly, descend into the public_html directory, copy the simple Web page from my cosc072 directory, and set the file's permissions so group and other have read permission:
seva% cd public_html <-- Descend into public_html seva% cp ~maloofm/cosc072/index.html ./ <-- Copy the Web page into the current directory seva% chmod og+r index.html <-- Add read permission for group and other seva% ls -l index.html <-- Display 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 seva will serve you the page. Type the URL
http://seva.cs.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:
seva% cd seva% cd public_htmlOnce in the public_html directory, type
seva% mkdir p2docs <-- Make a directory named p2docs seva% cd p2docs <-- Descend into the directory p2docs seva% cp ~/p2/html/* ./ <-- Copy the contents of p2/html to the current directory seva% chmod og+r * <-- Add read permission to group and other for all files seva% cd .. <-- Move up to the directory public_html seva% chmod og+rx p2docs <-- Add read and execute permissions for group and 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:
seva% cd <-- Takes you to your home directory seva% chmod -R og-rx public_html <-- Recursively removes read and execute privilege for group and other for public_html and all thereinIf you want to completely remove these directories and files, type the rather dangerous command:
seva% cd <-- Takes you to your home directory seva% rm -r public_html <-- Recursively removes public_html and all therein
My documentation: P2 Documentation.
A transcript of my session follows:
seva% echo $SHELL /bin/tcsh seva% echo "umask 077" >> ~/.cshrc seva% logout Log back in... seva% touch test seva% ls -l test -rw------- 1 maloofm maloofm 0 Feb 9 16:07 test seva% rm test seva% cd seva% cd .. seva% ls -l | grep maloofm drwxr-xr-x 20 maloofm maloofm 4096 Feb 9 16:07 maloofm/ seva% chmod -R og-rwx maloofm seva% cd seva% ls -l total 24 drwx------ 2 maloofm maloofm 4096 Dec 15 18:11 cosc071/ drwx------ 2 maloofm maloofm 4096 Jan 14 15:28 hw1/ drwx------ 2 maloofm maloofm 4096 Jan 22 20:04 p1/ drwx------ 2 maloofm maloofm 4096 Feb 9 08:45 p2/ -rw------- 1 maloofm maloofm 6183 Jan 14 10:29 submit.jar seva% cd .. seva% chmod og+rx maloofm seva% ls -l | grep maloofm drwxr-xr-x 19 maloofm maloofm 4096 Feb 9 16:09 maloofm/ seva% cd seva% mkdir public_html seva% chmod og+rx public_html seva% cd public_html seva% cp ~maloofm/cosc072/index.html ./ seva% ls -l index.html -rw------- 1 maloofm maloofm 103 Feb 9 16:11 index.html seva% chmod og+r index.html seva% ls -l index.html -rw-r--r-- 1 maloofm maloofm 103 Feb 9 16:11 index.html seva% pwd /home/maloofm/public_html seva% mkdir p2docs seva% ls index.html p2docs/ seva% cd p2docs seva% cp ~/p2/html/* ./ seva% ls annotated.html classPastas-members.html functions_func.html classFlat.html classRound.html functions.html classFlat-members.html classRound-members.html hierarchy.html classFlat.png classRound.png index.html classPasta.html doxygen.css main_8h-source.html classPasta-members.html doxygen.png pasta_8h-source.html classPasta.png files.html pastas_8h-source.html classPastas.html flat_8h-source.html round_8h-source.html seva% chmod og+r * seva% cd .. seva% chmod og+rx p2docs seva%