COSC-052: Computer Science II

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:

Running doxygen

Log on to cs-class 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
cs-class% cd p2
cs-class% 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 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.

Generating PDF Documentation

To generate a PDF file from the documentation in LaTeX, change into the latex directory and list its contents:
cs-class% cd latex
cs-class% 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. 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%

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 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 other
To 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.html
Next, 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_html
Once 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 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:

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 therein
If 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.