This document has been out-dated and replaced. See the scoop_admin_guide/ directory for the newer version.
Note: This documentation is incomplete, and may be somewhat inaccurate and/or outdated. If you don't know any perl, but want to help out with the project, and have a grasp of how it works, *please* consider updating this document! The developers will love you for it!Table of Contents:
Scoop is a web application designed to make it easy to run your own weblog. A weblog, defined loosely, is a website that posts news, or articles, or even just a personal diary-type thing, and is updated on a fairly regular basis. Many weblogs seek to provide a kind of online community, and allow readers to post comments of their own, and participate in the site in other ways. Scoop attempts to make it pretty easy to run a site that does these things.
Anyone! You can use it, certainly. Scoop will be useful, I think, for people who want to run a weblog, and who don't necessarily feel like programming their own, or tangling with some of the other systems out there, some of which can to be very complicated. Just for fairnesses sake, you have some options in your choice. Other systems that provide similar functionality as Scoop include:
If you're running a very high-traffic site, you probably shouldn't use Scoop. And by very high traffic, I mean hundreds or thousands of hits per minute. Scoop doesn't do any static page caching, and is not particularly concerned about using your system resources. For high-volume sites, I'd recommend Slash, since it's had long testing in such an environment.
Now, I don't want to scare anyone away, mind you. Scoop will not suck up 100% of your processor and bleed memeory all over your server room. I run both of my scoop sites from my own machines, both of which I use as workstations on a daily basis, and I've had no trouble whatsoever handling on the order of hundreds of hits per day. But generally, scoop is in the early release stage, and was not written for maximum efficiency. It will be undergoing a rewrite very soon, and you can expect to see it get leaner and more efficient as time goes on.
Scoop is released to you under the terms of the GNU General Public License. You will find a copy of this license in the file LICENSE, in the main scoop directory. If you're using free software, you should read the GPL at least once, so go ahead and read it. For more info on free software, look at http://www.opensource.org.
The instructions for installing Scoop are located in the file INSTALL, in the top-level Scoop directory. Please look there for the latest directions. If you're reading this from somewhere other than your own unpacked tarball (or CVS checkout), the general gist of the install is this:
The look and feel of your Scoop site can be almost entirely configured through the web interface of Scoop itself, using these things called Vars and Blocks. Simply put, Vars are small bits of text, some of which will get plugged in to the html around the site, and some of which control things like how many stories to display on the main page, etc. Blocks are larger chunks of text that create some of the bigger pieces of the scoop output. Blocks can include vars, as will be explained below. A complete list of important vars and blocks is also contained in these docs, and I recommend you look up what they are before you edit them. One other thing, Vars and Blocks are case sensitive. Meaning that "CONTENT" is a different var than "content". Got that? It's important!
When you log in to your scoop site as an administrator (i.e. a user with seclev >= 1000), you will get a bunch of options that normal users don't get. Many of the scoop configuration tools will be linked in a box called "Admin Tools." Normal users will only see "Story Moderation" in here, but you get some other options. One of them is "Vars/Blocks." Click on this, and you'll go to a screen with editing fields for all of your vars and blocks. Choose from one of the drop-down lists, click on "Get," and you have the current values for that var or block. Edit the value, and click "Write" and your changes are saved. The changes should take effect on the site immediately. There's no need to restart Apache. To create new blocks or vars, just make sure the drop-down is set to "Add New (whatever)." That's really all there is to it.
Vars are pretty simple. They each have one key, and one value. The value is restricted to 127 characters, as is the description. The Var name is restricted to 32 characters, and must not contain spaces. Vars are never interpolated, that is, you cannot embed Vars in other Vars and expect that to work.
d. Things to know about Blocks
Blocks are a little more complicated. Block names are restricted to 30
characters, and also must not contain spaces. Block values can be
as long as you need them to be. Additionally, you can embed Vars inside Blocks,
by including the var name inside pipes within the block value. For example, if I
had a var called 'font_color', whose value was '#000000', I could use it in a
block like this:
Additionally, some blocks can include things which are not Vars that you may edit, but are defined by the system when it builds certain pages. For example, the block 'comment' includes several variables, such as |subject|, |name|, |email|, and so on. These are not defined by you, but are created by the system when it uses these blocks. In the block list (elsewhere in this document), any blocks that can use special variables will include the name and purpose of each.
Name collision between special variables and normal Vars is possible, but only in a limited scope. Basically, you can name your Vars anything you want, but if, for example, you create one named 'name', you cannot use it within the block 'comment', because how is the system supposed to know which |name| is the system variable, and which is your Var? You see the problem. Generally, you probably won't need to create many Vars yourself, and if you do, pick a name that is likely to be unique, or check the list of special vars elsewhere in this document.
The following is a list of Vars that the system pretty much needs to function right, and what they each do. Please refer to this list when you're going to edit something, to make sure you know what you're doing. Some of them are named badly, and it's not obvious what they do. :-)
Purpose: This determines what the background color of a "box" should be. Boxes
are those things on the right side of the page, like "Login," "Older Stuff"
etc.
Value: The value of this should be a hex color, including the # sign.
Example: #EEEEEE
Purpose: The background color of the box titlebar.
Value: A hex color
Example: #006699
Purpose: The font to use when displaying box titles.
Value: A complete HTML opening <FONT> tag. If you want the titles to be
bold, also include an opening <B>.
Example: <FONT FACE="verdana, arial, helvetica, sans-serif" SIZE=2 COLOR="#FFFFFF"><B>
Purpose: The font to use when displaying "dep't" in stories.
Value: A complete HTML <FONT> tag. This will be bolded
automatically, no ned to include a <B>.
Example: <FONT FACE="arial, helvetica, sans-serif" SIZE=2>
Purpose: The total negative score required to hide a submitted story from
the users in "Story Moderation".
Value: Either a hard limit, like -10 (I recommend negative numbers for
this, since submitted stories start out at 0), or a percentage of registered
users, which would be, say, 5%. To use percentages, the value must be composed
only of digits followed by a single percent sign. If I chose 5%, then, and I had
500 users, the score needed to hide a story would be -25. It'll adjust on the
fly as new users are created, and if you have less than 100 users, the system
will pretend you have 100 users for the purposes of this score. So If I have 50
registered users, 5% will be translated into -5.
Example: -5 OR 5%
Purpose: The URL path of all your images.
Value: A path that will be prepended to image names in their <IMG>
tags. It should always include a leading '/', and never a trailing '/'. If the
images are not in a special directory, leave this blank. If the images are on
another server, put the full path to them here.
Example: /images, or something like http://images.kuro5hin.org
Purpose: The "From" address reported in emails sent to users (on new
account signup).
Value: This MUST be a valid address, and can be in a form that
includes your name as well, as in the example.
Example: Scoop <rusty@kuro5hin.org>
Purpose: The number of story summaries to display on the home page.
Value: An integer.
Example: 5
Purpose: The number of story titles to display in the "Older Stuff" box.
Note that these will be the x stories that are older than the ones
displayed in full summary form.
Value: An integer.
Example: 10
Purpose: This one's used all over the place. It's the <FONT> tag
that gets wrapped around most of the text on the site. All text that isn't
explicitly defined as something else will probably be displayed as this.
Value: A complete opening HTML <FONT> tag
Example: <FONT FACE="verdana, arial, helvetica, sans-serif" SIZE=2>
Purpose: BGCOLOR used in the "Story List" Admin section for stories that
are not being displayed yet.
Value: An HTML hex color
Example: #C0C0C0
Purpose: The total positive score a story must reach to be posted
automatically.
Value: May be an integer, or a percentage of users (see hide_story_threshold for more info about
percentages.
Example: 5 OR 5%
Purpose: How many icons to display in the "Recent News" box.
Value: An integer.
Example: 4
Purpose: The root URL path to use for all generated site links.
[Note: There may be cases where I've forgotten to include this in the
code, and your links will not be right. If you find a link that doesn't seem to
use this var, and needs to, please email me at rusty@kuro5hin.org and let me know!]
Value: The root URL path of your 'index.pl' file. Always include a
leading '/', never a trailing '/'. If your site is the only thing on a virtual host
(like scoop.kuro5hin.org), leave this blank.
Example: /scoop
Purpose: The name of your site, used in a few places around the
interface.
Value: Whatever. Just the name of your site.
Example: kuro5hin
Purpose: The "slogan" of your site. May be displayed in the header, or
the title. I change mine frequently.
Value: Some text. A funny quote, or a one-sentence mission statement.
Example: We're there when you need us.
Purpose: This number controls how many story titles to display at once in
the "Story List" admin page, and in the "Story Moderation" page.
Value: An integer.
Example: 15
Purpose: I think this is the bgcolor of the story moderation "vote"
controls. Tell you the truth, I'm not entirely sure though. Change it and see
what's a different color. :-)
Value: An HTML hex color value.
Example: #EEEEEE
Purpose: The background color of the little block at the bottom of a full
story display page, wthat has the links to the next and previous story.
Value: An HTML hex color value.
Example: #EEEEEE
Purpose: The bgcolor that designates a "submitted" story on the Admin
"Story List" page.
Value: An HTML hex color value.
Example: #c6dae4
Purpose: The background color of the story summary box, specifically the
part where the story introtext is displayed.
Value: An HTML hex color value.
Example: #FFFFFF
Purpose: The background color of page titles. Most noticably, the titles
of stories will have this bgcolor, but als the titles of admin pages, and some
other pages as well.
Value: An HTML hex color value.
Example: #FFFFFF
Purpose: The font to use when displaying Titles-- titles of stories,
titles of admin pages, etc.
Value: A complete HTML <FONT> tag. This will be made bold
automatically, so <B> is not needed.
Example: <FONT FACE="verdana, arial, helvetica, sans-serif" SIZE=4
COLOR="#006699">
Purpose: The path to use when looking for a "topic" image (the little
images that get displayed in story summary boxes). This is only the part after
the main imagedir
Value: A URL path. Always a leading '/', never a trailing '/'.
Example: topics/
Purpose: The bgcolor behind the "topic" image in the story summary box.
This is actually it's own table cell, so you can make it different from the rest
of the summary text bg if you want.
Value: An HTML hex color value.
Example: #FFFFFF
Purpose: In the admin "Story List" this is the row color designating
stories that are not being displayed (As in, their display mode is set to "Never
Display")
Value: An HTML hex color value.
Example: #c0c0c0
The following is a list of the system default blocks, roughly what they do, and what, if any, special vars they require (or can use). Examples will not be given, since many of them would be long, and all of them are in the default database anyway. For good examples, refer to your scoop site itself.
Purpose: This will appear on all the pages wherever you include it in index_template. The idea is that you'd put the code
to display a banner ad or whatever here.
Special Vars: None.
Purpose: This one's cool (and not in slash!). You know the "What's
Related" box that displays with every story? Well, that automatically parses
every HREF from the story itself, but it also searches for any word that you
put in here, and when it finds one, adds a link in "What's Related" consisting
of the word, and the URL you also provide. The format is "word,url" without
quotes, one per line. NO SPACES, and make sure your urls are full path. Add a
new one here, and it gets stuck in "Related" every time, without you ever having
to link it in the story.
Special Vars: None, and don't use normal Vars here either. It don't work
that way!
Purpose: This is the code that creates the standard "box." Should be
html, and, to work right, MUST contain the special vars below, somewhere. Each
box is separated by a <P>, so you should probably make this a
self-contained table, if you're going to change it
Special Vars:
Purpose: Each comment will be formatted according to this block. It
should consist of one or more single-celled table rows (you could just include something else
in a <TR><TD></TD></TR>, but it's gotta look like a
table row with one cell, on the outside). Many special vars included in this one, so pay
attention!
Special Vars:
Purpose: The legal warning to post before and after comments. Again, it
must look like one or more table rows, with one cell each, at least on the
outside.
Special Vars: None
Purpose: The bar that goes on top and below comments, with links to the
story, the number of comments, etc. As always, must look like a single-celled
table row.
Special Vars:
Purpose: The contents of the "Features" box. No special formatting
required, just some html.
Special Vars: None
Purpose: A page footer, stuff that you always want displayed at the
bottom of the page. Note that since you can also edit the entire page template
(umm, that'd be index_template) in Blocks, you
could easily change/move/rename this. But generally, you'll want a footer, and
this is where you'd put it. Formatting just has to mesh with index_template.
Special Vars: None
Purpose: Menu for the bottom of the page, probably. Gotchas here are the
tendancy to use pipe characters in menu lists. Remember to escape them! ('\|')
Special Vars: None.
Purpose: Stuff to put at the top of every page.
Special Vars:
Purpose: This one's pretty important. It controls the layout of your
entire standard page. There are two EXTREMELY important special vars here, so
read that part carefully. Generally this'll start with <HTML> and end with
</HTML>, and what's in the middle is mostly up to you. Experiment carefully
though, since if you bork this too badly, the page won't display, and you'll
have a hard time changing it back when you can't get to the admin console!
Special Vars:
Purpose: That's "moderate" the transitive verb, not the adjective. This
is the header to put above comments displayed in the story moderation section.
Should, of course, look like a single-celled table row.
Special Vars:
Purpose: This is the story moderation equivalent of comment. It controls how moderation vote/comment blocks are
displayed. Looks like one or more table rows.
Special Vars:
Purpose: Makes the "Recent Stories" display. This is basically a list of
topic icons, linked to their stories, however many you chose in the var recent_topics_num. Should probably be a table.
Special Vars:
Purpose: HTML to wrap around the story moderation "vote" console. Should
look like a table row with one cell, and must contain it's one and only special
var.
Special Vars:
Purpose: Controls the look of each "story summery". That is, the short
sections displayed on the main page, and that same bit on the full story page.
Should be one or more table rows, you knwo the drill.
Special Vars:
Purpose: Some html that will get displayed at the top of the story
submission page. Freeform, really.
Special Vars: None
Purpose: Get's displayed after someone submits a story. Whatever you want
to say.
Special Vars: None
This documentation is not yet complete, but it should at least get you started. For problems, help or bugs, email rusty@kuro5hin.org or visit Scoop Bug Reports.