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"
  50 (http://www.physics.drexel.edu/~wking/unfolding-disasters/posts/Atomgen/),
  51 which I've installed for you.  Run
  52   atomgen --help
  53 and
  54   atomgen add --help
  55 to see information about how to add to the atom.xml I've already
  56 created.  For example, to add a comment saying you'd posted the
  57 first set of homework solutions, you might run
  58   echo "Homework 1 solutions posted.  Hope you didn't have too much trouble." | \
  59     atomgen -o ~/public_html/xml/atom.xml add -i ~/public_html/atom.xml \
  60     "Homework 1 solutions posted." \
  61     "http://www.physics.drexel.edu/~phys201admin/homeworks.shtml#s1"
  62 where we use echo and the pipe (|) to pass the content for the post in
  63 via atomgen's stdin.
  64
  65 ~/public_html/doc/
  66 ==================
  67
  68 Each of the *.shtml pages except index.shtml, content.shtml, and
  69 announcements.shtml (whose content we've already discussed) has a call
  70 to printSectionDocs() in its PHP.  This call links in data from the
  71 ~/public_html/doc/.  The syntax is
  72   printSectionDocs($title, $directory, $startswith, $maxnum);
  73 for example
  74   printSectionDocs('Lecture', 'doc/lec', 'lec', 20);
  75 which searches through $directory (doc/lec) for any files of the form
  76 $startswith$index_* (lec5_slides.pdf) and links to them, calling them
  77 * (slides.pdf).  $maxnum makes it easy for printSectionDocs() to
  78 reference the files newest-to-oldest, finding files with
  79 0 < $index <= $maxnum.  $title sets the headings of the per-index
  80 blurbs.
  81
  82 To make the system work, you just drop your content into (for example)
  83   ~/public_html/doc/lec/
  84 with appropriate file names, and links show up on lectures.shtml
  85 automatically.  Because of the automatic linking, make sure you it's
  86 OK to post the information (e.g. exam solutions) BEFORE you place them
  87 in the doc/ tree.
  88
  89 To keep everything organized, I've also added doc/note to store things
  90 like a course syllabus.pdf, and write the link by hand in index.html's
  91 list of course resources.
  92
  93 In the past, I've used
  94   doc/lec/ for lecture notes/slides.
  95   doc/rec/ for recitation problems and solutions.
  96   doc/lab/ for lab procedures and prelabs.
  97   doc/hwk/ for homework problems and solutions.
  98   doc/exams/ for exam solutions.
  99 but it should be pretty clear what to change if you want to fiddle
 100 with that layout.
 101
 102 style
 103 =====
 104
 105 I haven't spent much time making everything look all pretty, so
 106 there's surely room for improvement if you like playing with CSS.
 107
 108
 109 And that's it!
 110
 111 Good luck,
 112 Trevor
 113
 114
 115 p.s. don't worry about what's in ~/bin/ or ~/lib/ unless you want to.
 116 They're there so you have atomgen and it works, but are not important
 117 for website maintenance.