This directory contains various utilities helpful in creating the HWN.

It is generally useful to create symlinks to these utilities in the
main hwn directory.

The utilities
-------------

gmane:

  Start from the command line by passing it one of the options
  'Haskell', 'Cafe', 'Libraries', 'Prime', or 'GHC' to look at
  haskell@, haskell-cafe@, libraries@, haskell-prime@, and ghc-users@
  respectively.  It will pull down thread subjects from GMane and
  allow you to select those threads which you wish to include in the
  HWN.  Type '?' at the prompt for a list of supported commands.  A
  typical workflow is to hit 'n' repeatedly for threads you don't want
  to include, and for threads you do want to include, hit 'a' (to list
  it under the 'Announcements' section, or 'z' (to list it under the
  'Discussions' section), then 'T' to auto-select the title from the
  subject (stripping any leading ANN: or ANNOUNCE: or similar), then
  'u' to open up your favorite editor to compose a paragraph
  summarizing the thread. The editor will start with the contents of
  the message, so usually you can just cut and paste portions of the
  message to create the summary, although it is often necessary to add
  some additional inline links (using the [http://blah.blah/ text]
  format).  Once you are done preparing an item for inclusion, ty[e
  'j' to move to the next item.  You can always type 'k' to go
  backwards through the list and change/edit previous items.

planethaskell:

  Takes no arguments.  Pulls blog titles from the planet haskell feed
  from which you can select.  Type '?' to see the available options.
  A typical workflow is to type 'y' for posts you do want to include
  ('n' for ones you don't), then 'A' to automatically parse the
  author's name from the title (which is often in the form "Author:
  Title"), or 'a' and 't' to enter the author/title manually; then 'j'
  to move to the next item.  You can also use 'u' to edit a summary of
  the post if desired---especially useful for posts with opaque titles.

  One pitfall is that the Planet Haskell RSS feed only retains a
  certain number of items---so if you wait too long between uses of
  the planethaskell tool you will miss some posts.  One solution is to
  subscribe to Planet Haskell in the RSS aggregator of your choice;
  then even if some of the posts since the last HWN have fallen off
  the end of the PH RSS feed, you can still recover links to them from
  your RSS reader's history.  Of course, this requires more manual
  work so is best avoided!  Usually a week's worth of posts will all
  fit within Planet Haskell's RSS history length, but two weeks of
  posts almost certainly will not.

  One thing to be aware of is that there are many interesting
  Haskell-related blog posts which are not syndicated on Planet
  Haskell.  A useful place to find these is on the Haskell Reddit;
  however, pulling blog posts from reddit is not (yet) automated.

quotes:

  Takes no arguments; pulls quotes from the #haskell IRC channel.  It
  works by grepping through the IRC logs for occurrences of the string
  @remember, so sometimes it finds extraneous things (such as people
  talking *about* the @remember command) and it also has no conception
  of whether a quote has already been encountered before.  Obviously,
  it also won't find quotes that were funny but happened not to be
  @remembered.

publish:
  
  This utility should be called from the main hwn directory, and
  handles actually generating the HWN in various formats (text,
  html...) from content.wiki.  When called with no arguments it simply
  builds the various HWN formats and dumps them in the same directory.
  When called with -p it does the following:

    * Builds the HWN (including spell-checking) and puts it in
      archives/yyyymmdd.*
    * Replaces content.wiki with content.pristine
    * Increments the issue number contained in the file 'issue'

totext.sh: turns generated HTML into a text version (for sending to
  the mailing list, etc.).  Doesn't need to be built, just make sure
  it has its executable bit set.

Building
--------

To build a bunch of the utilities all at once, type 'make all'.  You
can also type 'make foo' where foo is one of
{publish,gmane,planethaskell,quotes} to make an individual utility.

Before building, make sure you have the...

Dependencies
------------

  Haskell packages:
    feed
    zipedit
    tagsoup
    urlcheck

  External utilities (install through your OS package manager):

    validate  (in debian/ubuntu, install package 'wdg-html-validator')
    lynx