COSC 072 Homework 1

COSC 072: Computer Science II

Homework 2 (Optional)
Spring 2008

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.

You can download doxygen and install it on your own computer. The directions below are for seva.

Running doxygen on seva

Log on to seva and navigate into the directory containing your project's source code. Mine is in the directory $HOME/p1, which is what I will assume. ($HOME is a variable that stores the path of your home directory.) 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 p1 in PDF. Use secure ftp to transfer that file to your desktop or laptop and use Adobe Reader to view it.

The following is a transcript of my session. Bold type denotes commands I typed.

seva% cd p1
seva% ls
cat.cc  dog.cc  main.cc  Makefile  pet.h    pets.h
cat.h   dog.h   main.h   pet.cc    pets.cc
seva% doxygen *.h *.cc
Searching for include files...
Searching for example files...
...
Generating page index...
Generating graph info page...
seva% ls
cat.cc  dog.cc  html/   main.cc  Makefile  pet.h    pets.h
cat.h   dog.h   latex/  main.h   pet.cc    pets.cc
seva% cd latex
seva% ls
annotated.tex  classDog.eps  classPets.tex  Helvetica.ttf  refman.tex
classCat.eps   classDog.tex  classPet.tex   hierarchy.tex
classCat.tex   classPet.eps  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  classDog.tex   classPet.tex   refman.aux  refman.log
classCat.eps   classPet.aux   doxygen.sty    refman.dvi  refman.tex
classCat.tex   classPet.eps   Helvetica.ttf  refman.idx  refman.toc
classDog.aux   classPets.aux  hierarchy.tex  refman.ilg
classDog.eps   classPets.tex  Makefile       refman.ind
seva% dvipdf refman
seva% ls
annotated.tex  classDog.tex   classPet.tex   refman.aux  refman.log
classCat.eps   classPet.aux   doxygen.sty    refman.dvi  refman.tex
classCat.tex   classPet.eps   Helvetica.ttf  refman.idx  refman.toc
classDog.aux   classPets.aux  hierarchy.tex  refman.ilg
classDog.eps   classPets.tex  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. You account may already be configured properly. To see, type:

seva% touch test
seva% ls -l test
-rw-------  1 <your-netid> <your-netid> 0 Feb  9 14:57 test

If the string in the left column is not "-rw-------", then set the umask; otherwise, skip this step.

Setting the umask

I won't explain the details of this command here, but it sets the default privileges for new files:

seva% umask 077

You want to set the umask each time you log in, so 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.

Setting user priviledges

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.

Creating Web directories

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 "P1 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 p1 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 p1docs                             <-- Make a directory named p1docs
seva% cd p1docs                                <-- Descend into the directory p1docs
seva% cp ~/p1/html/* ./                        <-- Copy the contents of p1/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 p1docs                       <-- Add read and execute permissions for group and other for the directory p1docs

Assuming that your documentation is in the directory $HOME/p1/html, you should be able to use your browser to click the link to "P1 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: P1 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 p1docs
seva% ls
index.html  p1docs/
seva% cd p1docs
seva% cp ~/p1/html/* ./
seva% ls
annotated.html         classPet.html           files.html
cat_8h-source.html     classPet-members.html   functions_func.html
classCat.html          classPet.png            functions.html
classCat-members.html  classPets.html          hierarchy.html
classCat.png           classPets-members.html  index.html
classDog.html          dog_8h-source.html      main_8h-source.html
classDog-members.html  doxygen.css             pet_8h-source.html
classDog.png           doxygen.png             pets_8h-source.html
seva% chmod og+r *
seva% cd ..
seva% chmod og+rx p1docs
seva%