head	1.7;
access;
symbols
	start:1.1.1.1 swish-e:1.1.1;
locks; strict;
comment	@# @;


1.7
date	2005.05.30.05.08.19;	author whmoseley;	state Exp;
branches;
next	1.6;

1.6
date	2005.02.02.23.55.11;	author whmoseley;	state Exp;
branches;
next	1.5;

1.5
date	2005.02.01.05.19.42;	author whmoseley;	state Exp;
branches;
next	1.4;

1.4
date	2005.01.20.15.06.01;	author whmoseley;	state Exp;
branches;
next	1.3;

1.3
date	2005.01.19.07.05.06;	author whmoseley;	state Exp;
branches;
next	1.2;

1.2
date	2005.01.18.21.06.40;	author whmoseley;	state Exp;
branches;
next	1.1;

1.1
date	2005.01.18.20.32.47;	author whmoseley;	state Exp;
branches
	1.1.1.1;
next	;

1.1.1.1
date	2005.01.18.20.32.47;	author whmoseley;	state Exp;
branches;
next	;


desc
@@


1.7
log
@
A few updates to handle the new doc build system
@
text
@Mon Jan 17 07:32:40 PST 2005

$id$

Swish-e site.

This site is maintained in CVS.  Pages should not be modified directly.
Check out the site from cvs, and modify the pages locally.  Rebuild locally
to review and then check in.



Site layout
-----------

    ./
        -> src              - web source docs.
        -> public_html      - output files.  This is DocumentRoot
            distribution        - symlink to the swish-releases tarball directory[1]
            swish-daily         - symlink to swish-daily tarball directory
        -> bin              - bin/build script and other utilities
        -> lib/config       - site config templates.
        -> lib/config/site  - contains swish-e current version (see TODO)
        -> lib/config/map   - defines layout of site and site's menu
        -> lib/page         - templates that define the look of each page
        -> lib/pod_toc      - top-level index for pod docs

[1] these two (three including the "old" dir) directories are read when
building the index listings for the downloads, plus they must be avaiable via
the /distribution and /swish-daily URLs.  Originally, these were outside of
document root (public_html) in dirs_public and accesed with Alias in
httpd.conf.  And lib/config/site set their locations for generating the
index.html pages listing the files.


Building the site
-----------------

    Check out the "swish_website" project from CVS.  Once checked out you need to
    initialize a few directories, and then build the site.

        $ cd swish_website
        $ mkdir -p public_html dirs_public/download/old dirs_public/swish-daily
        $ bin/build -swishsrc=$HOME/swish-e -develsrc=$HOME/swish-e -archive=archive/index.swish-e

    (Or symlink as needed -- which is what I did.)

    Also in lib/config/site you might want to defined where swish-daily and
    the download dirs are set.  Currently to /distribution and /swish-daily.
    The download and swish-daily pages link files to those dirs.

    You need Template Toolkit, Pod::POM (from CPAN) and anything else it
    complains about.

    Those output directoreis can be overridden.  see bin/build --help  for
    help.  "dirs_public" can be set in lib/conifg/site.

    From the top-level directory* (where this README file is located)
    run:

        bin/build -all -swishsrc=$HOME/swish-e -v

    (assuming that's where the swish-e source is located)

    That builds both the website and the pod docs and writes them
    to the "public_html" directory.

    * Actually, from anywhere -- directories are determined relative to
    where the /bin/build program is found.

    Running without the -all switch will cause only the changed files to be
    rebuilt.  Normally you run with -all.

    Note: the docs/index.html file can only be correctly built if ALL the pods
    are processed (using -all).  So do not rm public_html/docs/index.html and expect
    it to be rebuilt automatically.

    For a bit more info, run:

        bin/build -help


    Note: if speedy (speedyCGI) is installed and in the path at build time the
    the search script will run that instead of perl.


Download and swish-daily directories
------------------------------------

These directory listings are *static* pages.  If a new file is added
to one of these directories you need to touch the source file or rebuild
all pages:

    $ touch src/download/index.html && bin/build -v
or
    $ bin/build -all -v



Building the html docs for distribution
---------------------------------------

    Specify the pod destination directory:

        bin/build -all -swishsrc=$HOME/swish-e -poddest=$HOME/swish-e/html

    This adjusts the links so that every non-pod link points to the swish-e.org
    site; pod links are local.


Content Creation
----------------

Links:
    All internal pages can (and probably should) be defined in the 
    config/map file.  This is mostly for defining the menu, but entries
    can be marked "hidden".  Even off-site links can be entered (look for link to CVS)

    Entries in the config/map file can then be linked
    to using a macro:

     Check out the [% link_to_page('readme#Key features', 'full list of features') %].

    That will find the (first) menu item that has "readme" for an id
    and create a complete <a>..</a> tag.  notice that it's possible to use
    fragments.

    The macro has at least three parameters:
        1) the menu id to search for
        2) optional text to use for the link -- otherwise the menu text is used
        3) flag to say just return the href part of the link


    TODO:
        add MACROS for page sections and the abilty to create a TOC at the top of the
        page.



Indexing the site for searches
------------------------------

To index the site run from the top level directory:

    $ SWISH_SITE=http://swish-e.org swish-e -c etc/swish.config -S prog

SWISH_SITE is the top level URL.
START_FILE is the starting file.  Default is index.html
(SWISH_SITE=http://swish-e.org/docs START_FILE=readme.html to index just one file)

That writes the index to public_html/search/

Or to run it quiet:

$ SPIDER_QUIET=1 SWISH_SITE=http://localhost/apache/public_html \
    swish-e -c etc/swish.config -S prog -v0

Capture output (for debugging) like this:

  $ SWISH_SITE=http://localhost/apache/public_html \
        /usr/local/lib/swish-e/spider.pl etc/spider.config > out



todo: add metaname selection and create build script that is built from


TODO
----

- add 404 and 500 pages (should they be cgi scripts to show the probled
path, or can people figure that out on their own?

- Have title be part of the layout (instead of added on each page)?


- [done] Fetch version from -swishsrc/configure instead of hard-coded in config/site

- Split out some of the lib/page templates into smaller components that can be
overridden separately.

- add to META on each page [author = '$Author: whmoseley $'] and maybe also $Date: 2005/02/02 23:55:11 $, although
lastmod is probably fine.  Waiting until can think of a better way to do the same
for the pod files.

- [done] test speedycgi and install on sunsite

- [done - not really needed under speedy ] enable template caching for the search script

- [done] Probably should filter all hrefs= and name= through |uri|html.  Plus some
are very large.  Maybe shorten or md5 them?  If so, then need to adjust link_to_page().
[Well, partially done.  Pod::POM prevents access to the #fragment so there's spaces in hrefs
which is ok, I suppose but other chars could mess things up.]

- [done - just rebuld, doesn't take any time] 
  Try (again) to find a way to detect when a cvs update doesn't really update any files.

- [done - see above]Add disk cache for table of contents for each POD page so index.html can be
regenerated without having to parse all pods.  Not that parsing a small handfull of
pods is a big deal....

- [done] add timezone to dates and make UTC.

- Set fixed pitch font for timestamp on file listings.  Currently ugly.
@


1.6
log
@*** empty log message ***
@
text
@d19 2
a20 1
        -> dirs_public      - download, archive, and swish-daily dirs
d28 6
d182 1
a182 1
- add to META on each page [author = '$Author: whmoseley $'] and maybe also $Date: 2005/02/01 05:19:42 $, although
@


1.5
log
@A few more updates to source files
@
text
@d37 1
a37 1
        $ bin/build -swishsrc=$HOME/swish-e -develsrc=$HOME/swish-e
d170 1
a170 1
- Fetch version from -swishsrc/configure instead of hard-coded in config/site
d175 1
a175 1
- add to META on each page [author = '$Author: whmoseley $'] and maybe also $Date: 2005/01/20 15:06:01 $, although
d179 1
a179 1
- test speedycgi and install on sunsite
d181 1
a181 1
- enable template caching for the search script
d183 1
a183 1
- Probably should filter all hrefs= and name= through |uri|html.  Plus some
d185 2
d188 2
a189 1
- Try (again) to find a way to detect when a cvs update doesn't really update any files.
d191 1
a191 1
- Add disk cache for table of contents for each POD page so index.html can be
d195 3
a197 1
- add timezone to dates and make UTC.
@


1.4
log
@
Enable speedycgi and update footer
@
text
@d39 6
d175 1
a175 1
- add to META on each page [author = '$Author: whmoseley $'] and maybe also $Date: 2005/01/19 07:05:06 $, although
@


1.3
log
@
Add inital code for indexing site and docs.

Meta name "section" is used to limit to a section.  Search for "defaultcontents"

   defaultcontents section=docs
   defaultcontents section=devel  ( only devel docs)
   defaultcontents section=website ( only web site pages, excluding docs and devel_docs )
@
text
@d70 15
d158 2
a159 1
- add 404 and 500 pages
d169 1
a169 1
- add to META on each page [author = '$Author: whmoseley $'] and maybe also $Date: 2005/01/18 21:06:40 $, although
d180 1
d182 3
d186 1
@


1.2
log
@Add and ignore file for the destination dirs
@
text
@d115 23
a137 1
[todo]
d153 1
a153 1
- add to META on each page [author = '$Author: whmoseley $'] and maybe also $Date: 2005/01/18 20:32:47 $, although
d161 3
@


1.1
log
@Initial revision
@
text
@d11 2
d32 13
d131 1
a131 1
- add to META on each page [author = '$Author$'] and maybe also $Date$, although
@


1.1.1.1
log
@Initial import
@
text
@@
