Update of /cvs/scoop/scoop/doc/sag-tex-src
In directory lithium.sabren.com:/tmp/cvs-serv26254/doc/sag-tex-src
Modified Files:
admin-tools.tex admin.tex faq.tex features.tex hacking.tex
install.tex intro.tex sag.tex sbe.tex
Log Message:
Documentation updates. Bugs 98, 114, 144, 148, 149, 150, 151, 155.
-janra
Index: admin.tex
===================================================================
RCS file: /cvs/scoop/scoop/doc/sag-tex-src/admin.tex,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** admin.tex 28 Mar 2004 22:14:22 -0000 1.2
--- admin.tex 27 Feb 2005 13:28:36 -0000 1.3
***************
*** 15,32 ****
{\bf Note:} if you just get a directory listing, check to make sure that you followed the directions in the section~\ref{install} completely, and that the Apache that's running is the one you compiled, has mod\_perl working, and has been freshly started with the Scoop code present.
! First, log in as `scoop' with the password you entered in the install phase. If you installed by hand and didn't use the install.pl script, the initial password is also `scoop'. Once you're logged in, the login fields should disappear and in their place is a box titled `scoop'. Not far below that, another new box has appeared, titled `Admin Tools'.
! The first thing to do is to make sure all of the required settings are right. All site-wide settings can be found in Site Controls, in your Admin Tools box.
! {\bf Note:} if you get `Permission Denied' when you click on Site Controls, there's probably something wrong with your cookies. See section~\ref{apache-config} for details on how it should be set up.
Most of the default settings should work, but there are some that you should definitely change, all in the `General' category:
\begin{itemize}
! \item {\bf imagedir}: check this and make sure it's correct. If your images are showing up on the page, it probably is.
! \item {\bf local\_email}: put the email you want Scoop to send stuff like new account notices from. This email address must be a valid one, both for the program and because people sometimes reply to it. You can put a name in it as well as the email address, by putting ``My Site Name \latexhtml{$<$scoop at mysite.org$>$}{<scoop at mysite.org>}'' (without the quotes) in the field. If this email is invalid, Scoop will often tell people that their email is invalid when they try to create an account.
! \item {\bf logout\_url}: put the full address of your website here, unless you have a specific page you want to direct people to when they log out, then put that. The front page is a good default. Don't leave it blank, or Apache will try to redirect you to nowhere. This should be a complete URL, including http://
\item {\bf sitename}: The official name of your site, not the URL. This is used for display and in emails, mostly.
\item {\bf site\_url}: The full URL of your site's front page, without a trailing slash. If there is a trailing slash, links sent in email to new accounts won't work properly because the double slash screws up Scoop's path parser (which separates parameters with slashes).
- \item {\bf slogan}: Put a witty saying here. It shows up in the title bar of the browser on the front and section pages.
\item {\bf time\_zone}: Put your time zone here. Rather, put the time zone your server runs on here, otherwise people will get very confused about posts coming from the future or the past, and the like.
\item {\bf admin\_alert}: The email(s) Scoop should email when it has a problem. This is generally rarely used, but extremely important.
--- 15,30 ----
{\bf Note:} if you just get a directory listing, check to make sure that you followed the directions in the section~\ref{install} completely, and that the Apache that's running is the one you compiled, has mod\_perl working, and has been freshly started with the Scoop code present.
! First, log in with the username password you entered in the install phase. If you installed by hand and didn't use the install.pl script, the initial username and password are both `scoop'. Once you're logged in, the login fields should disappear and in their place is a box titled with your username. Not far below that, another new box has appeared, titled `Admin Tools'.
! The first thing to do is to make sure all of the required settings are right. All site-wide settings can be found in Site Controls (the link is in the Admin Tools box).
! {\bf Note:} if you get `Permission Denied' when you click on the Site Controls link, there's probably something wrong with your cookies. See section~\ref{apache-config} for details on how it should be set up.
Most of the default settings should work, but there are some that you should definitely change, all in the `General' category:
\begin{itemize}
! \item {\bf imagedir}: check this and make sure it's correct. If your images are showing up on the page, it probably is fine.
! \item {\bf local\_email}: put the email you want Scoop to send stuff like new account notices {\em from}. This email address must be a valid one, both for the program and because people sometimes reply to it. You can put a name in it as well as the email address, by putting ``My Site Name \latexhtml{$<$scoop at mysite.org$>$}{<scoop at mysite.org>}'' (without the quotes) in the field. If this email is invalid, Scoop will often tell people that {\em their} email is invalid when they try to create an account.
\item {\bf sitename}: The official name of your site, not the URL. This is used for display and in emails, mostly.
\item {\bf site\_url}: The full URL of your site's front page, without a trailing slash. If there is a trailing slash, links sent in email to new accounts won't work properly because the double slash screws up Scoop's path parser (which separates parameters with slashes).
\item {\bf time\_zone}: Put your time zone here. Rather, put the time zone your server runs on here, otherwise people will get very confused about posts coming from the future or the past, and the like.
\item {\bf admin\_alert}: The email(s) Scoop should email when it has a problem. This is generally rarely used, but extremely important.
***************
*** 63,67 ****
Some others are section-specific, or both section- and group-specific. Those are generally found in the Sections Admin Tool, and are referred to within Scoop as `section perms'.
! The preferences found in Site Controls are global to the site.
\subsubsection{Blocks}
--- 61,65 ----
Some others are section-specific, or both section- and group-specific. Those are generally found in the Sections Admin Tool, and are referred to within Scoop as `section perms'.
! The preferences found in Site Controls are global to the site. There are also user-specific preferences (user prefs) which each user can change on their own; the user preferences available and their defaults can be managed in the User Preferences Admin Tool (\ref{admin-tools-user-preferences}).
\subsubsection{Blocks}
***************
*** 78,88 ****
If you refer to a block that doesn't exist, possibly by making a typo in a key that should refer to a block that does exist, Scoop silently replaces it with an empty string. If you're quite sure you put a block there and nothing is showing up, double-check your spelling.
! Now that you know this, you can start changing the look of your site. But it's easy to very quickly get lost in the maze of blocks and keys, especially with ``special keys'', so the best place to start is at the top level---the page templates in the templates category.
A page template is just another block, but it's the first one Scoop pulls up when it's building a page because it is a complete HTML page, starting with \latexhtml{$<$html$>$}{<html>} and ending with \latexhtml{$<$/html$>$}{</html>}.
! Your front page (and section pages) will use index\_template, viewing a story uses the story\_template, and most admin pages use admin\_template. Be very careful changing these, because, if you mess it up, you might not be able to view your site.
! To change a template, go to the block editor and choose the ``templates'' link, then scroll down to view the contents of the ``index\_template'' block. You can see near the top there is a key called \latexhtml{$\vert$}{|}header\latexhtml{$\vert$}{|}. As you can probably guess, this is a reference back to the header that we changed a few paragraphs before. It also contains the special key \latexhtml{$\vert$}{|}CONTENT\latexhtml{$\vert$}{|}, which is where all of the stories for the page are inserted. By changing this page you can drastically alter how your site appears. The special block \latexhtml{$\vert$}{|}CONTENT\latexhtml{$\vert$}{|} is critical, as it is replaced with the main content---in the case of the index\_template, it is replaced with the headlines and story summaries.
There are several special keys, most specific to a particular block and filled from the database. For example, the comment block, in the content category, has special keys for the comment subject, author, rating, and so on; those special keys have no meaning outside the comment block and corresponding blocks will not be found in the Blocks Admin Tool.
--- 76,86 ----
If you refer to a block that doesn't exist, possibly by making a typo in a key that should refer to a block that does exist, Scoop silently replaces it with an empty string. If you're quite sure you put a block there and nothing is showing up, double-check your spelling.
! Now that you know this, you can start changing the look of your site. But it's easy to very quickly get lost in the maze of blocks and keys, especially with ``special keys'' which do not refer to a block at all, so the best place to start is at the top level---the page templates category.
A page template is just another block, but it's the first one Scoop pulls up when it's building a page because it is a complete HTML page, starting with \latexhtml{$<$html$>$}{<html>} and ending with \latexhtml{$<$/html$>$}{</html>}.
! Your front page (and section pages) will use index\_template, viewing a story uses the story\_template, and most admin pages use admin\_template. Be very careful changing these, because, if you mess them up, you might not be able to view your site.
! To change a template, go to the block editor and choose the ``Page Templates'' link, then scroll down to view the contents of the ``index\_template'' block. You can see near the top there is a key called \latexhtml{$\vert$}{|}header\latexhtml{$\vert$}{|}. As you can probably guess, this is a reference back to the header that we changed a few paragraphs before. It also contains the special key \latexhtml{$\vert$}{|}CONTENT\latexhtml{$\vert$}{|}, which is where all of the stories for the page are inserted. By changing this page you can drastically alter how your site appears. The special block \latexhtml{$\vert$}{|}CONTENT\latexhtml{$\vert$}{|} is critical, as it is replaced with the main content---in the case of the index\_template, it is replaced with the headlines and story summaries.
There are several special keys, most specific to a particular block and filled from the database. For example, the comment block, in the content category, has special keys for the comment subject, author, rating, and so on; those special keys have no meaning outside the comment block and corresponding blocks will not be found in the Blocks Admin Tool.
***************
*** 95,103 ****
Blocks are only the beginning of the story, however, and since they always return (roughly) the same thing, they can't provide some of the more customized content.
! You will notice that the templates also contain keys like \latexhtml{$\vert$}{|}BOX,login\_box\latexhtml{$\vert$}{|} and \latexhtml{$\vert$}{|}BOX,user\_box\latexhtml{$\vert$}{|}. Unlike the blocks that we have just looked at, {\bf a box is a chunk of Perl code} that generally has HTML as output. Don't be too scared by this, because you don't have to learn very much Perl to change some basic functionality of the boxes.
Boxes can include keys as part of their output, and those will be interpolated in the same way as keys included in blocks.
! If you already know Perl, you will find Boxes to be an invaluable way to customize your Scoop site. Some fairly significant features have been done entirely in boxes, since boxes have access to every Scoop function and every bit of data Scoop carries.
If you don't know Perl, you will be limited to tweaking the existing boxes, or borrowing code from the Scoop Box Exchange. I am not going to provide a Perl tutorial for you here, but if you are interested in some light customization, just examine some of the boxes that ship with Scoop. If you like, you can look at a Perl tutorial so you can go a bit farther.
--- 93,101 ----
Blocks are only the beginning of the story, however, and since they always return (roughly) the same thing, they can't provide some of the more customized content.
! You will notice that the templates also contain keys like \latexhtml{$\vert$}{|}BOX,admin\_tools\latexhtml{$\vert$}{|} and \latexhtml{$\vert$}{|}BOX,user\_box\latexhtml{$\vert$}{|}. Unlike the blocks that we have just looked at, {\bf a box is a chunk of Perl code} that generally has HTML as output. Mostly, the boxes produce fairly generic output and don't need much changing, and the box template (Blocks Admin Tool, Box Templates category) chosen will have the most effect on how they look.
Boxes can include keys as part of their output, and those will be interpolated in the same way as keys included in blocks.
! If you already know Perl, you will find Boxes an invaluable way to customize your Scoop site. Some fairly significant features have been done entirely in boxes, since boxes have access to every Scoop function and every bit of data Scoop carries.
If you don't know Perl, you will be limited to tweaking the existing boxes, or borrowing code from the Scoop Box Exchange. I am not going to provide a Perl tutorial for you here, but if you are interested in some light customization, just examine some of the boxes that ship with Scoop. If you like, you can look at a Perl tutorial so you can go a bit farther.
***************
*** 114,120 ****
\subsubsection{Accounts}
! Account creation is automated and easy. It requires a user to provide a working email address, so Scoop can send them their first password; it also requires you to configure Scoop to be able to successfully send email with a valid From: address (covered in section~\ref{how-start}).
! If Scoop's {\bf email address is invalid}, it will tell a new user trying to create an account that it's the user's email address that is invalid.
Beside the username in all stories and comments, as well as on the User Info page, an ``Edit User'' link will let you edit that user's User Info, as well as change their username and group, and add notes about that user that only administrators can see, such as keeping a record of abuses so the account can have its permissions reduced appropriately if necessary.
--- 112,118 ----
\subsubsection{Accounts}
! Account creation is automated and easy. It requires a user to provide a working email address, so Scoop can confirm their account; it also requires you to configure Scoop to be able to successfully send email with a valid From: address (covered in section~\ref{how-start}).
! If Scoop's {\bf email address is invalid}, it will often tell a new user trying to create an account that it's the user's email address that is invalid.
Beside the username in all stories and comments, as well as on the User Info page, an ``Edit User'' link will let you edit that user's User Info, as well as change their username and group, and add notes about that user that only administrators can see, such as keeping a record of abuses so the account can have its permissions reduced appropriately if necessary.
***************
*** 122,126 ****
It's generally not a good idea to delete a user unless the account was just created and hadn't really done anything, because there is so much stuff tied to the userid and to that stuff (i.e., a user has comments, those comments have replies). Accounts which are created and post nothing but abusive comments and stories are generally the only accounts that should be deleted.
! If somebody goes on an unfair rating rampage, their ratings can be reversed. To revoke their rating abilities at the same time, you have to create a more restricted group that is missing that permission, then put that group's name in the site control `rating\_wipe\_group', in the Security category.
\subsubsection{Groups}
--- 120,124 ----
It's generally not a good idea to delete a user unless the account was just created and hadn't really done anything, because there is so much stuff tied to the userid and to that stuff (i.e., a user has comments, those comments have replies). Accounts which are created and post nothing but abusive comments and stories are generally the only accounts that should be deleted.
! If somebody goes on an unfair rating rampage, their ratings can be reversed. To revoke their rating abilities at the same time, you have to create a more restricted group that is missing that permission, then put that group's name in the site control `rating\_wipe\_group', in the Security category. The link to reverse a user's ratings is on the page showing that user's ratings.
\subsubsection{Groups}
***************
*** 142,154 ****
More than half of the permissions are for administrative stuff. All but one determine whether or not the user can perform an action; the one exception is super\_mojo, which basically means that regardless of comment ratings, users in that group are always considered trusted.
! The Superuser should have all permissions checked at all times.
! {\bf Warning:} if a group has permission to edit users and groups, members of that group can give themselves and others superuser privileges. Just because it's a website, don't think somebody with superuser privileges can't hose your system; Scoop's box system can run any command on your system---including starting a daemon, or fetching the daemon (or trojan!) first, then starting it---and present the output to a person viewing the page in any way the box creator wants.
Permissions are checked both when an action is attempted and when building the page; somebody without the comment\_post permission, for example, simply will not see the ``Reply to this'' and ``Post a comment'' links anywhere.
! If you ever need to {\bf add a new permission}, the master list is stored in the variable ``perms''. When you add a new perm it will default to being unselected for all groups. If for any reason you delete a perm from that list, the perm will still be set for all users that formerly had it, so make sure you've removed the permission from the groups first.
! There are also {\bf section permissions}, allowing you to have read-only or admin-only sections, as well as allowing certain groups to automatically post and bypass the queue. Those settings can be useful in several situations, including a ``Site News'' style section, in which normal users cannot post stories but the site administrator can automatically post to the section. These are available in the Sections Admin Tool (\ref{admin-tools-sections}). Using those permissions, an admin-only section, for example, can use either ``Hide'', where Scoop pretends that the section doesn't exist for that user, or ``Deny'', where Scoop admits that the section exists and tells the user he doesn't have permission to see it.
\subsubsection{Publishing Stories}
--- 140,152 ----
More than half of the permissions are for administrative stuff. All but one determine whether or not the user can perform an action; the one exception is super\_mojo, which basically means that regardless of comment ratings, users in that group are always considered trusted.
! The Superuser should have all permissions checked at all times, except the ``suballow\_group\_change'' and ``allow\_subscription'' perms, as those allow Scoop to change the user group if subscriptions are active. (Generally, subscribers will have fewer perms than the superuser...)
! {\bf Warning:} if a group has permission to edit users and groups, members of that group can give themselves and others superuser privileges. Just because it's a website, don't think somebody with superuser privileges can't hose your system; Scoop's box system can run {\bf any command on your system}---including starting a daemon, or fetching the daemon (or trojan!) first, then starting it---and present the output to a person viewing the page in any way the box creator wants. I have heard of one site administrator using a Scoop box to restart sshd when it died once.
Permissions are checked both when an action is attempted and when building the page; somebody without the comment\_post permission, for example, simply will not see the ``Reply to this'' and ``Post a comment'' links anywhere.
! If you ever need to {\bf add a new permission}, the master list is stored in the Site Control ``perms''. When you add a new perm it will default to being unselected for all groups. If for any reason you delete a perm from that list, the perm will still be set for all users that formerly had it, so make sure you've removed the permission from the groups first.
! There are also {\bf section permissions}, allowing you to have read-only or admin-only sections, as well as allowing certain groups to automatically post and bypass the queue. Those settings can be useful in several situations, including a ``Site News'' style section, in which normal users cannot post stories at all, but the site administrator can automatically post to the section. These are available in the Sections Admin Tool (\ref{admin-tools-sections}). Using those permissions, an admin-only section, for example, can use either ``Hide'', where Scoop pretends that the section doesn't exist for that user, or ``Deny'', where Scoop admits that the section exists and tells the user he doesn't have permission to see it.
\subsubsection{Publishing Stories}
***************
*** 195,203 ****
Scoop has the ability to run a box when certain events occur; the box can then do anything any Scoop box or function can do. This can be administered in the Hooks Admin Tool.
! A few of the events that are included but not activated by default log admin actions such as comment deletion. For example, if you wanted Scoop to email you when a story was posted, you could create a box that sends the email, and then bind the hook story\_post to your new box.
! If you activate the hooks that log admin events and set the variable use\_logging to either 1 (normal logging) or 2 (extended logging), the logs it creates can be viewed using the Log Admin Tool.
! A given hook can have as many functions as you want bound to it; however, you can't control what order they're run in, so none of them should depend on another of the hooks.
\subsection{Performance Monitoring}
--- 193,203 ----
Scoop has the ability to run a box when certain events occur; the box can then do anything any Scoop box or function can do. This can be administered in the Hooks Admin Tool.
! A few of the events that are included but not activated by default log admin actions such as comment deletion. If you activate the hooks that log admin events and set the variable use\_logging to either 1 (normal logging) or 2 (extended logging), the logs it creates can be viewed using the Log Admin Tool.
! For example, if you wanted Scoop to email you when a story was posted, you could create a box that sends the email, and then bind the hook story\_post to your new box.
! A given hook can have as many functions as you want bound to it; however, you can't control what order they're run in, so none of them should depend on another of the hooks. Hooks are given specified parameters which are relevent to the event; story\_post, for example, has two parameters: sid (the Story ID, a five-part numeric code) and where (the location the story is posted: either 'front' or 'Section').
!
! See section~\ref{admin-tools-hooks} for more information on hooks, when they are run, and tips on writing boxes for them.
\subsection{Performance Monitoring}
***************
*** 222,238 ****
\subsubsection{Access Control}
! If you have a development site that you don't really want people to see, or you're still setting it up and {\em don't want it to be publicly available just yet}, you can easily use apache's HTTP basic authentication. This is not a very good way to keep people out of sensitive areas, being only one step above ``Halt! Friend or Foe?'' ``Friend, of course'' ``Carry on''. It will keep bots and casual passers-by out, though.
!
! To turn on basic authentication with Scoop, find the Location directive for Scoop's root directory, and add the following lines (modify as necessary to suit your site) and stop then start your Apache server.
!
! \begin{verbatim}
! AuthType Basic
! AuthName "Whatever"
! AuthUserFile /path/to/.htpasswd
! Require user foo
! \end{verbatim}
!
! Then create entries in the .htpasswd file as described in the Apache documentation. When you are ready to open your site to the world, just delete or comment out those four lines, then stop and start Apache.
!
! An alternative to the basic authentication is Scoop's ``Safe Mode'', which returns a 503 Service Unavailable to everybody except the Superuser account, allowing you to set your site up then ``flick a switch'' (the variable {\bf safe\_mode}) to let everybody else in. See section~\ref{features-safemode} for details.
--- 222,225 ----
\subsubsection{Access Control}
! If you have a development site that you don't really want people to see, or you're still setting it up and {\bf don't want it to be publicly available just yet}, you can use Scoop's ``Safe Mode'', which returns a 503 Service Unavailable to everybody except the Superuser account, allowing you to set your site up then ``flick a switch'' (the variable {\bf safe\_mode}) to let everybody else in. As Scoop will process logins before determining whether or not to allow access, you can have a login form on a custom 503 error page which will allow you access to the site. See section~\ref{features-safemode} for details.
Index: sbe.tex
===================================================================
RCS file: /cvs/scoop/scoop/doc/sag-tex-src/sbe.tex,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** sbe.tex 28 Mar 2004 22:14:22 -0000 1.2
--- sbe.tex 27 Feb 2005 13:28:36 -0000 1.3
***************
*** 2,6 ****
\label{sbe}
! The Scoop Box Exchange (SBE) is a repository of boxes for Scoop that users and developers have written and decided to share. The SBE can be found at \hturl{http://www.perlmonkey.net/sbe/}.
\subsection{Boxes as a small part of the page}
--- 2,6 ----
\label{sbe}
! The Scoop Box Exchange (SBE) is a repository of boxes for Scoop that users and developers have written and decided to share. The SBE can be found at \hturl{http://scoop.kuro5hin.org/sbe/}.
\subsection{Boxes as a small part of the page}
Index: install.tex
===================================================================
RCS file: /cvs/scoop/scoop/doc/sag-tex-src/install.tex,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** install.tex 28 Mar 2004 22:14:22 -0000 1.2
--- install.tex 27 Feb 2005 13:28:36 -0000 1.3
***************
*** 29,41 ****
\label{install-require}
! {\bf Perl}, or Practical Extraction and Report Language, is the underlying language Scoop is written in. Scoop requires {\bf at least perl 5.005\_03} in order to run (note that the versioning system used for Perl changed between 5.005 and 5.6) but will work fine with later versions. Perl is available from \hturl{http://www.cpan.org/src/} and is available in both source and binary distributions. A standard Perl install is your best bet, so follow the instructions included with the distribution. If you're installing Scoop on any OS other than Windows, you probably already have a suitable Perl installed. If you're installing on Windows, you'll need to get and install ActiveState's Perl, available from \hturl{http://www.activestate.com/Products/ActivePerl/}.
{\bf Expat} is an XML parser. Strictly speaking, Scoop doesn't need it to run, but if you want to add RDF functionality later and you didn't put this in from the beginning, you'll basically have to recompile everything. So install it. Expat can be downloaded from \hturl{http://sourceforge.net/projects/expat/} and a default install is all that is needed. Follow the instructions that come with the distribution. When compiling Apache, you may need to explicitly tell it where expat is located, as sometimes it can't find it on its own.
! {\bf Apache} is a popular HTTP server, is available from the Apache website at \hturl{http://www.apache.org/dist/httpd/} and is the only one Scoop supports. A stable version of Apache 2.0 has been released, but is not supported by Scoop. Just about any version of Apache 1.3 should work, though the most recent is recommended as it will always include bug and security fixes. You should compile Apache by hand and not use a precompiled version, as precompiled packages are notorious for not working properly with Scoop. When you compile Apache, make sure to include mod\_perl (below) directly in the program. See section~\ref{install-apache-modperl} for detailed instructions.
! {\bf Mod\_perl}, Apache module, is also required. The stable tree is 1.x, and you can get it from the mod\_perl website at \hturl{http://perl.apache.org/}. Note that if you get, or already have, an older version of Apache, then you may need to get an older version of mod\_perl to work with it. As with Apache, the most recent 1.x version is recommended as it has bug and security fixes, but the mod\_perl version must correspond to the Apache version, as detailed on their website. Mod\_perl 2.0 is not yet stable enough for us to start porting Scoop, so it isn't supported.
! {\bf MySQL} is a database management system (DBMS), and is currently the only one Scoop supports, though support for Postgres is in the works. The stable tree for MySQL is 4.0, and versions 4.x, 3.23.x and 3.22.x are known to work with Scoop. To tell Scoop which one you're using, you have to set the variable mysql\_version in the Apache configuration file to a number corresponding to the first two parts of the version number (i.e., 3.22, 3.23, or 4.0). Version 3.22 uses a different date format, and version 4 has some extra features that Scoop can take advantage of, so you must set this variable correctly. All versions are available for download from \hturl{http://www.mysql.com/downloads/}. The most recent 3.23.x or 4.x version is recommended, and a default install is your best bet. Follow the installation instructions on the MySQL website, then make sure that you can access the MySQL database from the webserver. If you are using a binary mysql package, such as the .r!
pm or .deb, you will also need the mysql development package, whatever it is named in your packaging system. If you are compiling from source, you will have everything necessary already.
\subsubsection{Required Perl Modules}
--- 29,41 ----
\label{install-require}
! {\bf Perl}, or Practical Extraction and Report Language, is the underlying language Scoop is written in. Scoop requires {\bf at least perl 5.005\_03} in order to run (note that the versioning system used for Perl changed between 5.005 and 5.6) but will work fine with later versions. Perl is available from \hturl{http://www.cpan.org/src/} and is available in both source and binary distributions. A standard Perl install is your best bet, so follow the instructions included with the distribution. If you're installing Scoop on any OS other than Windows or Solaris, you probably already have a suitable Perl installed. See the system-specific notes for details.
{\bf Expat} is an XML parser. Strictly speaking, Scoop doesn't need it to run, but if you want to add RDF functionality later and you didn't put this in from the beginning, you'll basically have to recompile everything. So install it. Expat can be downloaded from \hturl{http://sourceforge.net/projects/expat/} and a default install is all that is needed. Follow the instructions that come with the distribution. When compiling Apache, you may need to explicitly tell it where expat is located, as sometimes it can't find it on its own.
! {\bf Apache} is a popular HTTP server, is available from the Apache website at \hturl{http://www.apache.org/dist/httpd/} and is the only one Scoop supports. Scoop with Apache 2.0 is not supported and not considered stable. Just about any version of Apache 1.3 should work, though the most recent is recommended as it will always include bug and security fixes. You should compile Apache by hand and not use a precompiled version, as many precompiled packages don't work properly with Scoop. When you compile Apache, you can include mod\_perl (below) directly in the program or compile it separately as a DSO (module). See section~\ref{install-apache-modperl} for detailed instructions.
! {\bf Mod\_perl}, an Apache module, is also required. The stable tree is 1.x, and you can get it from the mod\_perl website at \hturl{http://perl.apache.org/}. Note that if you get, or already have, an older version of Apache, then you may need to get an older version of mod\_perl to work with it. As with Apache, the most recent 1.x version is recommended as it has bug and security fixes, but the mod\_perl version must correspond to the Apache version, as detailed on their website. Mod\_perl 2.0 is not yet supported.
! {\bf MySQL} is a database management system (DBMS), and is currently the only one Scoop supports, though support for Postgres is in the works. The stable tree for MySQL is 4.0, and versions 4.x, 3.23.x and 3.22.x are known to work with Scoop. You must set the variable mysql\_version in the Apache configuration file to a number corresponding to the first two parts of the version number (i.e., 3.22, 3.23, or 4.0). Version 3.22 uses a different date format, and version 4 has some extra features that Scoop can take advantage of, so you must set this variable correctly. All versions are available for download from \hturl{http://www.mysql.com/downloads/}. The most recent 3.23.x or 4.x version is recommended, and a default install is your best bet. Follow the installation instructions on the MySQL website, then make sure that you can access the MySQL database from the webserver. If you are using a binary mysql package, such as the .rpm or .deb, you will also need the mysql !
development package, whatever it is named in your packaging system. If you are compiling from source, you will have everything necessary already.
\subsubsection{Required Perl Modules}
***************
*** 44,48 ****
Scoop uses quite a few Perl modules, all of which are available from CPAN. Table~\ref{perlmod} has a list of modules that are currently required by Scoop, as well as common problems encountered when installing them.
! This is pretty consistently {\bf the hardest, most frustrating} part of installing Scoop. Unfortunately, there is nothing we can do about it, since all the suckage is in CPAN and the quirky, fragile test scripts that come with some modules. There are some modules that simply will not pass their tests, even when compiled correctly. A ``force install'' is required to bypass the tests in those cases.
There are several ways to install them. You could go to CPAN, get each tarball, and install by hand, but that takes time and effort. You could also use the CPAN shell (more on this below) to install each one, but that still requires typing out each module.
--- 44,48 ----
Scoop uses quite a few Perl modules, all of which are available from CPAN. Table~\ref{perlmod} has a list of modules that are currently required by Scoop, as well as common problems encountered when installing them.
! This is pretty consistently {\bf the hardest, most frustrating} part of installing Scoop. Unfortunately, there is nothing we can do about it, since all the suckage is in CPAN and the quirky, fragile test scripts that come with some of the modules. There are some modules that simply will not pass their tests, even when compiled correctly. A ``force install'' is required to bypass the tests in those cases.
There are several ways to install them. You could go to CPAN, get each tarball, and install by hand, but that takes time and effort. You could also use the CPAN shell (more on this below) to install each one, but that still requires typing out each module.
***************
*** 83,91 ****
Apache::Test & ? & The newest versions of Apache::Request require Apache::Test, and if your /root directory has permissions 700 or 710, the tests will fail. Apache::Test starts up its own apache process, and tries to access a test html file inside /root/.cpan/, which it naturally doesn't have permission to... {\bf fix:} either force install Apache::Test, or change your permissions on /root to 711 (rwx--x--x) for the duration of the install, then back to whatever it was before after finishing installing this module. \\
%\hline
- Apache::Session & 1.51 & may need to force install using CPAN; sometimes one of the test programs won't compile \\
- %\hline
Class::Singleton & 1.03 & \\
%\hline
! Crypt::UnixCrpyt & 1.0 & \\
%\hline
Mail::Sendmail & 0.77 & \\
--- 83,89 ----
Apache::Test & ? & The newest versions of Apache::Request require Apache::Test, and if your /root directory has permissions 700 or 710, the tests will fail. Apache::Test starts up its own apache process, and tries to access a test html file inside /root/.cpan/, which it naturally doesn't have permission to... {\bf fix:} either force install Apache::Test, or change your permissions on /root to 711 (rwx--x--x) for the duration of the install, then back to whatever it was before after finishing installing this module. \\
%\hline
Class::Singleton & 1.03 & \\
%\hline
! Crypt::UnixCrypt & 1.0 & \\
%\hline
Mail::Sendmail & 0.77 & \\
***************
*** 97,100 ****
--- 95,102 ----
Time::Timezone & 99.062401 & \\
%\hline
+ Time::ParseDate & 99.062401 & \\
+ %\hline
+ Date::Calc & 5.4 & \\
+ %\hline
XML::Parser & 2.30 & must have expat installed \\
%\hline
***************
*** 146,150 ****
\end{itemize}
! The \$ indicates a normal user prompt; the \% a root prompt. This can all be done as root, but is not recommended. The backslash at the end of a line immediately precedes a newline; do not put any spaces after the backslash and before the newline.
\begin{verbatim}
--- 148,152 ----
\end{itemize}
! The \$ indicates a normal user prompt; the \% a root prompt. This can all be done as root, but is not recommended. The backslash at the end of a line immediately precedes a newline; do not put any spaces after the backslash and before the newline. And, obviously, substitute the correct value for the `x' in the version numbers.
\begin{verbatim}
***************
*** 166,172 ****
This places Apache into /usr/local/apache/*. you can change that to another value by altering APACHE\_PREFIX if you like.
\subsection{Getting Scoop}
! Before you can start installing and using Scoop, you're going to need to get it. Of course, if you already have it, then you can probably skip this section. Note that, while you'd usually want to get a stable version of any program, the nature of development with Scoop (at least, currently) results in a lot of new features being in the CVS development version, which is almost always stable. You'll probably want to get the development version. Besides, if you don't, you'll have a very hard time finding some of the better features described in this document!
\subsubsection{Getting a Tarball}
--- 168,176 ----
This places Apache into /usr/local/apache/*. you can change that to another value by altering APACHE\_PREFIX if you like.
+ If you are using different options for apache and mod\_perl, are adding other modules, or are compiling mod\_perl as a DSO instead of directly into apache (as the above instructions assume), you must not forget the `EVERYTHING=1' option to mod\_perl. If this is not set then Scoop will not work.
+
\subsection{Getting Scoop}
! Before you can start installing and using Scoop, you're going to need to get it. Of course, if you already have it, then you can probably skip this section. Note that, while you'd usually want to get a stable version of any program, the nature of development with Scoop (at least, currently) results in a lot of new features being in the CVS development version, which is almost always stable. You'll probably want to get the development version.
\subsubsection{Getting a Tarball}
***************
*** 196,200 ****
The script `{\bf install.pl}' is by far the easiest way to install Scoop. Once you've installed all the dependancies (\ref{install-depend}) and downloaded Scoop, all you have to do is change into the scripts directory and run install.pl. The install script isn't really set up to easily handle multiple Scoop sites, though it can work. Even if you use the install script, you may want to read section~\ref{by-hand} anyway, just to tweak things a bit.
! If you're running Windows, the installer won't work; you'll have to do it by hand, and follow a few special instructions besides. See sections~\ref{by-hand} and~\ref{install-system-notes}.
\subsubsection{Installing Perl Modules}
--- 200,204 ----
The script `{\bf install.pl}' is by far the easiest way to install Scoop. Once you've installed all the dependancies (\ref{install-depend}) and downloaded Scoop, all you have to do is change into the scripts directory and run install.pl. The install script isn't really set up to easily handle multiple Scoop sites, though it can work. Even if you use the install script, you may want to read section~\ref{by-hand} anyway, just to tweak things a bit.
! If you're running Windows, the installer won't work; you'll have to do it by hand, and follow a few special instructions as well. See sections~\ref{by-hand} and~\ref{install-system-notes}.
\subsubsection{Installing Perl Modules}
***************
*** 208,218 ****
If you're upgrading to a new computer, re-configuring your database will drop all the data in it, so unless that's your intention, don't let the script do it. If you're just upgrading the code, you shouldn't be using the install script; go read section~\ref{upgrading}.
! For a new install, however, you want to let it continue. You'll need to provide the installer with a username, password, hostname, and port so that it can connect to the database and do the work, though most of the defaults will work fine. Note that the user you provide will need to be able to create a database. At the next step, you'll probably want to choose option 1 (Create a new database), since if you rebuild, it'll just drop a current one.
Unless you have a specific reason to change it, such as if you're planning on running multiple Scoop sites on the same computer, the default database name will work just fine.
! After this, however, you'll need to make some choices. First is the path to Scoop on the webserver. What you put here depends on how you want to run Scoop. If you intend to run it on a domain or sub-domain (so that ``http://www.mysite.com/'' will access it), then put ``/'' in for the URL path. However, if you're running it in a separate directory (so that you access it with ``http://www.mysite.com/scoop/''), then put whatever you want the path to be in (which would be ``/scoop'' for our example). The next prompt asks simply for the email address of the admin (probably yours).
- Finally, you need to choose a password for the initial user (which will be called ``scoop''). This must be at least 8 characters long. After this, the database will be built (or re-built, depending on which option you chose).
\subsubsection{Configure Apache}
--- 212,221 ----
If you're upgrading to a new computer, re-configuring your database will drop all the data in it, so unless that's your intention, don't let the script do it. If you're just upgrading the code, you shouldn't be using the install script; go read section~\ref{upgrading}.
! For a new install, however, you want to let it continue. You'll need to provide the installer with a username, password, hostname, and port so that it can connect to the database and do the work, though most of the defaults will work fine. Note that you will need to give the script two usernames and passwords; one to create the database (usually the database root user) and one that Scoop will use to actually connect to the database (which should have access {\em only} to the Scoop database, as its password is stored in the apache configuration file). At the next step, you'll probably want to choose option 1 (Create a new database), since if you rebuild, it'll just drop a current one.
Unless you have a specific reason to change it, such as if you're planning on running multiple Scoop sites on the same computer, the default database name will work just fine.
! After this, you'll need to make some choices. The installer will walk you through the options, explaining each one. Make sure to read the prompts carefully.
\subsubsection{Configure Apache}
***************
*** 222,226 ****
The script then fills in the configuration file according to what you told it, then saves the configuration file with a name based on the site ID it asked for earlier (httpd-\latexhtml{$<$}{<}siteid\latexhtml{$>$}{>}.conf). Read this file over to make sure everything is set up properly. Put the file generated by the script in the same directory as your httpd.conf file.
! Edit httpd.conf to put an Include directive in the appropriate place, referencing Scoop's configuration file. The exact location of this directive will vary depending on how you have Apache set up, and if you've already done some customizations. Since the generated file contains full \latexhtml{$<$}{<}VirtualHost\latexhtml{$>$}{>} or \latexhtml{$<$}{<}Location\latexhtml{$>$}{>} directives, {\bf simply adding at the end of your httpd.conf file} should work.
The .conf file that Scoop generates for you {\bf is not a complete Apache configuration file}. It must be included in your main httpd.conf file either via pasting it in its entirety into httpd.conf or by using an Include directive.
--- 225,229 ----
The script then fills in the configuration file according to what you told it, then saves the configuration file with a name based on the site ID it asked for earlier (httpd-\latexhtml{$<$}{<}siteid\latexhtml{$>$}{>}.conf). Read this file over to make sure everything is set up properly. Put the file generated by the script in the same directory as your httpd.conf file.
! Edit httpd.conf to put an Include directive (\hturl{http://httpd.apache.org/docs/mod/core.html\#include}) in the appropriate place, referencing Scoop's configuration file. The exact location of this directive will vary depending on how you have Apache set up, and if you've already done some customizations. Since the generated file contains full \latexhtml{$<$}{<}VirtualHost\latexhtml{$>$}{>} or \latexhtml{$<$}{<}Location\latexhtml{$>$}{>} directives, {\bf simply adding at the end of your httpd.conf file} should work.
The .conf file that Scoop generates for you {\bf is not a complete Apache configuration file}. It must be included in your main httpd.conf file either via pasting it in its entirety into httpd.conf or by using an Include directive.
***************
*** 344,351 ****
$ cvs -d:pserver:anonymous at scoop.versionhost.com:/cvs/scoop login
password: anonymous
! $ cvs update -A -r STABLE
\end{verbatim}
! This will update your code as with `tracking CVS', above, but will move you from the numbered release to the latest stable code. If you want to do new feature development or just feel like living dangerously, you can leave off the `-r STABLE' to get the unstable CURRENT code. CURRENT is not guaranteed to work, nor even to be compatible with STABLE.
Before you take the site down to upgrade the database, running ``apachectl configtest'' will tell you if Apache will start properly when you try to bring the site back up again. This can be done while Apache is running (and probably should, so you still have a working site while you're trying to sort out any problems).
--- 347,354 ----
$ cvs -d:pserver:anonymous at scoop.versionhost.com:/cvs/scoop login
password: anonymous
! $ cvs update -A
\end{verbatim}
! This will update your code as with `tracking CVS', above, but will move you from the numbered release to the latest CVS code.
Before you take the site down to upgrade the database, running ``apachectl configtest'' will tell you if Apache will start properly when you try to bring the site back up again. This can be done while Apache is running (and probably should, so you still have a working site while you're trying to sort out any problems).
***************
*** 362,368 ****
It will also ask you where the patches are kept. If you're just tracking CVS, the default (scoop/struct/patch-files/current) is probably what you want. If you are upgrading from one numbered release to another, you will have to name those directories. If you are making a large upgrade, such as from 0.6 to 0.9, you will have to run the upgrade-db.pl script more than once: in this example, once for the directory 0.6-0.8 and once for the directory 0.8-0.9.
! If there has been a point release since the last time you updated, and you're tracking CVS, you'll have to first tell the script to use the appropriate numbered directory and then current, to make sure it gets all the patches.
! The script keeps track of which patches it's applied already in the database.
The patches must be applied in order, because they assume that all previous patches have been applied, and some alter information that was inserted by a previous patch.
--- 365,371 ----
It will also ask you where the patches are kept. If you're just tracking CVS, the default (scoop/struct/patch-files/current) is probably what you want. If you are upgrading from one numbered release to another, you will have to name those directories. If you are making a large upgrade, such as from 0.6 to 0.9, you will have to run the upgrade-db.pl script more than once: in this example, once for the directory 0.6-0.8 and once for the directory 0.8-0.9.
! If there has been a point release since the last time you updated, and you're tracking CVS, you'll have to first tell the script to use the appropriate numbered directory and then current, to make sure it gets all the patches. Missed patches cause very strange problems!
! upgrade-db.pl keeps track of which patches it's applied already in the database, which is why we strongly recommend that you use it.
The patches must be applied in order, because they assume that all previous patches have been applied, and some alter information that was inserted by a previous patch.
***************
*** 381,384 ****
--- 384,389 ----
Some operating systems have issues or quirks that need to be worked around. If your OS is listed here, make sure you read its section before installing.
+ Many thanks to the users and developers who have contributed the notes below.
+
\subsubsection{Debian Linux}
***************
*** 390,395 ****
\begin{itemize}
! \item before you can install Scoop you will need the developer tools (XCode) or you won't be able to compile any of the perl modules.
! \item the default Apache included with OS X works fine just by having it load mod\_perl
\item CPAN does not seem to like making all the perl modules; make fails with no useful error message. If you find this to be the case installing them by hand (outside of CPAN) works fine. It's tedious, but not particularly complicated, as most perl modules have the same install instructions, differing only in their prerequisites (which are listed in their README files). See the items below for a few prerequisite quirks.
\item Once the modules are installed, CPAN recognizes them and the install script works fine.
--- 395,400 ----
\begin{itemize}
! \item Before you can install Scoop you will need the developer tools (XCode) or you won't be able to compile any of the perl modules.
! \item The default Apache included with OS X works fine just by having it load mod\_perl
\item CPAN does not seem to like making all the perl modules; make fails with no useful error message. If you find this to be the case installing them by hand (outside of CPAN) works fine. It's tedious, but not particularly complicated, as most perl modules have the same install instructions, differing only in their prerequisites (which are listed in their README files). See the items below for a few prerequisite quirks.
\item Once the modules are installed, CPAN recognizes them and the install script works fine.
***************
*** 398,407 ****
\end{itemize}
\subsubsection{Windows 2000/XP}
\begin{itemize}
! \item mail sending is notoriously troublesome under Windows. Some people have reported that Scoop can send only one email before email stops working. No fix has been reported yet.
! \item you'll need to get and install ActiveState's Perl, which is available from \hturl{http://www.activestate.com/Products/ActivePerl/}.
! \item there is no CPAN for Windows, and therefore Bundle::Scoop won't work. Use ppm instead:
\begin{verbatim}
ppm install (module name)
--- 403,420 ----
\end{itemize}
+ \subsubsection{Solaris}
+
+ \begin{itemize}
+ \item The perl that comes with Solaris won't work properly. You should build your own perl using the same compiler you use to build mod\_perl. (perl has a notion of how it was built, and it tries to keep using that notion for future building.)
+ \item Make sure your perl install is in your path {\em before} the perl installed by Solaris, so that it's used when compiling apache/mod\_perl.
+ \item gcc-3.2 (Solaris package from sunfreeware) is the recommended compiler.
+ \end{itemize}
+
\subsubsection{Windows 2000/XP}
\begin{itemize}
! \item Mail sending is notoriously troublesome under Windows. Some people have reported that Scoop can send only one email before email stops working. No fix has been reported yet.
! \item You'll need to get and install ActiveState's Perl, which is available from \hturl{http://www.activestate.com/Products/ActivePerl/}.
! \item There is no CPAN for Windows, and therefore Bundle::Scoop won't work. Use ppm instead:
\begin{verbatim}
ppm install (module name)
***************
*** 468,471 ****
--- 481,486 ----
\hline
My site starts up fine, but when I (or anybody else) tries to create an account, no email is sent & make sure your smtp and email variables in the apache config file (\ref{apache-config}) and the Site Controls (\ref{initial-setup}) are set properly. Make sure the SMTP server you are using allows your Scoop server to send email through it. Make sure your SMTP server is allowed to send email to the receiving server, too, before messing with its configuration---if it's in a spam blocklist the receiving server is using, no email will get through, through no configuration on your part. \\
+ \hline
+ I get the error ``\latexhtml{$<$}{<}Perl\latexhtml{$>$}{>}: PerlSetVar takes two arguments, Perl config var and value'' but my PerlSetVar commands all have the two arguments they need & Check your VERSION file - chances are there's been a cvs conflict (usually at the bottom of the file). The conflict delimiters mess up how apache parses that file for version info. \\
\hline
\latex{\end{longtable}}
Index: sag.tex
===================================================================
RCS file: /cvs/scoop/scoop/doc/sag-tex-src/sag.tex,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** sag.tex 28 Mar 2004 22:14:22 -0000 1.2
--- sag.tex 27 Feb 2005 13:28:36 -0000 1.3
***************
*** 1,4 ****
% Scoop Administrator's Guide
! % Covers version 1.0
\documentclass{article}
--- 1,4 ----
% Scoop Administrator's Guide
! % Covers version 1.1
\documentclass{article}
***************
*** 10,14 ****
! \title{Scoop 1.0 Administration Guide}
\begin{document}
--- 10,14 ----
! \title{Scoop 1.1 Administration Guide}
\begin{document}
***************
*** 20,23 ****
--- 20,25 ----
\latex{\tableofcontents}
+
+ \latex{\clearpage}
\input{intro}
Index: faq.tex
===================================================================
RCS file: /cvs/scoop/scoop/doc/sag-tex-src/faq.tex,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** faq.tex 28 Mar 2004 22:14:22 -0000 1.2
--- faq.tex 27 Feb 2005 13:28:36 -0000 1.3
***************
*** 8,12 ****
\subsubsection{What exactly is Scoop?}
! Scoop is a ``Collaborative Media Application''. Basically, it's somewhere between a weblog, a bulletin board, and a content management system. Superficially, it looks exactly like a weblog, with stories displayed in reverse chronological order, and comments attached. The difference is that Scoop allows your users to drive the site by not only submitting stories, but acting as site editors and choosing which stories to publish. That's where the ``collaborative'' part of the name comes in.
Scoop is designed to enable your website to become a community. It empowers your visitors to be the producers of the site, contributing news and discussion, and making sure that the signal remains high.
--- 8,12 ----
\subsubsection{What exactly is Scoop?}
! Scoop is a ``Collaborative Media Application''. Basically, it's somewhere between a weblog, a bulletin board, and a content management system. Superficially, it looks like a weblog, with stories displayed in reverse chronological order, and comments attached. The difference is that Scoop allows your users to drive the site by not only submitting stories, but acting as site editors and choosing which stories to publish. That's where the ``collaborative'' part of the name comes in.
Scoop is designed to enable your website to become a community. It empowers your visitors to be the producers of the site, contributing news and discussion, and making sure that the signal remains high.
Index: hacking.tex
===================================================================
RCS file: /cvs/scoop/scoop/doc/sag-tex-src/hacking.tex,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** hacking.tex 28 Mar 2004 22:14:22 -0000 1.2
--- hacking.tex 27 Feb 2005 13:28:36 -0000 1.3
***************
*** 12,15 ****
--- 12,17 ----
Adding features sometimes require changes to the underlying code of Scoop, sometimes only boxes, and sometimes a combination of underlying code and boxes.
+ When you change any of the .pm files in the scoop/lib directory or you change any of the apache configuration, you must completely stop apache, then start it. This forces everything to be recompiled; an `apachectl restart' will {\em not} do the job. When you change anything that is available to change via the web interface, you don't need to touch apache, it gets picked up automatically.
+
\subsection{The \$S Object}
\label{hacking-s}
***************
*** 297,309 ****
\label{hacking-patches}
! Patches can be sent to the scoop-dev mailing list, scoop-dev at lists.sourceforge.net or if they are a bugfix can be attached to the bug in question in bugzilla, at \hturl{http://bugz.mostly-harmless.ca/}.
! Only send patches against the most recent cvs tree, and indicate if it's the STABLE or CURRENT tree.
! Create your code patches using the `cvs diff -c' command. You probably want to redirect the output of that command into an appropriately named file.
If any changes to the database are required, submit a database patch with all the SQL commands required to make those changes. The syntax is exactly the same as it is in the mysql client, so it's a good idea to create the patch as you make the database changes, and copy/paste the SQL commands you use into the patch file.
! Remember that many blocks, boxes, and site controls that already exist may have been changed by a given site, and that if you are making significant changes to any of those that could break an established site, you probably want a db upgrade script that will test the site and make the changes as appropriate.
--- 299,311 ----
\label{hacking-patches}
! Patches should be attached to the relevant bug in the Scoop Bug Muncher, at \hturl{http://bugz.mostly-harmless.ca/}. If you have a patch for a new feature which has no corresponding bug in the bug muncher, create the bug, assign it to yourself, then attach the file. Please note that if you want the attachment to be reviewed you should set the `review?' flag on the attachment. That flag is used in searches and makes it easier for us to distinguish between patches already tested and those that aren't. By setting the review? flag, you will also get an email notice when the patch is tested and either approved (review+) or rejected (review-) by the maintainers.
! {\bf Only send patches against the most recent cvs tree!} Patches against older code will not be accepted. To make sure you are developing from the most recent code, do a `cvs update -dPA' in your scoop/ directory.
! Create your code patches using the `cvs diff -u' command, and issue that command in the scoop/ directory (not in the subdirectory containing the file you were working in) to make sure the patch contains all your changes. You probably want to redirect the output of that command into an appropriately named file. Note that these rules are to make it easier for the maintainers to read and apply your patch!
If any changes to the database are required, submit a database patch with all the SQL commands required to make those changes. The syntax is exactly the same as it is in the mysql client, so it's a good idea to create the patch as you make the database changes, and copy/paste the SQL commands you use into the patch file.
! Remember that many blocks, boxes, and site controls that already exist may have been changed by a given site, and that if you are making significant changes to any of those that could break an established site, you probably want a db upgrade script that will test the site and make the changes as appropriate. You can look at the scripts in the scoop/struct/patch-files directories for examples.
Index: features.tex
===================================================================
RCS file: /cvs/scoop/scoop/doc/sag-tex-src/features.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** features.tex 23 Jan 2005 03:45:58 -0000 1.3
--- features.tex 27 Feb 2005 13:28:36 -0000 1.4
***************
*** 182,185 ****
--- 182,205 ----
Then stop and start Apache. Paths should be adjusted as necessary for your setup. This will allow files in the scoop/html directory, such as robots.txt, backend.rdf, and dynamic-comments.js to be fetched normally.
+ \subsection{Story hotlisting/bookmarking}
+ \label{features-hotlist}
+
+ Scoop offers a `hotlist' feature which allows users to mark stories they would like to watch. Hotlisted stories are listed in a menu in the sidebar on every page via the {\bf hotlist} box, for easy access, and display the number of new comments (\ref{comments-unread}) since the story was last viewed. The hotlist box disappears entirely if no stories are hotlisted, unless the {\bf hotlist\_flex} or one of its variants (available from the Scoop Box Exchange: \ref{sbe}) is used.
+
+ The hotlist add/remove link is placed in the {\bf story\_summary} block using the special key {\bf \latexhtml{$\vert$}{|}hotlist\latexhtml{$\vert$}{|}}. The actual text (or image) of the hotlist link is set in the blocks {\bf hotlist\_link} and {\bf hotlist\_remove\_link}.
+
+ The {\bf hotlist} perm (\ref{perm-hotlist}) determines who can use the hotlist function and see the hotlist add/remove links.
+
+ Note that story hotlisting is distinct from diary subscriptions (\ref{sbe-diarysub}), although many people use `hotlist' to describe them both; story hotlisting does not notify you of new stories, it allows you to track specific existing stories.
+
+ \subsection{Automatic `Related Links' listing}
+ \label{features-autorelated}
+
+ For every story, Scoop provides a `Related Links' box in the sidebar which collects all of the links in the story plus a few internal links to more similar stories based on the author and topic of the story. This is done automatically by scanning the story's HTML for links.
+
+ There is also an `autorelated' feature, where certain keywords cause links to appear in the Related Links box, even if the story author didn't link them to anything. This does not affect the display of the story itself and does not insert any links into the story; it only adds links to the Related Links box. Words and phrases which trigger the `autorelated' feature and their links are defined in the Site Control {\bf autorelated}. By default only a few are defined, as an example of the format. When creating your own autorelated entries, try to keep the words specific and the phrases short, to decrease the chance of them appearing inappropriately and increase the chance of them being used, respectively.
+
+ For example, the default autorelated list includes \verb!Scoop, http://scoop.kuro5hin.org/!. Any mention of the name of the software will generate a link to Scoop's home page in the related links box. If \verb!gutenberg, http://www.gutenberg.org/! were added, any reference to Gutenberg's press, Project Gutenberg, or Gutenberg himself would generate a link to Project Gutenberg's home page. (If there are common misspellings of a word you want to link automatically, they should also be included as keywords.)
+
\subsection{Comments and Comment Views}
\label{features-comment-views}
***************
*** 228,232 ****
{\bf Unread comments} can be marked as new for registered users, and the index pages can display the number of new comments in a story since a user last read it. The read/unread status is based on the highest comment number the last time the user displayed the story and comments; the system assumes that all comments displayed have been read. Displaying comments alone does not mark them as read.
! The variable {\bf show\_new\_comments} determines whether all, none, or only that user's hotlisted stories track which comments have been read, and the block {\bf new\_comment\_marker} is displayed on the new comments.
The {\bf Scoop Box Exchange} (see appendix~\ref{sbe}) has a box that will notify users if there is an unread reply to one of their comments. If you use this box, let your users know that comments are only marked read if they view the story; this has caused confusion in the past.
--- 248,252 ----
{\bf Unread comments} can be marked as new for registered users, and the index pages can display the number of new comments in a story since a user last read it. The read/unread status is based on the highest comment number the last time the user displayed the story and comments; the system assumes that all comments displayed have been read. Displaying comments alone does not mark them as read.
! The variable {\bf show\_new\_comments} determines whether all, none, or only that user's hotlisted stories (\ref{features-hotlist}) track which comments have been read, and the block {\bf new\_comment\_marker} is displayed on the new comments.
The {\bf Scoop Box Exchange} (see appendix~\ref{sbe}) has a box that will notify users if there is an unread reply to one of their comments. If you use this box, let your users know that comments are only marked read if they view the story; this has caused confusion in the past.
***************
*** 367,371 ****
The weighted number of ratings and the sum of the weighted rating values are added independantly, then the value is divided by the number of ratings, to give the user's mojo.
! A user's trusted or untrusted status does not take effect unless the number of rated comments posted in the time limit set in the variable {\bf mojo\_max\_days} is greater than the number in the variable {\bf mojo\_min\_trusted} for trusted status, or {mojo\_min\_untrusted} for untrusted status.
If user abuses his privileges and {\bf rates good comments down or bad comments up} in a consistent pattern, his ratings can be reversed and rating privileges taken away with one click by the admin from the user's ``show user ratings'' page. The group the abusive user is transferred to is named in the variable {\bf rating\_wipe\_group}. This group must exist and shouldn't have the perm {\bf comment\_rate} (\ref{perm-comment-rate}). This doesn't affect that user's mojo calculation, but all users whose comments had been rated have their mojo recalculated.
--- 387,391 ----
The weighted number of ratings and the sum of the weighted rating values are added independantly, then the value is divided by the number of ratings, to give the user's mojo.
! A user's trusted or untrusted status does not take effect unless the number of rated comments posted in the time limit set in the variable {\bf mojo\_max\_days} is greater than the number in the variable {\bf mojo\_min\_trusted} for trusted status, or {\bf mojo\_min\_untrusted} for untrusted status.
If user abuses his privileges and {\bf rates good comments down or bad comments up} in a consistent pattern, his ratings can be reversed and rating privileges taken away with one click by the admin from the user's ``show user ratings'' page. The group the abusive user is transferred to is named in the variable {\bf rating\_wipe\_group}. This group must exist and shouldn't have the perm {\bf comment\_rate} (\ref{perm-comment-rate}). This doesn't affect that user's mojo calculation, but all users whose comments had been rated have their mojo recalculated.
***************
*** 521,524 ****
--- 541,601 ----
The ads available for commenting are filed in the section named in the variable {\bf ad\_story\_section}. You will have to create this section in the Sections Admin Tool before it will list the ad stories, and set its Post Story section permissions to ``Hide'' for all groups except Superuser to prevent people from posting regular stories to that section. Both Read permissions and the Post Comment permission should all still be ``Allow''. Ads will not show up on the ``Everything'' section page unless you remove the ad section from the variable {\bf sections\_excluded\_from\_all}.
+
+ \subsection{Calendar}
+ \label{features-calendar}
+
+ Scoop's calendar feature permits multiple public and private calendars and events, as well as allowing users to maintain their own personal calendars in addition to the site-wide calendars.
+
+ Calendars are turned on using the Site Control {\bf use\_calendars}. See the sections below for details on configuring the specific behaviour you want. Global calendar configuration is handled by the site controls in the `Events' category; calendar display is handled by the blocks in the `Calendars and Events' category. Per-calendar configuration and global event configuration are managed in the Calendars Admin Tool (\ref{admin-tools-calendars}).
+
+ Site-wide calendars can be managed by anyone with the {\bf edit\_calendars} perm (\ref{perm-edit-calendars}). One site-wide calendar is included by default, but you may create as many as you like.
+
+ If the Site Control {\bf allow\_user\_calendars} is on, users may create their own calendars, but only one calendar may be created per account. Users may set the access controls (\ref{features-calendar-access}) on their calendar however they choose, but admins always have the ability to see all calendars.
+
+ If a user has the {\bf submit\_event} perm (\ref{perm-submit-event}) and the calendar permissions allow it, they may submit events to a calendar for display to all other users. On submitting the event, they are marked as the `organizer' of that event and they (and the owner of the calender the event is submitted to) are able to invite site members to view the event and see the RSVP status, and, if they have the {\bf update\_own\_event} perm (\ref{perm-update-own-event}) can change the event.
+
+ If there is more than one site-wide calendar, or if users can have their own calendars, you probably want to enable calendar subscriptions (\ref{features-calendar-subscription}). Users are automatically subscribed to their own calendar when it is created.
+
+ The mini-calendar that can be displayed on the front page (the box {\bf mini\_calendar}) contains the same events as the full-sized calendar displayed on the /calendar URL, when no calendar ID is specified. If calendar subscriptions (\ref{features-calendar-subscription}) are on, this is the current user's personal calendar view; otherwise it is the calendar named in the site control {\bf default\_calendar\_id}.
+
+ \subsubsection{Access control}
+ \label{features-calendar-access}
+
+ Calendars and events each have a system of access control that can be as fine-grained as the calendar or event owner likes. Each calendar and event has a trio of permissions associated with it, two of which the calendar or event owner can change.
+
+ \begin{description}
+ \item[View] This determines who can view the calendar or event. The three options are: everybody (public), only people on the invitation list, and only me (private). Whenever a calendar or event is viewed, this permission is checked to make sure the current user has permission to see it. For calendars, somebody with the {\bf edit\_calendars} perm (\ref{perm-edit-calendars}) can see the calendar regardless of permissions. For events, somebody with the {\bf edit\_events} perm (\ref{perm-edit-events}) OR the owner of the calendar the event was submitted to can see the event regardless of permissions.
+ \item[Submit] This determines who can submit events to the calendar, or stories to the event. The five options are: everybody (public); everybody, but I will review the events before they're visible; only people on the invitation list; only people on the invitation list, but I will review the events before they're visible; and only me (private). This is checked when building the menus attached to a calendar or event so only appropriate links are shown, and also when somebody attempts to submit. For calendars, somebody with the {\bf edit\_calendars} perm (\ref{perm-edit-calendars}) can submit events to the calendar regardless of permissions. For events, somebody with the {\bf edit\_events} perm (\ref{perm-edit-events}) OR the owner of the calendar the event was submitted to can submit to the event regardless of permissions.
+ \item[Edit] This determines who can edit the calendar or event. For calendars, users with the {\bf edit\_calendars} perm (\ref{perm-edit-calendars}) or the owner of the calendar can edit the calendar settings, moderate event submissions, and manage the calendar's invitation list. For events, users with the {\bf edit\_events} perm (\ref{perm-edit-events}), the owner of the calendar the event was submitted to, or the user who submitted the event if that user has the {\bf update\_own\_event} perm (\ref{perm-update-own-event}) can edit the event and its invitation lists.
+ \end{description}
+
+ Events submitted to a private or invitation-only calendar will only be visible to people who have permission to see that calendar, and may be restricted further. To have an event visible to all as well as visible in a private or invitation-only calendar, it must be submitted to a public calendar then included in the private calendar afterward.
+
+ \subsubsection{Subscriptions}
+ \label{features-calendar-subscription}
+
+ If the site control {\bf allow\_personal\_calendar\_view} is on (and the user has the edit\_own\_calendar perm (\ref{perm-edit-own-calendar}) - wtf? FIXME: rusty added that), users can subscribe to multiple calendars and have their events displayed all at once in a `personal calendar view'. The personal calendar view is displayed when a user requests /my/calendar or otherwise doesn't specify a particular calendar ID. If the user is not subscribed to any calendars, the calendar named in the site control {\bf default\_calendar\_id} is displayed.
+
+ When viewing a specified calendar, a subscribe/unsubscribe link is provided as appropriate. Clicking the link will subscribe or unsubscribe the user as required.
+
+ When viewing the personal calendar view, all calendars available for the user's subscription are listed beside checkboxes. Checked calendars are currently subscribed; unchecked calendars are not. Multiple calendars can be subscribed and unsubscribed simultaneously by adjusting the checkboxes as desired and clicking the `Update Calendar' button.
+
+ Users can also subscribe to events by clicking the `notify me of changes to this event' link on the event page. If you place the box {\bf event\_notify} on a page template, it will appear to let the user know that the event has changed since they last looked at it.
+
+ \subsubsection{Event RSVP}
+ \label{features-calendar-rsvp}
+
+ Each event tracks RSVPs and volunteers (if volunteers are requested when the event is submitted). The event owner can see who has indicated via the RSVP form that they are coming, and whether or not they have volunteered. The event owner is emailed if somebody indicates that they would like to volunteer so they can get in touch and start planning duties. The volunteer form lets users know that their `realemail' will be emailed to the event owner for this purpose prior to them submitting it.
+
+ The RSVP list is sorted with volunteers at the top and everybody else below, to help the event organizer.
+
+ \subsubsection{Event stories}
+ \label{features-calendar-stories}
+
+ Stories can be attached to particular events, to provide updates, more details, summaries, and a place to talk about the event both before and after the fact. They are displayed below the event details on the event's page, and are filed in the `events' section. Users must have the {\bf story\_post} perm (\ref{perm-story-post}) to post stories to events, and: the event must be set to allow anybody to post stories to it, the user is on the invitation list, or the user is the owner of the event.
+
+ The `events' section should be listed in the Site Control {\bf sections\_excluded\_from\_all} so event stories do not appear on the `Everything' page or in the site's RSS feed. The section's `story post' permissions should be set to `Hide' for all groups so it does not appear in the normal story submit form, only when posting a story specifically to a particular event.
+
+ By placing {\bf \latexhtml{$\vert$}{|}BOX,event,\latexhtml{$\vert$}{|}sid\latexhtml{$\vert$}{|}\latexhtml{$\vert$}{|}} in the story\_summary block, stories associated with events will have a link added to the relevant event's page. All other stories will have nothing added.
\subsection{Site Layout and Themes}
Index: admin-tools.tex
===================================================================
RCS file: /cvs/scoop/scoop/doc/sag-tex-src/admin-tools.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** admin-tools.tex 16 Jun 2004 18:03:59 -0000 1.3
--- admin-tools.tex 27 Feb 2005 13:28:36 -0000 1.4
***************
*** 355,358 ****
--- 355,372 ----
This should be reserved for administrators only.
+ \subsubsection{ad\_opt\_out}
+ \label{perm-ad-opt-out}
+
+ Determines whether or not a user can hide ads shown through the Advertising Admin Tool (\ref{admin-tools-advertising}). Users with this perm have an extra user preference on their interface prefs page, if the ad system is in use.
+
+ This should be reserved for registered users only.
+
+ \subsubsection{admin\_search}
+ \label{perm-admin-search}
+
+ Determines whether or not a user can use the admin tools search engine. This searches the content and description of blocks, boxes, special pages, and vars, subject to the edit permission for each of those (i.e., somebody who doesn't not have permission to edit boxes will not be able to search boxes).
+
+ This should be reserved for administrators only.
+
\subsubsection{allow\_subscription}
\label{perm-allow-subscription}
***************
*** 371,374 ****
--- 385,393 ----
This may be given to any user group.
+ \subsubsection{bypass\_safe\_mode}
+ \label{perm-bypass-safe-mode}
+
+ Determines whether or not a user can use the site normally when the {\bf safe\_mode} Site Control is on. Users without this permission will get an error message.
+
\subsubsection{comment\_delete}
\label{perm-comment-delete}
***************
*** 392,395 ****
--- 411,428 ----
This is generally given to all registered accounts, and not Anonymous users. A restricted group without this permission can be created for people who abuse their rating privileges by consistently rating spam high or one person's comments low.
+ \subsubsection{comment\_remove}
+ \label{perm-comment-remove}
+
+ Determines whether or not a user can `remove' comments (replace comment content and subject with text from the blocks removed\_comment\_body and removed\_comment\_subject, respectively).
+
+ This should be reserved for administrators only.
+
+ \subsubsection{comment\_toggle}
+ \label{perm-comment-toggle}
+
+ Determines whether or not a user can switch a comment between `topical' and `editorial' modes. Generally, editorial mode comments are not shown once a story is posted, unless the user has specifically chosen to see them.
+
+ This should be reserved for administrators only.
+
\subsubsection{cron\_admin}
\label{perm-cron-admin}
***************
*** 413,416 ****
--- 446,469 ----
This should be reserved for trusted administrators only.
+ \subsubsection{edit\_calendars}
+ \label{perm-edit-calendars}
+
+ Determines whether or not a user can edit calendars other than their own, including site-wide calendars, using the Calendars Admin Tool (\ref{admin-tools-calendars}).
+
+ This should be reserved for administrators only.
+
+ %\subsubsection{edit\_event\_properties}
+ %\label{perm-edit-event-properties}
+
+ %This determines whether or not a user can edit the fields which are used on the event submission form, using
+ % FIXME ??? this isn't used in the code or a box. Must have been added then discarded during development.
+
+ \subsubsection{edit\_events}
+ \label{perm-edit-events}
+
+ Determines whether or not a user can edit events other than their own. Note that a calendar owner can edit events submitted by another user to their calendar because the event `belongs to' the calendar as well.
+
+ This should be reserved for administrators only.
+
\subsubsection{edit\_groups}
\label{perm-edit-groups}
***************
*** 434,437 ****
--- 487,497 ----
This should be reserved for administrators only.
+ \subsubsection{edit\_my\_stories}
+ \label{perm-edit-my-stories}
+
+ Determines whether or not a user can edit their own stories even when out of the edit queue. The perm edit\_own\_story (\ref{perm-edit-own-story}) is for the edit queue. This permission is moot for users without story\_post (\ref{perm-story-post}).
+
+ This should be reserved for registered users.
+
\subsubsection{edit\_ops}
\label{perm-edit-ops}
***************
*** 441,448 ****
This should be reserved for administrators only.
\subsubsection{edit\_own\_story}
\label{perm-edit-own-story}
! Determines whether or not a user can submit a story into the editing queue. This permission depends on the perms moderate (\ref{perm-moderate}) and story\_post (\ref{perm-story-post}).
This should be reserved for registered users.
--- 501,515 ----
This should be reserved for administrators only.
+ \subsubsection{edit\_own\_calendar}
+ \label{perm-edit-own-calendar}
+
+ Determines whether or not a user can create and edit their own calendar. Users can have only one calendar.
+
+ This should be reserved for registered users.
+
\subsubsection{edit\_own\_story}
\label{perm-edit-own-story}
! Determines whether or not a user can submit a story into the editing queue. This permission depends on the perms moderate (\ref{perm-moderate}) and story\_post (\ref{perm-story-post}). To allow users to edit their stories outside of the edit queue, see edit\_my\_stories (\ref{perm-edit-my-stories}).
This should be reserved for registered users.
***************
*** 455,458 ****
--- 522,532 ----
This should be reserved for administrators only.
+ \subsubsection{edit\_prefs}
+ \label{edit-prefs}
+
+ Determines whether or not a user can manage user preferences using the User Preferences Admin Tool (\ref{admin-tools-user-preferences}).
+
+ This should be reserved for administrators only.
+
\subsubsection{edit\_sections}
\label{perm-edit-sections}
***************
*** 500,504 ****
\label{perm-hotlist}
! Determines whether or not a user can hotlist a favourite story.
This should be reserved for registered users. It makes no sense for anonymous users.
--- 574,578 ----
\label{perm-hotlist}
! Determines whether or not a user can hotlist (\ref{features-hotlist}) a favourite story.
This should be reserved for registered users. It makes no sense for anonymous users.
***************
*** 595,598 ****
--- 669,679 ----
This is usually reserved for registered users, but some sites may choose to allow the Anonymous group to post stories as well.
+ \subsubsection{story\_time\_update}
+ \label{perm-story-time-update}
+
+ Determines whether or not the user can use the `reset timestamp to now' checkbox on the story edit form.
+
+ This should be reserved for administrators.
+
\subsubsection{suballow\_group\_change}
\label{perm-suballow-group-change}
***************
*** 609,612 ****
--- 690,700 ----
This is usually reserved for registered users.
+ \subsubsection{submit\_event}
+ \label{perm-submit-event}
+
+ Determines whether or not a user can submit events to calendars which allow event submission.
+
+ This is generally given to all groups, or all groups except Anonymous.
+
\subsubsection{submit\_rdf}
\label{perm-submit-rdf}
***************
*** 630,633 ****
--- 718,728 ----
This should be reserved for administrators.
+ \subsubsection{update\_own\_event}
+ \label{perm-update-own-event}
+
+ Determines whether or not a user can edit their own events after submission.
+
+ This should be reserved for registered users.
+
\subsubsection{upload\_admin}
\label{perm-upload-admin}
***************
*** 1035,1038 ****
--- 1130,1238 ----
Macros cannot be created or deleted from the category screen.
+ \subsection{User Preferences}
+ \label{admin-tools-user-preferences}
+
+ All user preferences (except user group, real email, and password) can be customized, modified, and enabled in the User Preferences Admin Tool. Many of the built-in user preferences are {\bf required by Scoop and should never be deleted}. If you don't want your users to change those preferences, set the default value however you like and disable the preference, but that default value is often required.
+
+ User preferences can be public or private, required or optional, available to some groups but not others, allow or not allow HTML, have a specific validation process or allow any content. All of these options are set in this admin tool.
+
+ Like most admin tools, the form begins with the 'save' and 'get' buttons, and a selectbox for choosing which user preference to fetch for editing.
+
+ \begin{description}
+ \item[Delete] This checkbox is just under the first selectbox and over on the left, and should generally not be used for Scoop's built-in preferences. As mentioned above, most of the built-in preferences are required for correct operation of the site, and should be disabled instead of deleted if you don't want users to have access to them. Checking this and saving will cause the selected preference to be removed from the database.
+ \item[Name] Like most admin tools, if the selectbox is set to `Add New', a new item is created with the name entered here; to update an existing preference, the selectbox and the name field must match.
+ \item[Enabled] The enabled checkbox allows you to make a preference available or not globally.
+ \item[Title] This is displayed to the user as the title of the user preference. It should be a short but descriptive name.
+ \item[Description] If the title is not enough to explain the preference, additional instructions can be placed in this field. The description is displayed according to the `Template' chosen (below).
+ \item[Default Value] If the user has not set a value for this preference, the default value is used. This should be a value that validates correctly according to the validation filters set below, although it is not actually filtered here.
+ \end{description}
+
+ The next portion of the form lets you specify the display settings for this preference.
+
+ \begin{description}
+ \item[Shown on signup page?] This determines whether or not a particular preference is required or not, and whether or not it is displayed on the newuser page when accounts are first created. The options are:
+ \begin{itemize}
+ \item {\bf No} This preference is optional and does not need to be shown on the signup page
+ \item {\bf Yes} This preference is optional and should be shown on the signup page
+ \item {\bf Yes, and it's required} This preference is required and thus must be shown on the signup page to collect an initial value. This preference can never be saved blank, it must always have a value that validates as specified below
+ \end{itemize}
+ \item[Preferences page] Which preferences page to display this user preference on. The pages included by default are: User Info, Interface, and Comments. You can create new preferences pages simply by entering a value which does not yet exist in this field. The menu used for navigating between preferences pages will detect new pages and add them to its list. The preferences page named 'Protected' (display title of `Email and Password') should not be used here, as it is reserved for `protected settings', those settings which define a user: username, group, password, and realemail.
+ \item[Order on page] What order to display this preference in, in relation to the other preferences on the same page. If you enter an order number which is already in use, the conflicting number and all preferences with order numbers higher than this are shifted down the page by one place.
+ \item[Control to display] The form element which will collect the data for this preference. The form element should have a name setting identical to the preference name, and a default value of \latexhtml{$\vert$value$\vert$}{|value|}, so that the user's current preference is correctly displayed. This can also be a box call; for selectboxes, radio buttons, and checkboxes it typically is, so that the correct item is selected. There are generic boxes for two of the three types which can often be used for quite a few of the preferences: pref\_selectbox, which takes as its parameters the preference name, the current value, and the list of possible values and produces a selectbox with the current item selected; and pref\_checkbox, which takes as its parameters the preference name and the current value and produces a checkbox, selected or not as appropriate.
+ \item[Template] A block whose name ends in `\_pref' and which formats the title, description, and control appropriately. See the block description for the two templates included by default for more information.
+ \item[Visible on public user info page?] Determines whether or not the value of this preference will be displayed to any user who requests the user info page. If visible, its display is also subject to the `Perm to view' setting (below).
+ \item[Formatting to apply to value] If you would like to format the value of this preference a certain way when it is displayed on the public user info page, you should specify the HTML here, and place \latexhtml{$\vert$value$\vert$}{|value|} where you want the value placed. For example, the homepage preference formats the value as a hyperlink.
+ \end{description}
+
+ The next portion of the form lets you specify what permissions or site controls must be satisfied before the preference can be used, if it is enabled.
+
+ \begin{description}
+ \item[Site Control] The site control that must be true for this preference to be available. For example, if you are not using Scoop's ad server at all, the site control `use\_ads' would be false, and the preference `ad\_open\_new\_win' would be irrelevant---and thus shouldn't be shown.
+ \item[Perm to view] If a user requires a specific permission before being allowed to see a preference, that permission is selected here. For example, the `admin\_notes' preference is visible on the user's public info page, but only to admins who have permission to edit users.
+ \item[Perm to edit] If a user requires a specific permission before being allowed to change a preference, that permission is selected here. As above, only admins can change the `admin\_notes' preferences.
+ \item[Trusted User status] This preference is only available to `trusted users' (\ref{features-mojo}).
+ \end{description}
+
+ The last portion of the form deals with input validation; what values are permitted.
+
+ \begin{description}
+ \item[HTML allowed] This determines whether or not HTML is permitted in the preference. If it is permitted, the value is run through the HTML filter. The HTML allowed can be specified in the `allowed\_html' block; the context for user preferences is `pref' (see the block description for details).
+ \item[Field length] This determines the maximum length of the value. If left blank or set to zero, no limit is imposed (although the database has a limit of 64kb).
+ \item[Box or regular expression] This filters the preference for acceptable values. This can be either a box or a regular expression. For a regular expression, simply enter the regex in this field, with pipes escaped: for example, \verb!^(on\|off)$! is used for all checkboxes, as they have only two possible valid values, on or off. To use a box for advanced filtering, such as the `start\_page' preference uses to allow any defined section as a valid value, enter the box call without the surrounding pipes: \verb!BOX,boxid[,args]!. The boxes that perform validation are called with the following arguments: the name of the preference, the value the user tried to save, then any of the optional arguments listed in this field after the box ID. These boxes should only return a value if they encounter an error; a blank return value indicates success, and the value filtered will be saved.
+ \end{description}
+
+ \subsection{Calendars}
+ \label{admin-tools-calendars}
+
+ The calendars admin tool is where you can manage all calendars (\ref{features-calendar}), events, and define which fields are used for the event form.
+
+ There are three tools on this admin page: Calendar List, Event List, and Event Properties. The calendar list contains links to the edit form for every calendar in the system, and allows you to create additional site-wide calendars (those without an owner). The event list contains links to the edit form for every event in the system, much as the story list and poll list do for their respective features. The event properties allows you to define the fields Scoop will use to collect information about events.
+
+ \subsubsection{Calendar List}
+
+ This is a basic list of calendars, with three columns: the calendar title (linked to the calendar), the calendar owner, and the admin actions available (delete and edit). Site-wide calendars have no owner, and only admins with the {\bf edit\_calendars} perm (\ref{perm-edit-calendars}) can edit them. User calendars can also be edited by their owners.
+
+ Below the list is a form with which site-wide calendars can be created. There are only three fields: a title and two permissions fields. A fourth field, for the description, is available on the calendar edit form (\ref{admin-tools-calendars-edit-form}). The two permission fields determine who can see the calendar and the events contained in it, and who can submit events to the calendar.
+
+ \subsubsection{Event List}
+ \label{admin-tools-calendars-event-list}
+
+ The event list is a three-column list which summarizes all events in the system.
+
+ The first column contains the event title, linked to the event page, with an edit link if the current user can edit that event; the second column contains the nickname of the user who submitted the event; the third column contains a list of calendars the event is displayed in, linked to the calendar, with an edit link if the current user can edit that calendar and the name of the calendar owner if it's a user calendar. One calendar in the list will have an asterisk next to it; this indicates the calendar the event takes its permissions from (its `primary' calendar).
+
+ \subsubsection{Event Properties}
+ \label{admin-tools-calendars-event-properties}
+
+ The event submission and editing form is built based on the event properties defined here. Like most admin tools forms, it starts with `Get' and `Save' buttons and a selectbox to choose which item to edit.
+
+ \begin{description}
+ \item[Property ID] The internal name of the event field.
+ \item[Title] The display title for the event field.
+ \item[Format on event page] On the single event information page, this is the HTML used to format whatever value a user enters into this field when submitting an event. If left blank, the value is displayed as-is. If anything is entered, \latexhtml{$\vert$}{|}value\latexhtml{$\vert$}{|} is replaced with the value entered by the user, and \latexhtml{$\vert$}{|}eid\latexhtml{$\vert$}{|} by the event's ID.
+ \item[Format in calendar view] As above, but used in the monthly, weekly, or daily calendar view.
+ \item[Enabled] This checkbox determines whether or not the event field is used. This is a global toggle.
+ \item[Required] This checkbox determines whether or not the event field must be filled in when an event is submitted or edited.
+ \item[HTML allowed] This checkbox determines whether or not the value entered by the user is filtered through the HTML filter. If HTML is permitted, the allowed\_html block defines what HTML is allowed. The context for this field is `event'. See the block description for allowed\_html for details.
+ \item[Property is a date] This checkbox determines whether or not this event field is a date. Events are displayed on the calendar for these additional date fields as well as the start and end dates.
+ \item[Display order] What order to display this event field in, in relation to the other fields. If you enter an order number which is already in use, the conflicting number and all fields with order numbers higher than this are shifted down the page by one place.
+ \item[Form field] The block used to format the form field on the event submit/edit form. These are blocks whose names begin with \verb!event_property_!. See the descriptions for the blocks for more information.
+ \item[Validation regex] A perl regular expression the value entered by the user is compared to. Pipes in the regular expression must be escaped. Leave this blank if you don't want to use a regex for validation.
+ \item[This property requires] If this event field is used, the field named here must also be used. This is a good way to make a property `partially required'---for example, by default the `address' event field requires the `city' field, so even though neither of them are marked as required by the checkbox above, if an address is entered, a city must also be entered.
+ \item[Description] The event field description shown on the event submit/edit form. For when the title alone isn't descriptive enough.
+ \end{description}
+
+ \subsubsection{Edit Calendar Form}
+ \label{admin-tools-calendars-edit-form}
+
+ The Edit Calendar form has four pages: Edit Calendar Settings, Approve Submitted Events, Event List, and Invitation List.
+
+ The `Edit Calendar Settings' page is available to admins with the {\bf edit\_calendars} perm (\ref{perm-edit-calendars}) for any calendar, and to users with the {\bf edit\_own\_calendar} perm (\ref{perm-edit-own-calendar}) for their calendar only. There are only four fields: a title, a description, and two permissions fields.
+
+ The `Approve Submitted Events' page contains a list of events which have been submitted and are pending approval by the calendar owner or site admin. The calendar owner can select several items by marking their checkboxes, then approving (Approve for display) or rejecting (Do not display) that group of events by choosing the appropriate radio button and clicking `Moderate'.
+
+ The `Event List' page is a four-column list which summarizes all events attached to the current calendar. The first column contains the event title, linked to the event; the second column contains the nickname of the user who submitted the event, the third column contains the event date, and the fourth column contains action links (such as `edit') depending on what permissions the current user has.
+
+ The `Invitation List' page lets you specify who may see or submit events to your calendar, if you have set either of the two calendar permission settings to `Only people on the invitation list'. Users are added one at a time by nickname, and can be removed via a `remove' link after their name once they are in the invitation list.
\subsection{Search}
Index: intro.tex
===================================================================
RCS file: /cvs/scoop/scoop/doc/sag-tex-src/intro.tex,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** intro.tex 28 Mar 2004 22:14:22 -0000 1.2
--- intro.tex 27 Feb 2005 13:28:36 -0000 1.3
***************
*** 3,13 ****
Scoop is a web-based program primarily used for running community-based weblog-style sites. However, because it is extremely customizable, it can be used for purposes ranging from simple content management with no comments or reader submissions to magazine-style publishing to the discussion site mentioned above. Nearly all customization can be done through the web interface.
! This document covers version 1.0 of Scoop.
! %This document covers the CVS version of Scoop as of the date at the bottom of the page. If you are using a prior numbered release or an older version of the CVS code, you may not be able to find some of the features described here.
\subsection{Read This Section First!}
! If you don't, you'll look like a tit when you ask a question that's answered here. The entire purpose if this section is to stop you from doing that.
First, a few things you should know about Scoop.
--- 3,13 ----
Scoop is a web-based program primarily used for running community-based weblog-style sites. However, because it is extremely customizable, it can be used for purposes ranging from simple content management with no comments or reader submissions to magazine-style publishing to the discussion site mentioned above. Nearly all customization can be done through the web interface.
! %This document covers version 1.1 of Scoop.
! This document covers the CVS version of Scoop as of the date at the bottom of the page. If you are using a prior numbered release or an older version of the CVS code, you may not be able to find some of the features described here.
\subsection{Read This Section First!}
! This section answers the most common questions about Scoop which are seen by the developers. Please read this section first.
First, a few things you should know about Scoop.
***************
*** 15,30 ****
\item There are {\bf no .html files} for you to edit. All customization is done through the web interface.
\item You must have {\bf root or root-equivalent} access to the web server. If you don't and can't get it, there are a few companies that will host a Scoop site for you.
! \item You will need to either know a lot about Apache or be prepared to learn.
! \item If you have Scoop running but {\bf can't create accounts}, there's probably a problem with your mail server. Check that your SMTP variable is set correctly; if so, make sure that the SMTP server referenced allows relays from the webserver.
! \item If Scoop starts but you {\bf can't log in}, or you can {\bf log in but get ``Permission Denied''} when you try to do something, check the cookie\_host setting in the Scoop section of your Apache config file. It should match the string you are currently using as a domain name to access your Scoop site, and it must have at least two dots in it. If you are using www.example.com you may omit the `www' and use just .example.com but if you are using test.example.com do {\em not} use .test.example.com because that extra period screws things up for some browsers. If you don't have a domain name, you can use the IP address as your cookie\_host and as long as you then access your Scoop site using the IP address it will work, but when you get a domain name you'll have to remember to change it.
\end{itemize}
Scoop has a lot of dependencies, and if any of them aren't set up just right, Scoop will not work, or will not work properly.
! To start with, though it sounds small, you need the {\bf full expat}. Scoop will run deceptively well without it, but anything RDF (both fetching headlines from other sites and producing your own headline feed) will not work. To add RDF later, you'll basically need to reinstall from scratch, as several things need expat at compile-time. See section~\ref{install-require} for more details.
! Scoop requires {\bf Apache 1.3.x with mod\_perl}, as it is a mod\_perl program. If Scoop does nothing but give you a directory listing and you're {\em sure} you set it up properly, you probably don't have mod\_perl working. We strongly recommend that you compile this yourself as described in section~\ref{install-apache-modperl}, as {\bf packaged versions tend not to work} with Scoop properly. The mod\_perl may be compiled into Apache, or loaded as a DSO (dynamic shared object).
! For those running Apache 2.x, sorry; if you want to run Scoop you'll have to downgrade, as Scoop has not yet been ported to mod\_perl 2.0 yet.
Scoop requires {\bf MySQL 3.22 or higher} (including 4.0) to provide its database. There isn't really any special configuration required for Scoop, just follow the mySQL install instructions. Packaged versions work fine. As long as you can log in and get at the database from the webserver (Scoop and the db can be on separate machines if you like) you're fine.
--- 15,31 ----
\item There are {\bf no .html files} for you to edit. All customization is done through the web interface.
\item You must have {\bf root or root-equivalent} access to the web server. If you don't and can't get it, there are a few companies that will host a Scoop site for you.
! \item You will need to either know a lot about Apache or be prepared to learn. If you don't and don't want to, there are a few companies that will host a Scoop site for you.
! \item `apachectl restart' or `apachectl graceful' won't work, despite the Apache documentation's insistence otherwise. They do not free the memory used by Scoop for its cache; if you don't do a full `apachectl stop' and wait for it to terminate completely before doing an `apachectl start', your Scoop install will still have the old cache running and you will get some very very strange effects if you change anything in the database (such as during an upgrade). Some of these very strange effects can make you think that {\bf Scoop broke during an upgrade}.
! \item If you have Scoop running but {\bf can't create accounts}, there's probably a problem with your mail server. Check that your SMTP settings are correct; if so, make sure that the SMTP server referenced allows your web server to relay through it.
! \item If Scoop starts but you {\bf can't stay logged in}, or you can {\bf log in but get ``Permission Denied''} when you try to do something, check the cookie\_host setting in the Scoop section of your Apache config file. It should match the string you are currently using as a domain name to access your Scoop site, and it must have at least two dots in it. If you are using www.example.com you may omit the `www' and use just .example.com but if you are using test.example.com do {\em not} use .test.example.com because that extra period screws things up for some browsers. If you don't have a domain name, you can use the IP address as your cookie\_host and as long as you then access your Scoop site using the IP address it will work, but when you get a domain name you'll have to remember to change it.
\end{itemize}
Scoop has a lot of dependencies, and if any of them aren't set up just right, Scoop will not work, or will not work properly.
! To start with, though it sounds small, you need the {\bf full expat}. Scoop will run deceptively well without it, but anything RDF (both fetching headlines from other sites and producing your own headline feed) will not work. To add RDF later, you'd basically need to reinstall from scratch, as several things need expat at compile-time. See section~\ref{install-require} for more details.
! Scoop requires {\bf Apache 1.3.x with mod\_perl}, as it is a mod\_perl program. If Scoop does nothing but give you a directory listing and you're {\em sure} you set it up properly, you probably don't have mod\_perl working. We strongly recommend that you compile this yourself as described in section~\ref{install-apache-modperl}, as {\bf many packaged versions don't work} with Scoop properly. The mod\_perl may be compiled into Apache, or loaded as a DSO (dynamic shared object).
! For those running Apache 2.x, sorry; if you want to run Scoop you'll have to downgrade, as Scoop has not yet been ported to mod\_perl 2.0 yet. Some work has been done to make it work with Apache 2, but it is not considered suitable for a live site.
Scoop requires {\bf MySQL 3.22 or higher} (including 4.0) to provide its database. There isn't really any special configuration required for Scoop, just follow the mySQL install instructions. Packaged versions work fine. As long as you can log in and get at the database from the webserver (Scoop and the db can be on separate machines if you like) you're fine.
***************
*** 38,47 ****
\subsection{System Requirements}
! Scoop should run on any OS that Apache with mod\_perl and mySQL will run on, though some take extra tweaking. It has been run on basically every flavour of Linux, some other Unixes, Mac OS X, and Windows 2000 and XP. There are currently issues with sending email (required to create new accounts) under Windows; the development team is working on sorting that out.
The computer power you need will depend directly on the number of hits your site gets and especially how big your database is. Once the database indexes get too large for available memory, performance goes all to hell and one person on dialup can DoS the site easily. That's where you either get more RAM (if practical) and/or turn on archiving.
\begin{itemize}
! \item A P133/64Mb RAM can run a very low traffic site with a small database, and still work as a desktop computer.
\item A dual 800MHz PIII/1Gb RAM can run a site that gets between 70 thousand and 90 thousand hits per day and has a 450Mb database.
\item Two beefy load-balanced Scoop servers and a database server with 1Gb RAM will handle a site that gets about 180,000 hits per day and has a big database, but only if story and comment archiving are active and most stories and comments are archived.
--- 39,48 ----
\subsection{System Requirements}
! Scoop should run on any OS that Apache with mod\_perl and mySQL will run on, though some take extra tweaking. It has been run on basically every flavour of Linux, some other Unixes, Mac OS X, and Windows 2000 and XP. There are currently issues with sending email (required to create new accounts) under Windows.
The computer power you need will depend directly on the number of hits your site gets and especially how big your database is. Once the database indexes get too large for available memory, performance goes all to hell and one person on dialup can DoS the site easily. That's where you either get more RAM (if practical) and/or turn on archiving.
\begin{itemize}
! \item A P133/64Mb RAM can run a very low traffic site with a small database, and still work as a desktop computer, although it is sluggish.
\item A dual 800MHz PIII/1Gb RAM can run a site that gets between 70 thousand and 90 thousand hits per day and has a 450Mb database.
\item Two beefy load-balanced Scoop servers and a database server with 1Gb RAM will handle a site that gets about 180,000 hits per day and has a big database, but only if story and comment archiving are active and most stories and comments are archived.
***************
*** 55,62 ****
If you need help with anything Scoop-related, the first place you want to look is in this document. After that, you can take a look at section~\ref{faq} for the FAQ and past problem descriptions to see if your question is answered there. There's also the scoop-help and scoop-dev mailing lists; the first is for users and general questions about Scoop, and the second is for developers to discuss new features.
! You can subscribe at \hturl{http://lists.sourceforge.net/lists/listinfo/scoop-help} or \hturl{http://lists.sourceforge.net/lists/listinfo/scoop-dev} and read the archives at \hturl{http://sourceforge.net/mailarchive/forum.php?forum=scoop-help} or \hturl{http://sourceforge.net/mailarchive/forum.php?forum=scoop-dev} to see if your question has already been asked and answered.
Actually, if you run Scoop it's a good idea to subscribe to scoop-help even if you don't have a problem, because then you get announcements about updates to scoop and how to use them. It's a very low traffic list.
! If you've searched all of the above and still can't figure it out, you can go to the slashnet IRC server (irc.slashnet.org) and join channel \#scoop to talk to the developers. If you do, you may have to be patient; many of the developers idle there all the time, and sometimes forget to indicate that they're away. If you stick around, someone will eventually look at their chat window and realize there's a question waiting to be answered.
--- 56,63 ----
If you need help with anything Scoop-related, the first place you want to look is in this document. After that, you can take a look at section~\ref{faq} for the FAQ and past problem descriptions to see if your question is answered there. There's also the scoop-help and scoop-dev mailing lists; the first is for users and general questions about Scoop, and the second is for developers to discuss new features.
! You can subscribe at \hturl{http://lists.kuro5hin.org/mailman/listinfo/scoop-help} or \hturl{http://lists.kuro5hin.org/mailman/listinfo/scoop-dev} and read the archives at \hturl{http://lists.kuro5hin.org/pipermail/scoop-help/} or \hturl{http://lists.kuro5hin.org/pipermail/scoop-dev} to see if your question has already been asked and answered.
Actually, if you run Scoop it's a good idea to subscribe to scoop-help even if you don't have a problem, because then you get announcements about updates to scoop and how to use them. It's a very low traffic list.
! If you've searched all of the above and still can't figure it out, you can go to the slashnet IRC server (irc.slashnet.org) and join channel \#scoop to talk to the developers. If you do, you may have to be patient; many of the developers idle there all the time, and sometimes forget to indicate that they're away. If you ask a question then stick around, someone will eventually look at their chat window and realize there's a question waiting to be answered.