nitlog/README

   1                                                                 Nov 10, 2004
   2                                                 Dave Coombs <dcoombs@nit.ca>
   3
   4
   5 --------
   6 Preamble
   7 --------
   8
   9 NITLog is a weblog system written in PHP, designed to be relatively simple
  10 and to stay out of your way.  Or, more accurately, to stay out of *my* way.
  11
  12 You write entries in text files, you can mark them up with whatever HTML
  13 you want, and there are a few additional useful formatting commands for
  14 including images and bulleted lists.  The layout of your page is completely
  15 customizable.  All of this is described below.
  16
  17 Entries are organized and viewed by month.  The current (or most recent)
  18 month is displayed upside-down, with the newest entries at the top.  All
  19 older months are displayed the other way, chronologically.
  20
  21 If NITLog doesn't do something you want it to do, it could be because I
  22 never thought of it or was too lazy.  Please feel free to let me know what
  23 you'd like to see.  Better yet, please feel doubly free to do some hacking
  24 yourself and send me a patch.
  25
  26 NITLog is freely available under the GPL.  Please see the enclosed LICENSE
  27 file.
  28
  29
  30 ---------------------
  31 Configuration Options
  32 ---------------------
  33
  34 The following options in config.ini.php are available:
  35
  36     required:
  37         $name        -- the title of your site
  38         $layout      -- the HTML layout file to crunch and fill with content
  39         $topdir      -- the directory we're installed in (eg: "nitlog")
  40
  41     optional:
  42         $username    -- your username, optional
  43         $email       -- email address for site administrator, optional
  44         $logfile     -- log page requests to this file, optional
  45         $rsslink     -- true if you want to offer an RSS feed
  46         $absoluteurl -- used for translating relative paths in RSS feed
  47
  48
  49 ----------------
  50 Directory Layout
  51 ----------------
  52
  53 Install NITLog as described in the INSTALL file, beginning, if you like,
  54 with the included example.
  55
  56 Under the 'nitlog' directory, make a directory for each month that has
  57 entries.  November 2004 would be called '200411'.
  58
  59 Inside a month directory, write your entries in files with two-digit
  60 numeric names corresponding to the day of the month.
  61
  62
  63 ----------------
  64 Entry Formatting
  65 ----------------
  66
  67 Any HTML is allowed, and will be passed through unharmed.  Additionally,
  68 NITLog automatically performs the following actions on your text:
  69
  70     - A blank line is replaced with <p>, so you don't need to explicitly
  71       separate paragraphs with HTML yourself.
  72
  73     - Lines beginning with a minus sign and a space ("- ") will be turned
  74       into a bulleted list.  You can put blank lines between consecutive
  75       bulleted lines.  NITLog is not yet smart enough to deal with indented
  76       lists, so don't even try.
  77
  78     - Lines of the form:
  79
  80             image 1234 This is an image.
  81
  82       will insert an image into your text.  NITLog expects to find two
  83       files, "img_1234_sm.jpg" and "img_1234_lg.jpg", corresponding to
  84       small and large versions of the image, in the same directory as the
  85       article text.  The small version will be displayed inline, centred,
  86       with the given caption underneath.  The image is itself a clickable
  87       link to the larger version.
  88
  89     - Lines of the form:
  90
  91             pngimage 1234 This is an image.
  92
  93       work just like the above, but look for png files instead of jpg.
  94
  95     - Lines of the form:
  96
  97             thumb 1234 This is an image.
  98
  99       will insert a thumbnail image into your text.  NITLog expects to find
 100       a thumbnail image named "img_1234_th.jpg" in the same directory as
 101       the article text.
 102
 103       Clicking the thumbnail will invoke img.php, and allow the user to see
 104       the caption and view the image in different sizes.  If you have
 105       "img_1234_sm.jpg", "img_1234_lg.jpg", and "img_1234.jpg", they will
 106       be treated as small, large, and huge, respectively.
 107
 108       Don't put a blank line between consecutive "thumb" lines.
 109
 110
 111 ----------------
 112 A Note About RSS
 113 ----------------
 114
 115 rss.php will parse the same entries as index.php, and it will give you an
 116 XML RSS feed in return.
 117
 118 It is important to note that when you are linking to other parts of your
 119 nitlog, you want to do it with a relative path involving . or .. or with an
 120 absolute URL.  The escape() function in rss.php translates . and .. into an
 121 absolute URL.  This is necessary because when someone reads your RSS feed
 122 on another site, the relative paths won't otherwise work.  Thus, linking to
 123 yourself:
 124
 125     href="http://foo.com/nitlog/?m=200411#05"       OK
 126     href="../nitlog/?m=200411#05"                   OK
 127     href="./?m=200411#05"                           OK
 128
 129     href="?m=200411#05"                             BAD BAD BAD
 130     href="#05"                                      BAD BAD BAD
 131
 132 NITLog is not smart enough to translate the last two into an absolute URL.
 133 Don't do it.
 134
 135
 136 -----------
 137 Page Layout
 138 -----------
 139
 140 You will want to design your own layout template for NITLog.  This is done
 141 as a regular HTML file, with certain extra markup tags that are parsed by
 142 NITLog and replaced with content.
 143
 144 See example/layout.inc.html for a simple example, and
 145 fancy-example/dcoombs.inc.html for a fancier one.
 146
 147
 148 The following globally scoped tags are replaced by NITLog as appropriate:
 149
 150     <## title ##>
 151         the title of your site, as defined by $title in config.inc.php
 152
 153     <## email ##>
 154         the site administrator's email address, as defined by $email in
 155         config.inc.php
 156
 157     <## prevmonth ##>
 158     <## nextmonth ##>
 159     <## thismonth ##>
 160         a numeric representation of the previous, next, and current months,
 161         for linking purposes.  For example, November 2004 is "200411".  Link
 162         to this month with "http://whatever/nitlog/?m=200411".
 163
 164     <## prev ##>
 165     <## next ##>
 166     <## this ##>
 167         a textual representation of the previous, next, and current months
 168
 169     <## prevabbr ##>
 170     <## nextabbr ##>
 171         an abbreviated textual representation of the previous and next months
 172
 173     <## rsslink ##>
 174         a link to rss.php, constructed from $absoluteurl and $topdir in
 175         config.inc.php
 176
 177
 178 The following control structures must be on separate lines, and behave as
 179 described:
 180
 181     ### ifemail
 182         stuff passed through only if $email is defined
 183     ### endif
 184
 185
 186     ### ifprev
 187         stuff passed through only if an earlier month exists
 188     ### endif
 189
 190
 191     ### ifnext
 192         stuff passed through only if a future month exists
 193     ### endif
 194
 195
 196     ### ifprevnext
 197         stuff passed through only if an earlier *OR* a future month exists
 198     ### endif
 199
 200
 201     ### ifrss
 202         stuff passed through only if $rss is true
 203     ### endif
 204
 205
 206     ### loopentries
 207         stuff that is repeatedly passed through once for each entry
 208         in the month
 209     ### endloopentries
 210
 211
 212 The following tags are available only inside the "loopentries" structure,
 213 and correspond to information about the current entry in the iterator:
 214
 215     <## entrytitle ##>
 216         the title of the entry, which is currently always the publication
 217         date
 218
 219     <## entrytime ##>
 220         the date and time the entry was published, determined by the mtime
 221         of the entry file
 222
 223     <## entrylink ##>
 224         a relative link to the current entry.  requires "entryanchor"
 225
 226     <## entryanchor ##>
 227         a name for an anchor for the current entry, so that "entrylink"
 228         will actually work
 229
 230
 231 The following control structures are available only inside the
 232 "loopentries" structure, must be on separate lines, and behave as
 233 described:
 234
 235     ### ifentrytitle
 236         stuff passed through only if the current entry has a title.  If the
 237         two-digit date is "00", this is false.
 238     ### endif
 239
 240
 241     ### entrycontent
 242         this line is replaced by the text of the entry
 243
 244
 245 ---------
 246 Postamble
 247 ---------
 248
 249 Please join me in banning the word "blog" from the English language.  And
 250 from all other languages, while we're at it.  Thank you for your support.
 251