README.newbie

   1 Course Web-admin,
   2
   3 This is the framework I used for the Phys201 course in the winter of
   4 2008-2009, and I think it works pretty well.  The workflow is,
   5 however, a bit different than anything I've found elsewhere, so I'll
   6 explain how it works for me below.  Feel free to email me with any
   7 questions or problems.
   8
   9 ~/src/
  10 ======
  11
  12 The source for the website (and a bunch of LaTeX problems/solutions
  13 I've written up over the last few years as a TA), are all over in
  14 ~/src/, and in my own work I make all my changes there and then run
  15 "make" in the ~/src/ directory to push the changes to ~/public_html,
  16 which is the actively served directory.  This is mostly to allow
  17 automatic compiling and installation of my LaTeX solutions.  You can
  18 look around in ~/src/ if you like, but if it's too confusing, I
  19 suggest you stick to handling ~/public_html directory.
  20
  21 ~/public_html/ and overview
  22 ===========================
  23
  24 ~/public_html/ contains assorted *.shtml files, each of which
  25 corresponds to one of the course pages.  They all use Server Side
  26 Includes (SSI) to include headers and footers stored in
  27   ~/public_html/shared/
  28 which take care of a lot of HTML boilerplate.  If you want to add
  29 content to any of the pages, just hack away on the appropriate *.shtml
  30 file (for example, see labs.shtml).  You'll definitely want to flesh
  31 out the content in index.shtml (the main page) with appropriate course
  32 details.
  33
  34 Inside many of the *.shtml files are <?php ?> tags.  These tags use
  35 PHP to include all the site's dynamic content.  I suggest you leave
  36 them alone.  You won't have to worry about the PHP code itself, but
  37 you will have to supply those scripts with content to parse.  This
  38 content lives in ~/public_html/xml/ and ~/public_html/doc.
  39
  40 ~/public_html/xml/
  41 ==================
  42
  43 profs.xml, TAs.xml, and course.xml are pretty clear.  Just fill in the
  44 XML as appropriate for the course.  webmaster.xml is even easier,
  45 since you don't have to look up your own information.
  46
  47 atom.xml is an atom feed (which is also parsed by atom.php to fill in
  48 the announcements page).  I wrote a command line atom feed generator
  49 "atomgen", which I've installed for you.  Run
  50   atomgen --help
  51 and
  52   atomgen add --help
  53 to see information about how to add to the atom.xml I've already
  54 created.  For example, to add a comment saying you'd posted the
  55 first set of homework solutions, you might run
  56   echo "Homework 1 solutions posted.  Hope you didn't have too much trouble." | \
  57     atomgen -o ~/public_html/xml/atom.xml add -i ~/public_html/atom.xml \
  58     "Homework 1 solutions posted." \
  59     "http://www.physics.drexel.edu/~phys201admin/homeworks.shtml#s1"
  60 where we use echo and the pipe (|) to pass the content for the post in
  61 via atomgen's stdin.
  62
  63 ~/public_html/doc/
  64 ==================
  65
  66 Each of the *.shtml pages except index.shtml, content.shtml, and
  67 announcements.shtml (whose content we've already discussed) has a call
  68 to printSectionDocs() in its PHP.  This call links in data from the
  69 ~/public_html/doc/.  The syntax is
  70   printSectionDocs($title, $directory, $startswith, $maxnum);
  71 for example
  72   printSectionDocs('Lecture', 'doc/lec', 'lec', 20);
  73 which searches through $directory (doc/lec) for any files of the form
  74 $startswith$index_* (lec5_slides.pdf) and links to them, calling them
  75 * (slides.pdf).  $maxnum makes it easy for printSectionDocs() to
  76 reference the files newest-to-oldest, finding files with
  77 0 < $index <= $maxnum.  $title sets the headings of the per-index
  78 blurbs.
  79
  80 To make the system work, you just drop your content into (for example)
  81   ~/public_html/doc/lec/
  82 with appropriate file names, and links show up on lectures.shtml
  83 automatically.  Because of the automatic linking, make sure you it's
  84 OK to post the information (e.g. exam solutions) BEFORE you place them
  85 in the doc/ tree.
  86
  87 To keep everything organized, I've also added doc/note to store things
  88 like a course syllabus.pdf, and write the link by hand in index.html's
  89 list of course resources.
  90
  91 In the past, I've used
  92   doc/lec/ for lecture notes/slides.
  93   doc/rec/ for recitation problems and solutions.
  94   doc/lab/ for lab procedures and prelabs.
  95   doc/hwk/ for homework problems and solutions.
  96   doc/exams/ for exam solutions.
  97 but it should be pretty clear what to change if you want to fiddle
  98 with that layout.
  99
 100 style
 101 =====
 102
 103 I haven't spent much time making everything look all pretty, so
 104 there's surely room for improvement if you like playing with CSS.
 105
 106
 107 And that's it!
 108
 109 Good luck,
 110 Trevor
 111
 112
 113 p.s. don't worry about what's in ~/bin/ or ~/lib/ unless you want to.
 114 They're there so you have atomgen and it works, but are not important
 115 for website maintenance.