COSC-072: Computer Science II

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.

Running doxygen

Log on to seva and navigate into the directory containing your project's source code. Mine is in the directory $HOME/p2, which is what I will assume. To run doxygen on the source in the directory, type
seva% doxygen *.h *.cc
If 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.

Generating PDF Documentation

To generate a PDF file from the documentation in LaTeX, change into the latex directory and list its contents:
seva% cd latex
seva% ls
You'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 refman
If 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%

Publishing HTML Documentation

Publishing your documentation as a Web page is a little more involved because your account is not yet configured to display Web pages. The tricky thing is you have to change the permissions of the directories in your account so the Web server (and other people) can access the files for your Web site, but none of your other files. If you feel the least bit uncomfortable about this, please stop by and I'll help you.

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 077
Since 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 $SHELL
If echo reports '/bin/tcsh', then you're using the T-C-shell, and you should type:
seva% touch ~/.cshrc
seva% echo "umask 077" >> ~/.cshrc
If 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_profile
These 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 test
If 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.jar
For 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 other
To 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.html
Next, 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_html
Once 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 p2docs
Assuming 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 therein
If 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%