Commit info for scoop/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:
Updated documentation to 1.0 release version.
Index: admin-tools.tex
===================================================================
RCS file: /cvs/scoop/scoop/doc/sag-tex-src/admin-tools.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -r1.1 -r1.2
14a15,26
> %\htmladdimg{newstory.jpg}
> %\includegraphics[width=5in]{newstory}
>
> %\begin{figure}[hp]
> % \label{new-story-fig}
> % \caption{New Story form differences}
> % \begin{rawhtml}
> % <IMG src="newstory.jpg" alt="screenshot">
> % \end{rawhtml}
> % \latex{\centering\includegraphics[width=5in]{newstory}}
> %\end{figure}
>
86,104c98
< The ``Type'' field can be one of Text, Number, Boolean, or Textarea. This determines what kind of sanity checking Scoop will do when saving the value.
<
< {\bf Text} variables can be short strings of any characters. They are used for things like the email address Scoop uses to send notices from, and the URL of the site.
<
< {\bf Number} variables must be a numeric value. They are used for things like maximum or minimum times, threshold values, and the number of fields available in a poll.
<
< {\bf Boolean} values must be either 1 (on) or 0 (off). They are used for things like turning spellchecking or advertising on or off.
<
< {\bf Textarea} values are long freeform fields. They are used for any text variable that is too long for the Text type, such as the list of permissions.
<
< The ``Select Variable'' field contains a list of every variable contained in the Site Controls. To load a variable, you would select its name here, then press the Get button above to fetch the variable's data. When adding a new variable, this must be set to ``Add New Variable''; when saving an existing variable, this must match the variable name in the ``Name'' field, below.
<
< The ``Select Categories'' field contains a list of all existing categories. When a variable has been loaded, that variable's categories are hilighted. When saving a variable, at least one of the categories should be selected (or a new category named in the ``New Category'' field below). If a variable has no selected category, it will only be visible in a list of all variables, making it rather hard to find later.
<
< The ``Name'' field contains the name of the variable, as it is used in the code. Changing the name of an existing variable is discouraged, as many variables are called by name from the code. New variables may be named anything as long as it doesn't conflict with any other variable names.
<
< The ``New Category'' field is used only when a new variable doesn't fit in any of the existing categories, or you want to add an existing variable to a newly created category. A category only exists when a variable is filed in it; by filing a variable in a new category, that category is automatically created. (Likewise, when the last variable in a category is removed, the category automatically disappears.)
<
< The ``Value'' field contains the value of the variable. It can be anything, subject to the limitations imposed by the ``Type'' field, above. This is the field most often changed, and is also the only field that can be changed when in the category screen.
---
> The fields are:
106c100,114
< The ``Description'' field contains the documentation for that particular variable. If you create a new variable, please describe it well, using the conventions described in section~\ref{vars-description-format} as much as possible.
---
> \begin{description}
> \item[Type] This determines what kind of sanity checking Scoop will do when saving the value.
> \begin{itemize}
> \item {\bf Text} variables can be short strings of any characters. They are used for things like the email address Scoop uses to send notices from, and the URL of the site.
> \item {\bf Number} variables must be a numeric value. They are used for things like maximum or minimum times, threshold values, and the number of fields available in a poll.
> \item {\bf Boolean} values must be either 1 (on) or 0 (off). They are used for things like turning spellchecking or advertising on or off.
> \item {\bf Textarea} values are long freeform fields. They are used for any text variable that is too long for the Text type, such as the list of permissions.
> \end{itemize}
> \item[Select Variable] Contains a list of every variable contained in the Site Controls. To load a variable, you would select its name here, then press the Get button above to fetch the variable's data. When adding a new variable, this must be set to ``Add New Variable''; when saving an existing variable, this must match the variable name in the ``Name'' field, below.
> \item[Select Categories] Contains a list of all existing categories. When a variable has been loaded, that variable's categories are hilighted. When saving a variable, at least one of the categories should be selected (or a new category named in the ``New Category'' field below). If a variable has no selected category, it will only be visible in a list of all variables, making it rather hard to find later.
> \item[Name] Contains the name of the variable, as it is used in the code. Changing the name of an existing variable is discouraged, as many variables are called by name from the code. New variables may be named anything as long as it doesn't conflict with any other variable names.
> \item[New Category] Used only when a new variable doesn't fit in any of the existing categories, or you want to add an existing variable to a newly created category. A category only exists when a variable is filed in it; by filing a variable in a new category, that category is automatically created. (Likewise, when the last variable in a category is removed, the category automatically disappears.)
> \item[Value] Contains the value of the variable. It can be anything, subject to the limitations imposed by the ``Type'' field, above. This is the field most often changed, and is also the only field that can be changed when in the category screen.
> \item[Description] Contains the documentation for that particular variable. If you create a new variable, please describe it well, using the conventions described in section~\ref{vars-description-format} as much as possible.
> \end{description}
159,171c167,175
< The ``Select Block'' field contains a list of every block contained in the database. To load a block, you would select its name here, then press the Get button above to fetch the block's data. When adding a new block (including copying an existing block to a different theme), this must be set to ``Add New Block''; when saving an existing block, this must match the block name in the ``Name'' field, below.
<
< The ``Select Categories'' field contains a list of all existing categories. When a block has been loaded, that block's categories are hilighted. When saving a block, at least one of the categories should be selected (or a new category named in the ``New Category'' field below). If a block has no selected category, it will only be visible in a list of all blocks, making it rather hard to find later.
<
< The ``Name'' field contains the name of the block, as it is used in the code. Changing the name of an existing block is discouraged, as many blocks are called by name from the code. New blocks may be named anything as long as it doesn't conflict with any other block names.
<
< The ``Theme'' field contains the name of the theme the block is a part of. If this field is left blank, whichever theme you are currently working in is used. New themes can be created by saving a new block with a theme name that doesn't exist. Likewise, when the last block in a theme is deleted, the theme automatically disappears.
<
< The ``New Category'' field is used only when a new block doesn't fit in any of the existing categories, or you want to add an existing block to a newly created category. A category only exists when a block is filed in it; by filing a block in a new category, that category is automatically created. Likewise, when the last block in a category is deleted, the category automatically disappears.
<
< The ``Value'' field contains the value of the block. It can be anything, keeping in mind of course what its intended use is. This is the field most often changed, and is also the only field that can be changed when in the category screen.
<
< The ``Description'' field contains the documentation for that particular variable. If you create a new variable, please describe it well, using the conventions described in section~\ref{blocks-description-format} as much as possible.
---
> \begin{description}
> \item[Select Block] Contains a list of every block contained in the database. To load a block, you would select its name here, then press the Get button above to fetch the block's data. When adding a new block (including copying an existing block to a different theme), this must be set to ``Add New Block''; when saving an existing block, this must match the block name in the ``Name'' field, below.
> \item[Select Categories] Contains a list of all existing categories. When a block has been loaded, that block's categories are hilighted. When saving a block, at least one of the categories should be selected (or a new category named in the ``New Category'' field below). If a block has no selected category, it will only be visible in a list of all blocks, making it rather hard to find later.
> \item[Name] Contains the name of the block, as it is used in the code. Changing the name of an existing block is discouraged, as many blocks are called by name from the code. New blocks may be named anything as long as it doesn't conflict with any other block names.
> \item[Theme] Contains the name of the theme the block is a part of. If this field is left blank, whichever theme you are currently working in is used. New themes can be created by saving a new block with a theme name that doesn't exist. Likewise, when the last block in a theme is deleted, the theme automatically disappears.
> \item[New Category] Used only when a new block doesn't fit in any of the existing categories, or you want to add an existing block to a newly created category. A category only exists when a block is filed in it; by filing a block in a new category, that category is automatically created. Likewise, when the last block in a category is deleted, the category automatically disappears.
> \item[Value] Contains the value of the block. It can be anything, keeping in mind of course what its intended use is. This is the field most often changed, and is also the only field that can be changed when in the category screen.
> \item[Description] field contains the documentation for that particular variable. If you create a new variable, please describe it well, using the conventions described in section~\ref{blocks-description-format} as much as possible.
> \end{description}
210,216c214,219
< The ``TID'' is the topic ID, a short alphanumeric string used to uniquely identify the topic.
<
< The ``Dimensions'' are used when displaying the image in a story. Enter the pixel width in the first box and the pixel height in the second.
<
< The ``Alt Text'' is used both as the alt attribute when displaying the topic icon and also as the descriptive name in the select box when a new story is being posted.
<
< The ``Image Name'' is the filename of the topic image, with no path information. Scoop assumes that all topic images are in the subdirectory named in the variable topics of the directory named in the variable imagedir and will prepend that path to whatever image name you supply.
---
> \begin{description}
> \item[TID] The topic ID, a short alphanumeric string used to uniquely identify the topic.
> \item[Dimensions] Used when displaying the image in a story. Enter the pixel width in the first box and the pixel height in the second.
> \item[Alt Text] Used both as the alt attribute when displaying the topic icon and also as the descriptive name in the select box when a new story is being posted.
> \item[Image Name] The filename of the topic image, with no path information. Scoop assumes that all topic images are in the subdirectory named in the variable topics of the directory named in the variable imagedir and will prepend that path to whatever image name you supply.
> \end{description}
232,238c235,240
< The ``Section'' is the section ID, a short alphanumeric string used to uniquely identify the section. This shouldn't have any spaces, as it's used in the URL.
<
< The ``Display Title'' is the full name of the section, used both as a page header on the section index page and in the drop-down box on the story submission form.
<
< The ``Description'' can be used for a section-specific slogan if you like, or can just be a reminder to yourself what the section was for. If you use a section-specific slogan, you'll need to alter the box section\_title to display it.
<
< The ``Section Icon'' is the filename of the section image. Scoop prepends the directory named in the variable imagedir to this filename.
---
> \begin{description}
> \item[Section] is the section ID, a short alphanumeric string used to uniquely identify the section. This shouldn't have any spaces, as it's used in the URL.
> \item[Display Title] is the full name of the section, used both as a page header on the section index page and in the drop-down box on the story submission form.
> \item[Description] can be used for a section-specific slogan if you like, or can just be a reminder to yourself what the section was for. If you use a section-specific slogan, you'll need to alter the box section\_title to display it.
> \item[Section Icon] is the filename of the section image. Scoop prepends the directory named in the variable imagedir to this filename.
> \end{description}
260c262,266
< FIXME: needs work
---
> Subsections can allow a simple heirarchical structure for the sections on your site, if one `level' of sections isn't adequate. Subsections can also do much stranger things, such as allow you to file one story in several sections.
>
> Below the section permissions table, a list of all parent sections is displayed. If there are no parent sections, ``Top Level'' is shown; if there are, the ``path'' to the current section is shown, with the names of the parent sections links to edit that section. Below that, a table containing any child sections is shown if there are any, again with the names of the child sections as links to edit that section, and a drop-down box containing any section names that are not already marked as a parent or child section.
>
> You cannot directly add a parent section. Instead, you must go to the parent section and add a child; the parent section is automatically updated from this information.
262c268,274
< %hillct will help
---
> Sections can have multiple child sections, just as directories can have multiple subdirectories. For a simple heirarchical structure, this is all you will need. Sections can also have multiple parent sections, which tends to be rather confusing at first.
>
> The simplest case is a heirarchical structure, where each section has one parent and however many children as seems appropriate. Each story is displayed in its particular section and on the front page as appropriate. The only real difference between this case and the normal `flat' structure in which subsections aren't used at all is that Scoop can generate links to the parent sections when in a child section's index page.
>
> Child sections have two properties that make more complicated structures possible. As mentioned above, a child section can have two parents (or, two sections can claim the same section as their child). The ``inheritable'' property found in the table of child sections when editing a parent section allows stories filed in the child section to also appear in the parent section's index listing. (This is the reverse of normal inheritance, in which the child gets whatever the parent has.) Combined with a child section having two or more parents, a single story can be effectively filed in multiple sections.
>
> The ``invisible'' property makes the name of the child section disappear from the generated heirarchy when viewing its children's index pages. If you write a dynamic menu/submenu for your site's sections, you can test this property and not display invisible subsections in the menu structure. Invisible subsections are primarily used when they are also inheritable to more than one parent section and you don't want them to show in a menu structure.
271,277c283,289
< The ``Page ID'' is a short alphanumeric string used to uniquely identify the special page. This shouldn't have any spaces in it, as it's used primarily in the URL.
<
< The ``Title'' is the full title of the page, displayed in the page header.
<
< The ``Description'' is not used anywhere else, and is just to show the admin(s) what the page is for, in a few words.
<
< The ``Content'' is the special page itself. Any HTML markup may be used here, but full HTML header and footer information isn't required, as the contents of this textarea are inserted into the |CONTENT| special block in a page template.
---
> \begin{description}
> \item[Delete this page] This checkbox, if checked, will cause the page to be deleted when saved. It is only displayed when a page is loaded into the form.
> \item[Page ID] is a short alphanumeric string used to uniquely identify the special page. This shouldn't have any spaces in it, as it's used primarily in the URL.
> \item[Title] is the full title of the page, displayed in the page header.
> \item[Description] is not used anywhere else, and is just to show the admin(s) what the page is for, in a few words.
> \item[Content] is the special page itself. Any HTML markup may be used here, but full HTML header and footer information isn't required, as the contents of this textarea are inserted into the \latexhtml{$\vert$}{|}CONTENT\latexhtml{$\vert$}{|} special block in a page template.
> \end{description}
284c296,330
< FIXME
---
> The Boxes Admin Tool is where you manage boxes. To use this admin tool, you must have the edit\_boxes perm (\ref{perm-edit-boxes}) active for your group.
>
> {\bf WARNING:} any user with permission to edit boxes can run arbitrary code on the server, with Apache's user and group permissions. Be careful when giving this permission to other people.
>
> Boxes are bits of perl code that have full access to all of Scoop's data and subroutines. They range in complexity from the {\bf user\_box} which checks a few permissions to determine which items to display in the user's customized menu, to a set of boxes which handle the payment processing for advertisements and subscriptions and activate those items once they are paid.
>
> Some features exist only in boxes, and likewise, entirely new features can be added using boxes without touching the underlying code. Boxes can also call external programs on the server, as can any perl script; the {\bf fortune\_box} is a simple example of this, and calls the unix `fortune' program to fetch a random quote, then formats it for display. For more information on adding features to Scoop, see section~\ref{hacking}.
>
> To edit a box, first select the desired box from the drop-down box labelled ``Box:'' then click the ``Get Box'' button next to it. The fields below will be filled in with the appropriate information.
>
> To create a new box, leave the drop-down box set to ``Select Box'' and fill in the fields below as appropriate.
>
> To save a new box or changes to an existing box, click the ``Save Box'' button at the bottom of the form.
>
> The fields are:
>
> \begin{description}
> \item[Box] is the name of the box being edited. When creating a new box, this should be ``Select Box'', and when saving any existing box, it must match the name in the ``Box ID'' field below.
> \item[Delete this box] if checked, will cause Scoop to delete the box chosen in the above drop-down box. It is only displayed if a box is loaded into the form.
> \item[Box ID] is the name of the box being edited. When saving any existing box, it must match the name in the ``Box'' field above. When creating a new box, this field must contain a value not already used for a box name.
> \item[Title] is the display title of the box, and is used in the special key `title' in the box template, unless the title is changed in the box code.
> \item[Template] is the HTML used to contain the box's output. This is a block, and can be edited in the Blocks Admin Tool (\ref{admin-tools-blocks}). The block must contain the special key `content' and may contain the special key `title'. When a box's information is loaded into the form, an edit link appears next to this field which brings you to the Blocks Admin Tool with the box template already loaded for editing.
> \item[Allow users to toggle box off] determines whether or not this box is listed in the user's display preferences. Some boxes are integral parts of the interface and shouldn't be optional, while others, like RDF feeds, are extras and make sense as optional boxes.
> \item[Description] is, as you would expect, a description of the box and what it does.
> \item[Content] is the perl code itself. Boxes can be considered standalone scripts instead of part of a mod\_perl program, as they do not need to be in a subroutine or otherwise structurally different than what you'd find in an actual standalone perl script, except they have the advantage of having full access to all of Scoop's data and functionality, through the \$S object. (For more information on the \$S object and using it, see section~\ref{hacking}, Extending Scoop's Abilities.)
> \end{description}
>
> The code in a given box can return either one or two values; the single value, or first of a pair, is placed in the special key `content' in the box template. The second value, if present, is placed in the special key `title' in the box template. If the second value is not present, the contents of the ``Title'' field above is used instead.
>
> You should return the values as an anonymous hash. That is,
>
> \begin{verbatim}
> return \{ content => \$content, title => '\$title' \}
> \end{verbatim}
>
295,301c341,346
< The ``Group ID'' is the name of the group. Since only site administrators should see the group names, there is no display name associated with a group.
<
< The ``Default New User Group'' checkbox allows you to set which group new accounts are automatically placed into. By default, this is the group Users. Only one group can have this checkbox set; if you set it for a different group, it is unset on the group it marked before.
<
< The ``Group Description'' is a description to remind the admin what the purpose of the group is, and what type of people should be in it.
<
< The ``Group Permissions'' are a series of checkboxes, one for each individual permission available on the system. All but one determine whether or not a user can perform an action, and the majority are for administrative actions.
---
> \begin{description}
> \item[Group ID] is the name of the group. Since only site administrators should see the group names, there is no display name associated with a group.
> \item[Default New User Group] checkbox allows you to set which group new accounts are automatically placed into. By default, this is the group Users. Only one group can have this checkbox set; if you set it for a different group, it is unset on the group it marked before.
> \item[Group Description] is a description to remind the admin what the purpose of the group is, and what type of people should be in it.
> \item[Group Permissions] are a series of checkboxes, one for each individual permission available on the system. All but one determine whether or not a user can perform an action, and the majority are for administrative actions.
> \end{description}
311a357,365
> \subsubsection{allow\_subscription}
> \label{perm-allow-subscription}
>
> Determines whether or not a user is permitted to buy a subscription (\ref{features-subscriptions}). Only regular users should have this permission, as buying a subscription changes the user group of the subscriber. Superusers and site editors should never have this permission.
>
> User groups created for misbehaving users should also not have this permission because they can regain the privileges they lost simply by buying the minimum subscription.
>
> This should be reserved for registered users only.
>
375,376c429,430
< \subsubsection{edit\_own\_story}
< \label{perm-edit-own-story}
---
> \subsubsection{edit\_macros}
> \label{perm-edit-macros}
378c432
< 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}).
---
> Determines whether or not a user can manage Scoop's Macros, using the Macros Admin Tool (\ref{admin-tools-macros}). This includes giving all users access to specific Scoop boxes.
380c434
< This should be reserved for registered users.
---
> This should be reserved for administrators only.
389,390c443,446
< \subsubsection{edit\_perms}
< \label{perm-edit-perms}
---
> \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}).
392c448
< FIXME: is this used? It isn't in the code and is only in the database to make it exist.
---
> This should be reserved for registered users.
456a513,519
> \subsubsection{make\_new\_accounts}
> \label{perm-make-new-accounts}
>
> Determines whether or not a user can create new accounts while still logged in. This is mainly useful when setting up a new site or creating accounts on behalf of other people.
>
> This should be reserved for the site administrator only.
>
499,503d561
< \subsubsection{show\_perms}
< \label{perm-show-perms}
<
< FIXME: is this used? It doesn't seem to be in the code, and is only in the database to make it exist.
<
510a569,582
> \subsubsection{story\_commentstatus\_select}
> \label{perm-story-commentstatus-select}
>
> Determines whether or not a user has the ability to enable or disable comment posting on a given story when posting that story through the normal story submission form. If all stories should have comments either enabled or disabled, the site control {\bf default\_commentstatus} should be used instead.
>
> Regardless of the setting of this perm, users with the {\bf story\_admin} perm (\ref{perm-story-admin}) have the ability to change a story's comment status when editing a story.
>
> \subsubsection{story\_displaystatus\_select}
> \label{perm-story-displaystatus-select}
>
> Determines whether or not a user has the ability to select the display status on a given story when posting that story through the normal story submission form. If all stories should go through the voting queue, this perm should not be given out. If certain groups should be able to by-pass the voting queue in specific sections, section permissions (\ref{sections-perms}, \ref{admin-tools-sections}) should be used instead.
>
> Regardless of the setting of this perm, users with the {\bf story\_admin} perm (\ref{perm-story-admin}) have the ability to change a story's display status when editing a story.
>
524a597,603
> \subsubsection{suballow\_group\_change}
> \label{perm-suballow-group-change}
>
> Determines whether or not Scoop can automatically change a user's group when a subscription is paid for. If a group has the perm {\bf allow\_subscription} (\ref{perm-allow-subscription}) but not this perm, the administrator will be emailed to manually change the subscriber's group when he pays for his subscription.
>
> This should never be given to Superusers, just to prevent accidents while testing your site's subscription setup. This is otherwise usually reserved for registered users.
>
538a618,624
> \subsubsection{subscription\_admin}
> \label{perm-subscription-admin}
>
> Determines whether or not a user can create and manage subscription types through the Subscriptions Admin Tool (\ref{admin-tools-subscriptions}).
>
> This should be reserved for administrators only.
>
546,552d631
< \subsubsection{upload\_content}
< \label{perm-upload-content}
<
< Determines whether or not a user may upload a text file into the extended copy of a story submission (depends on the perm story\_post (\ref{perm-story-post})) or into the content field of a special page (depends on the perm edit\_special (\ref{perm-edit-special})).
<
< This may be given to any user group.
<
559a639,645
> \subsubsection{upload\_content}
> \label{perm-upload-content}
>
> Determines whether or not a user may upload a text file into the extended copy of a story submission (depends on the perm story\_post (\ref{perm-story-post})) or into the content field of a special page (depends on the perm edit\_special (\ref{perm-edit-special})).
>
> This may be given to any user group.
>
614c700
< Below the list of feeds is a link that displays all of the feeds together, as they would appear if a user selected every single feed in his display prefs. FIXME: there's a bug in the rdf display box that doesn't check for ``all'' as a parameter, and displays none of the feeds.
---
> Below the list of feeds is a link that displays all of the feeds together, as they would appear if a user selected every single feed in his display prefs.
634c720
< The Cron Admin Tool is where you manage Scoop's scheduled tasks, those tasks which are not done in response to a user action, such as dealing with RDF feeds or cleaning up the sessions table in the database. The Cron Admin Tool is composed of two parts: a list of cron items, and the actions that can be performed on a cron item.
---
> The Cron Admin Tool is where you manage Scoop's scheduled tasks, those tasks which are not done in response to a user action, such as dealing with RDF feeds or cleaning up the sessions table in the database. The Cron Admin Tool is composed of two parts: a list of cron items, and the actions that can be performed on a cron item. This provides similar but different functionality to the Hooks Admin Tool (\ref{admin-tools-hooks}), the difference being that cron items are run on a timed basis, while hooks are run based on the activities of users and administrators.
644c730
< The third column indicates whether or not the cron is a box. Some cron items have code built into Scoop, and some run a box. (See section~\ref{features-expandable}.)
---
> The third column indicates whether or not the cron is a box. Some cron items have code built into Scoop, and some run a box. (See section~\ref{hacking}.)
648c734
< The fifth column is the interval at which the cron should run. The format is <number><unit>; for example, to run a cron once a day you would enter 1d, and to run it every 5 minutes, you would enter 5m. The possible units are s (second), m (minute), h (hour), d (day), w (week), M (month), Y (year).
---
> The fifth column is the interval at which the cron should run. The format is \latexhtml{$<$}{<}number\latexhtml{$>$}{>}\latexhtml{$<$}{<}unit\latexhtml{$>$}{>}; for example, to run a cron once a day you would enter 1d, and to run it every 5 minutes, you would enter 5m. The possible units are s (second), m (minute), h (hour), d (day), w (week), M (month), Y (year).
768,769c854,855
< \item[Ad Position (integer)] A number corresponding to an ad location. Ad locations are passed as a parameter to the show\_ad box (|BOX,ad\_box,1|). If the number is not given, ``1'' is assumed. You can use this parameter to set up different types of ads in different locations. Any number of ad types can share an ad position; they are rotated in the same queue. Any number of physical locations in the page can also share an ad position; they pull their ad text from the same queue. A given ad type cannot be shared across different ad positions, however.
< \item[Maximum number of characters to allow in the <field> field of this ad type] Depending on which fields you have placed in the ad template, there could be a number of these lines. Enter the number of characters you would like to allow for each field.
---
> \item[Ad Position (integer)] A number corresponding to an ad location. Ad locations are passed as a parameter to the show\_ad box (\latexhtml{$\vert$}{|}BOX,ad\_box,\latexhtml{$\vert$}{|}). If the number is not given, ``1'' is assumed. You can use this parameter to set up different types of ads in different locations. Any number of ad types can share an ad position; they are rotated in the same queue. Any number of physical locations in the page can also share an ad position; they pull their ad text from the same queue. A given ad type cannot be shared across different ad positions, however.
> \item[Maximum number of characters to allow in the \latexhtml{$<$}{<}field\latexhtml{$>$}{>} field of this ad type] Depending on which fields you have placed in the ad template, there could be a number of these lines. Enter the number of characters you would like to allow for each field.
779c865
< Ops that do not exist are handed back to Apache to process as a normal directory.
---
> Ops that do not exist or are not enabled are handed back to Apache to process as a normal directory.
791a878,879
> \item[Op Aliases] Alternate names that this op recognizes as equivalent. For example, the {\bf displaystory} op has the alias {\bf story}, so by default the URL http://www.site.com/displaystory/nnnn/nn/nn/nnnn/nnnn gives the same page as http://www.site.com/story/nnnn/nn/nn/nnnn/nnnn.
> \item[URL Templates] Information on how Scoop should interpret the paths it gets, and how to turn them into CGI parameters. There can be multiple templates of varying path length. Each template should be on one line, and multiple templates should be separated by a comma. The details are below.
799a888,905
> {\bf To understand URL Templates}, the first thing you have to know is that they are generally laid out much like the paths that they are used to interpret, except the first pseudo-directory (the op) is not present in the templates. The elements between slashes are CGI parameter names (in the path that the user sees they are the parameter values), and there are various commands that allow you to customize Scoop's interpretation of the path. An overview of how to create a basic URL Template string is below the following examples.
>
> The simplest form can be found, for example, in the section op. The URL template there is {\bf /section/page/} which means that when the URL http://www.example.com/section/news/3 is requested, Scoop will first look at the section op to find out what to do with the rest of the path (first pseudo-directory) then set the CGI parameter `section' to news (second pseudo-directory), and the CGI parameter `page' to 3 (third pseudo-directory). The more familiar CGI URL, for those of you who have done web programming before, would be http://www.example.com/?op=section;section=news;page=3 and would get exactly the same page. If there are fewer pseudo-directories in the page request than in the URL template, the last few parameters are undefined.
>
> Looking at the URL template for the comments op, you can see three different `complications' in how the paths are parsed. The first template, with {\bf element.1} at the beginning, indicates that this template only applies if the first pseudo-directory after the op is `poll'. (Element 0 is the op itself.) The rest of the URL template is then used as above to assign values to CGI parameter names.
>
> The second and third templates have {\bf length=} at the beginning. This indicates that they are to apply if the path is of that particular length (again, not counting the op in that length). You can see that the entry with length=2 has two CGI parameters defined, and that the one with length=3 has three parameters defined.
>
> The fourth template shows an entirely different `complication'; sid\{5\} means that what would otherwise be five seperate items are treated as one parameter called `sid' (including the internal slashes). Story ID, or sid, values consist of five parts, separated by slashes.
>
> The most complicated form can be found in the user op. The URL template there is a block of perl code enclosed in an EVAL\{~\} statement. This perl code, like boxes, has full access to Scoop's internal functions. The value returned by the code must be a hash with CGI parameter names as the keys and CGI parameter values as the values of the hash. In the case of the user op, it must do such things as translate /my/info to use the user op and the nickname of the user making the request. It can also change the real op entirely: this is how /user/nickname/stories can return search results---the op is changed to be search, and the nickname is used as the search term for an author search.
>
> {\bf To create URL Templates}, you must first sort out what CGI parameters must be passed to your op for it to do everything it needs to do in a GET request. (CGI parameters that should be posted can be ignored here, since they never appear in the URL.) Then, in general, you should order them from most generic to most specific. For example, the sections op first lists which section (generic) then which page (specific) you are requesting. Optional parameters (like which page) should be last, so they can be left off without messing up the other parameters.
>
> Then, if none of your parameter values have slashes in them, you simply put your parameter names in the URL Templates textarea in order, separated by slashes. (Don't forget - leave off the op.)
>
> If one or more of your parameter values have slashes, such as the sid (story ID), then specify how many `parts' the parameter value has. The sid, for example, has five parts - four slashes in the value, so instead of just /sid/ you would put /sid\{5\}/ to tell Scoop to slurp up five 'directories' for that CGI parameter instead of the default one.
>
803c909,926
< FIXME
---
> The Subscriptions Admin Tool is where you create subscription types and define their prices and other properties. For detailed information on setting up subscriptions, see section~\ref{features-subscriptions}.
>
> To edit a subscription, choose the name of the subscription type from the topmost drop-down box, and click the ``Get'' button. The fields below will be filled in with the appropriate information. To create a new subscription, leave the topmost drop-down box on ``New Subscription Type'' and fill in the fields below as appropriate.
>
> In both cases, to save either changes to an existing subscription or a new subscription, click on the ``Save'' button in the top row of the form.
>
> The fields are:
>
> \begin{description}
> \item[Delete?] If selected, the current subscription type will be deleted when you click the ``Save'' button.
> \item[Name] The name of the subscription type. This is used as the display name as well, when members are choosing which subscription they would like to buy.
> \item[Current Subscribers] Displays the number of people currently subscribed to the loaded subscription type.
> \item[Group] The name of the group subscribers will be placed in. The group generally has a few extra permissions. You must create the group before you can create the subscription type.
> \item[Price] The cost per month of this subscription type. If set to 0, the subscription is activated immediately; if set to some positive value, the subscription is activated once paid.
> \item[Maximum Time] The maximum time a user can be subscribed. For example, a trial subscription could have a maximum time of one month, so people don't perpetually use the trial subscription instead of getting a real subscription.
> \item[Renewable] Whether or not a subscription type is renewable. For example, a trial subscription wouldn't be renewable, so that once a user tries it they have to either get a real subscription or go back to being a non-subscriber once their subscription runs out.
> \item[Description] A description of what the subscription type allows a subscriber. This is displayed when a user is selecting which subscription type to buy, to help them make their decision.
> \end{description}
808c931,967
< FIXME
---
> The Hooks Admin Tool is where you create and change hooks, or event triggers. Hooks are associated with events in Scoop, such as when a comment is posted or somebody creates a new account, and trigger some code that will do something based on what the event was. This provides similar but different functionality to the Cron Admin Tool (\ref{admin-tools-cron}), the difference being that cron items are run on a timed basis, while hooks are run based on the activities of users and administrators.
>
> The hooks included with Scoop are all disabled, but are set up as an example. Each row in the hooks table displays the event that will trigger an action and the function or box that performs that action.
>
> The table has five columns, with one row for each hook definition. The last row contains form elements where you can define new hooks. Below the table is a list of actions that can be performed on the hook definitions.
>
> The first column is a checkbox, used to select existing hooks for an action as described below.
>
> The second column is the event the hook is bound to. The list of available hooks is in the variable {\bf hooks}. Hooks cannot be added arbitrarily to this list; a corresponding run\_hook command must be present at the appropriate place in the code.
>
> The third column is the name of the function or box run when the event in the second column happens. This can be a built-in function, such as the {\bf log\_activity} function used in the included hooks, or it can be a box which you write yourself.
>
> The fourth column indicates whether or not the function named in the third column is a box or not.
>
> The fifth column indicates whether or not the hook is enabled. A disabled hook will be skipped when the event it's associated with occurs.
>
> The actions are:
>
> \begin{description}
> \item[Add Hook] Takes the information in the form elements of the last row of the table above and creates a new hook. Ignores any existing hooks which are selected.
> \item[Delete Hooks] Deletes the selected existing hooks. Ignores any information entered in the new hook form elements in the table above.
> \item[Toggle Enabled] Turns the selected existing hooks either on or off, depending on their status before. Each individual hook is toggled separately.
> \end{description}
>
> A given event may have as many functions or boxes associated with it as you like, but the functions should not depend on each other because you have no control over the order in which the functions are run.
>
> Each event passes different parameters to the function or box that handles it. These parameters are listed beside the event name in both the variable {\bf hooks} and in the drop-down box in the Hooks Admin Tool table. Although not listed explicitly, the name of the event is always the first parameter given to the function or box. This allows one function to handle several hooks, as the {\bf log\_activity} function does, by tailoring its response to the hook which triggered it.
>
> When writing a box to handle a hook, then, the first line should be, using comment\_new(sid,cid) as an example:
>
> \begin{verbatim}
> my ($hookname, $sid, $cid) = @ARGS;
> \end{verbatim}
>
> The arguments are used to identify exactly what has happened. For comment\_new, the sid (story ID) and cid (comment ID) uniquely identify every comment ever posted.
>
> For more information on writing boxes, see section~\ref{hacking}.
813c972,1011
< FIXME
---
> The Log Admin Tool is where you view and manage the activity logs. The first page of the Log Admin Tool is a simple list of links to the different logged item views and actions you can take.
>
> The logged item views are:
>
> \begin{description}
> \item[View list of all logged records] This link displays a list of all log records recorded to date. The list includes information such as the action taken, the item acted upon, the person who performed the action, and the time and date. If extended logging is enabled, a `More' link leads to extra details for each specific item. This list includes the items shown in the three views below as well as any others.
> \item[View list of deleted comments] This link displays a list of all log records for comment deletion. The details are as above.
> \item[View list of deleted stories] This link displays a list of all log records for story deletion. The details are as above.
> \item[View list of updated stories] This link displays a list of all log records for story updates. The details are as above.
> \end{description}
>
> The actions are:
>
> \begin{description}
> \item[Clear logfile] This link clears all items from the log, and adds a log item indicating that the log has been cleared, by whom, and when. The log item generated by this link cannot be avoided, even if all other logging functionality is turned off.
> \item[Change logging level] This link brings you to the Site Controls Admin Tool (\ref{admin-tools-vars}) with the variable {\bf use\_logging} displayed. From there you can set the log level to none, basic, or extended.
> \item[Enable all logging hooks] This link enables all hooks that use the function {\bf log\_activity}. Hooks are defined in the Hooks Admin Tool (\ref{admin-tools-hooks}).
> \item[Disable all logging hooks] This link disables all hooks that use the function {\bf log\_activity}.
> \item[Customize logging hooks] This link brings you to the Hooks Admin Tool (\ref{admin-tools-hooks}) where you can edit any of the logging or other hooks defined there.
> \end{description}
>
> For more information on setting up activity logs, see section~\ref{features-admin-action-log}
>
> \subsection{Macros}
> \label{admin-tools-macros}
>
> FIXME: interface is much like Site Controls (\ref{admin-tools-vars}).
>
> \subsection{Search}
> \label{admin-tools-search}
>
> The Search Admin Tool is where you can search through some of the other admin tools and find the part of the site you want to change.
>
> To use this tool you must have the perm {\bf admin\_search}, and you may only search those admin tools which you have permission to edit.
>
> The search form allows you to choose which admin tools to search in, as well as whether you want to search for a phrase, all of the search terms in any order, or any of the search terms.
>
> Search results are displayed grouped by the admin tool they were found in and show the item name, description, and provide a link to the edit form for that item.
>
> Generally if you are searching for a specific part of the display (not including usernames and other very dynamic content) you will want to search in the `values' (Block values, Box code, or Special Pages); if you are searching for items that do a task that you can describe but do not know what specific output it creates, you will want to search in the `descriptions' (Block descriptions, Box descriptions, or Site Controls descriptions).
814a1013
> %EOF
Index: admin.tex
===================================================================
RCS file: /cvs/scoop/scoop/doc/sag-tex-src/admin.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -r1.1 -r1.2
26c26
< \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 <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 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.
43c43
< \subsection{Where Do I Start?}
---
> \subsection{Basic Customization}
49a50,51
> It can often be tricky to figure out where the item you're looking for is, or what it's called. The Search Admin Tool (\ref{admin-tools-search}) lets you search through values and descriptions for several of the other admin tools.
>
74c76
< The best part of the blocks system is the ability to include other blocks within a block. Look carefully at the header block. You will notice that, mixed in with the HTML elements and text, are a few items marked off by pipes (|). Where you see the key `|section\_links|', Scoop will take the value from the section\_links block and seamlessly replace the key with it.
---
> The best part of the blocks system is the ability to include other blocks within a block. Look carefully at the header block. You will notice that, mixed in with the HTML elements and text, are a few items marked off by pipes (\latexhtml{$\vert$}{|}). Where you see the key `\latexhtml{$\vert$}{|}section\_links\latexhtml{$\vert$}{|}', Scoop will take the value from the section\_links block and seamlessly replace the key with it.
80c82
< 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 <html> and ending with </html>.
---
> 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>}.
82c84
< Your front page (and section pages) will use index\_template, viewing a story uses the story\_template, and most admin pages use default\_template. Be very careful changing these, because, if you mess it up, you might not be able to view your site.
---
> 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.
84c86
< 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 |header|. 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 |CONTENT|, 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 |CONTENT| 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.
---
> 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.
95c97
< You will notice that the templates also contain keys like |BOX,login\_box| and |BOX,user\_box|. 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.
---
> 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.
107,124c109
< \subsubsection{Publishing Stories}
< \label{how-publishing}
<
< Scoop uses a democratic model of publishing by default; that is, unlike most weblogs which have a limited number of people choosing what to post, {\bf any registered user can vote} on what stories to publish and where. Which users can submit stories and vote is controlled by their group permissions (see section~\ref{admin-users}).
<
< If you have enabled the `edit queue' (see section~\ref{moderation-queues}) and the user has chosen to use it, he can change his story according to `editorial' comments other users offer to help improve it to the point where it can be moved on to the voting queue.
<
< When the user is satisfied or a time limit is reached, the story is moved from the edit queue to the voting queue, and can then be voted on. If the edit queue isn't active, all stories go immediately to the voting queue. Other users then cast their vote; either +1 (post), -1 (drop), or 0 (abstain). The votes are added up using the methods described in section~\ref{moderation-autopost}, and when the story reaches one of the thresholds, the story is either posted or dropped. All of the limits can be configured through the Site Controls Admin Tool, in the Stories category.
<
< If there are not enough people to vote a story up, the Superuser can force a story to be published---this is common in brand new sites. By clicking the `edit' link in the story then setting the dropdown box just under the title to ``Always Display'' a story can be published on the front page regardless of votes.
<
< If you don't want to use Scoop's story voting mechanism but just let yourself or maybe a few people post stories at will, you can take away normal users' ability to post stories or vote using the Groups Admin Tool, then use the Sections Admin Tool to give your group the ability to auto-post stories to the front page or the section page, whichever you prefer.
<
< \subsubsection{...etc}
<
< FIXME: more... what else confuses people new to Scoop administration?
<
< \subsection{Users}
---
> \subsection{Users and Stories}
137c122
< It's generally not a good idea to delete a user, because there is so much stuff tied to the userid and to that stuff (i.e., a user has comments, those comments have replies), but there is a function that allows you to anonymize all comments by a specific user and disable the account. FIXME: where and how?
---
> 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.
168a154,166
> \subsubsection{Publishing Stories}
> \label{how-publishing}
>
> Scoop uses a democratic model of publishing by default; that is, unlike most weblogs which have a limited number of people choosing what to post, {\bf any registered user can vote} on what stories to publish and where. Which users can submit stories and vote is controlled by their group permissions (see section~\ref{admin-users}).
>
> If you have enabled the `edit queue' (see section~\ref{moderation-queues}) and the user has chosen to use it, he can change his story according to `editorial' comments other users offer to help improve it to the point where it can be moved on to the voting queue.
>
> When the user is satisfied or a time limit is reached, the story is moved from the edit queue to the voting queue, and can then be voted on. If the edit queue isn't active, all stories go immediately to the voting queue. Other users then cast their vote; either +1 (post), -1 (drop), or 0 (abstain). The votes are added up using the methods described in section~\ref{moderation-autopost}, and when the story reaches one of the thresholds, the story is either posted or dropped. All of the limits can be configured through the Site Controls Admin Tool, in the Stories category.
>
> If there are not enough people to vote a story up, the Superuser can force a story to be published---this is common in brand new sites. By clicking the `edit' link in the story then setting the dropdown box just under the title to ``Always Display'' a story can be published on the front page regardless of votes.
>
> If you don't want to use Scoop's story voting mechanism but just let yourself or maybe a few people post stories at will, you can take away normal users' ability to post stories or vote using the Groups Admin Tool, then use the Sections Admin Tool to give your group the ability to auto-post stories to the front page or the section page, whichever you prefer.
>
184c182
< You may want to use Apache's log rotation to avoid filling up your hard drive. This is not set up via Scoop, but in the Apache configuration. See the apache log rotation documentation at \hturl{http://httpd.apache.org/docs/logs.html\#rotation} to set it up to suit your site.
---
> You may want to use Apache's log rotation to avoid filling up your hard drive. This is not set up via Scoop, but in the Apache configuration. See the apache documentation at \hturl{http://httpd.apache.org/docs/logs.html\#rotation} to set it up to suit your site.
204a203,214
> \subsection{Performance Monitoring}
> \label{performance}
>
> \hturl{http://jeremy.zawodny.com/mysql/mytop/} MySQL performance monitoring on the command line. Display is similar to unix `top' but shows the queries running and stats on efficiency and slow queries.
>
> In the mysql client, you can see what queries are currently running by typing at the mysql prompt:
> \begin{verbatim}
> mysql> show full processlist;
> \end{verbatim}
>
> %FIXME: more performance tips added as they're thought of.
>
208c218
< FIXME: I know there's loads, just can't think of them right now. Will add as I think of them.
---
> \subsubsection{Security}
210c220,222
< Boxes can run arbitrary code on the server. Be careful when you give out edit\_box perms.
---
> Boxes can run arbitrary perl code on the server, with the permissions of the apache daemon. This includes any external programs present on your system. Be careful when you give out edit\_box perms.
>
> \subsubsection{Access Control}
223a236,237
>
> 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.
Index: faq.tex
===================================================================
RCS file: /cvs/scoop/scoop/doc/sag-tex-src/faq.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -r1.1 -r1.2
5a6
> \subsection{General and installation}
7c8
< What's the difference between blocks and boxes?
---
> \subsubsection{What exactly is Scoop?}
9c10
< How do stories get posted?
---
> 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.
11c12
< How do stories get posted if there aren't any users to vote on them?
---
> 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.
13c14
< What is an "open queue"?
---
> A scoop site can be run almost entirely by the readers. The whole life-cycle of content is reader-driven. They submit stories, they choose what to post, and they can discuss what they post. Readers can rate other readers comments, as well, providing a collaborative filtering tool to let the best contributions float to the top. Based on this rating, you can also reward consistently good contributors with greater power to review potentially untrusted content. The real power of Scoop is that it is almost totally collaborative.
15c16
< What is a "closed queue"?
---
> Of course, as an admin, you also may pick and choose which tools you want the community to have, and which will be available to admins only. Administrators have a very wide range of customization and security management tools available. All of the administration of Scoop is done through the normal web interface. Scoop will seamlessly provide more options to site administrators, right in the normal site, so the tools you need are always right where you need them.
17c18
< How do I edit a comment?
---
> \subsubsection{Why don't you re-write Scoop in (insert your favourite language here)?}
19c20
< Why don't we re-write Scoop in (insert your favourite language here)?
---
> Go right ahead, but the Scoop developers like perl. There's not much point in writing a Scoop feature clone in another language though, you should figure out which features you really want and implement them however you see fit in your own project.
21c22
< How do I add some of those sidebar boxes that kuro5hin has?
---
> \subsubsection{Does Scoop run on Apache 2?}
23,24c24
< Does Scoop run on apache 2?
< A: Yes, but... Some things may be broken (file uploads are for definate at the moment). Also, you have to run CVS development versions of libapreq. Plus, it's not recomended to run mod\_perl 2 on a production machine.
---
> Yes, but... Some things may be broken (file uploads are definately broken at the moment, some other items as well). Also, you have to run CVS development versions of libapreq.
26c26
< Why won't my site send email when creating new accounts?
---
> Basically, Scoop has been made to run on Apache 2, but you should only do so if you intend to help port it to mod\_perl 2. On no account should you run a production Scoop site using mod\_perl 2.
28c28
< Why do I get logged out on every new page load, even though I can log in just fine?
---
> \subsubsection{Why can't Apache find all the perl modules I installed?}
30c30
< Why does the admin stuff tell me "Permission Denied" when I've logged in as the administrator?
---
> There are a couple of possibilities. One is that some of the perl modules didn't get installed properly---if that's the case, check CPAN's output for error messages.
32c32
< Why can't Apache find all the perl modules I installed?
---
> Another possibility is that CPAN upgraded perl without asking you. If this is the case, you'll see messages like ``Can't find Something.pm in @INC (@INC includes path1,path2,...)''. See section~\ref{install-troubleshooting} for details on what causes this and how to fix it.
33a34,142
> \subsubsection{What is CPAN? and how do I get these crazy modules?}
>
> CPAN is the Comprehensive Perl Archive Network, a vast repository of more perl modules than you'll ever need. Scoop depends heavily on quite a few of those modules, so the Scoop developers don't have to rewrite such basic functions as sending email, generating random strings, and connecting to the database.
>
> The full details on how to get the modules from CPAN are in section~\ref{install-modules}
>
> \subsubsection{I keep getting "Document Contains no Data", what does that mean?}
>
> This means that somehow either Apache or Scoop is failing without warning and just stopping.
>
> If Scoop hasn't yet successfully shown its front page, it may be having trouble connecting to the database. One fix that has been known to work is to go back into cpan, and 'force install' DBD::mSQL
> \begin{verbatim}
> cpan> force install DBD::mSQL
> \end{verbatim}
> and tell it to install the msyql modules only.
>
> If Scoop was working before and is now giving you ``Document Contains no Data'', it may be because Apache has run out of space to write its log files. Scoop has been known to trigger this via its page caching (\ref{features-static-page-caching}), if Apache's log files and Scoop's cache files are on the same partition on the hard drive.
>
> \subsection{Stories, comments, and the queue}
>
> \subsubsection{How do stories get posted?}
>
> Stories are placed into a moderation queue when submitted, then are voted on by registered users. When a story's score (the sum of all positive, negative, and neutral votes) reaches a configurable threshold, the story is either posted or dropped. The exact mechanism and a description of what the thresholds are and how they interact is described in section~\ref{features-modsub}.
>
> \subsubsection{How do stories get posted if there aren't any users to vote on them?}
>
> To short-circuit the problem all Scoop sites have when first started, that of having no users to vote stories up and therefore no stories posted to attract users, the administrator can manually post articles. When enough active users are present, the moderation queue can be opened to members with the thresholds set suitably low and raised as the membership grows. Details can be found in section~\ref{moderation-override}.
>
> \subsubsection{What is an "open queue"?}
>
> An open moderation queue is one in which all registered users have permission to view and vote on submitted stories. Stories are posted or not depending on what the users choose. For full details on configuring the open queue, see section~\ref{features-modsub}.
>
> \subsubsection{What is a "closed queue"?}
>
> A closed moderation queue is one in which only editors, but not any registered users, have permission to view and vote on submitted stories. In a closed queue, the editors will also generally have permission to edit the stories, so the queue then becomes a place for the site's editorial staff to prepare stories for publication.
>
> \subsubsection{How do I edit a comment?}
>
> There's no way to edit a comment's text. As an admin, all you can do is delete it, which is irreversible, or change it between editorial or topical, which is easily reversible by simply changing it again. For more details on what is possible with comments, see section~\ref{comments-display}.
>
> \subsection{Users, logging in, and logging out}
>
> \subsubsection{Why do I get logged out on every new page load, even though I can log in just fine?}
>
> This is a cookie problem. Scoop uses cookies to identify you with every page you request, so it knows what you are allowed to do. Generally this is caused by the cookie\_host variable in your Apache configuration being wrong; it must match the domain you are using the access the site. See section~\ref{apache-config} for more details.
>
> \subsubsection{Why does the admin stuff tell me "Permission Denied" when I've logged in as the administrator?}
>
> Chances are you're being logged out. If you are, see the question above.
>
> If you're still logged in but are being denied permission to do admin events, you should check the Groups Admin Tool (\ref{admin-tools-groups}) to make sure you actually do have permission to do what you're trying to do. If you've created another account, you may be logged in as that account and not the superuser account created when Scoop is first installed.
>
> \subsubsection{Why does logging out take so long? Every other page load is way faster!}
>
> KeepAlive is on. Logging out waits for the KeepAlive to time out, a length of time set by the Apache directive {\bf KeepAliveTimeout}. You can reduce the timeout or turn KeepAlive off entirely to speed up the logout process.
>
> KeepAlive has some advantages, so you should read Apache's documentation on that directive and consider the advantages against the logout time issue to decide what you want to set the timeout to.
>
> \subsubsection{I have a user who forgot their password, how do I change it?}
>
> Users can request a new password from Scoop by putting their username into the login box and clicking the ``Mail Password'' button.
>
> If the user does not have access anymore to the email address listed as their ``real email'' in their user preferences, you will have to change their password for them - but {\bf make sure to your satisfaction that they are who they claim they are!} While logged into a Superuser level account, use the Edit User box in the Admin Tool box to type in their username, and click 'prefs'. Scroll down do where you can enter a new password for them. Type in a new password for them, into both boxes. Click ``Save'', let them know about their new password, and you're done.
>
> \subsection{Site layout and customization}
>
> \subsubsection{What's the difference between blocks and boxes?}
>
> {\bf Blocks} are used to build the display. At first they can be confusing, because it's not always clear which block is used where, but they allow you to quickly and easily change the entire layout of the site. This is where all layout changes are made; there are no HTML template files to modify. (The html/ directory in the Scoop package contains the site's static files, such as its images and robots.txt.)
>
> {\bf Boxes}, on the other hand, are bits of perl code that run every time they appear on a page. They range from very simple (the main\_menu box which checks a few permissions and displays appropriate menu items) to very complex (the payment processing boxes used to handle ad and subscription payment and activation). Boxes have full access to all of Scoop's data and functions, as well as the normal Perl ability to call external programs and capture their output for parsing (the fortune\_box is an example of this; it calls the unix program 'fortune' and displays the quote returned). There are a number of useful boxes included with Scoop, and quite a number of other boxes available on the Scoop Box Exchange (\ref{sbe}).
>
> \subsubsection{How do I add some of those sidebar boxes that kuro5hin has?}
>
> Some of kuro5hin's custom boxes are available on the Scoop Box Exchange (\ref{sbe}). Others aren't. The SBE is the first place to look for boxes that aren't included with Scoop.
>
> \subsection{Crashes and general misbehaviour}
>
> \subsubsection{RDFs don't work! I can't fetch any from the RDF admin tool!}
>
> This is because apache, by default, compiles in a modified version of expat (called expat-lite) that differs from the normal expat, which perl's XML parser module uses. Having two different expat's in memory is enough to segfault the apache child. You will see this behavior when running cron with 'op=cron' or re-fetching the RDF feeds from the RDF admin tool. Sadly, the only way to fix this is to recompile apache.
>
> See section~\ref{install-depend} for an explanation.
>
> \subsubsection{Cron is segfaulting Apache!}
>
> See the question above; this is most likely happening when Scoop's cron tries to fetch RDF files.
>
> \subsubsection{I keep getting "Document Contains no Data", what does that mean?}
>
> This means that somehow either Apache or Scoop is failing without warning and just stopping.
>
> If Scoop was working before and is now giving you ``Document Contains no Data'', it may be because Apache has run out of space to write its log files. Scoop has been known to trigger this via its page caching (\ref{features-static-page-caching}), if Apache's log files and Scoop's cache files are on the same partition on the hard drive.
>
> \subsection{Email}
>
> \subsubsection{Why won't my site send email when creating new accounts?}
>
> First, make sure Scoop is configured to use the right mail server by checking your configuration against the instructions in section~\ref{apache-config}.
>
> If Scoop is configured properly, try creating an account using an email address you know for certain the mail server Scoop uses can successfully send email to. It is entirely possible that the address that didn't receive the email has an overzealous spam filter, and there's actually nothing at all wrong with your configuration. In that case, there's really nothing you can do.
>
> If Scoop can't send an email to an address that you know for sure works and you can send email to via the same mailserver as Scoop is configured to use, then you'll have to check the mailserver logs to see what is actually happening to the email, because the problem is probably in the mail server configuration itself, possibly an issue with your Scoop server not having permission to relay email through the mail server.
>
> If you've installed Scoop on Windows, we know email doesn't work but we don't know why yet.
>
> \subsection{Other}
>
> If your question isn't answered in any of the previous sections of the Scoop FAQ, feel free to drop by \#scoop on irc.slashnet.org to ask for help. A lot of Scoop problems have been solved in that channel. Your question may also end up here in the FAQ!
Index: features.tex
===================================================================
RCS file: /cvs/scoop/scoop/doc/sag-tex-src/features.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -r1.1 -r1.2
6,7d5
< FIXME: I'm merging the feature admin stuff with what I had here before, which was a sort of fluffy ``ooh, look at the features!'' thing, which frankly I didn't like much. Too marketing-ish. Anyhow, as long as this message is here, some of the subsections below will be still fluffy, and some will actually have good admin info in them. The ones that still need work are marked with "FIXME"; the ones without that tag are finished.
<
81c79,182
< If you want to {\bf bypass the queue entirely}, either for the entire site or just a specific section, for everybody or just certain groups, you can set the section permissions (see section~\ref{section-perms} and appendix~\ref{admin-tools-sections} for details) to allow the appropriate groups to auto-post to either section or front page for each relevant section. This is a different auto-post than described above; this one does no calculations, but bypasses the queue entirely and automatically posts the story wherever the permissions specify. This is the preferred method if you always want to bypass the queue in certain situations.
---
> If you want to {\bf bypass the queue entirely}, either for the entire site or just a specific section, for everybody or just certain groups, you can set the section permissions (see section~\ref{sections-perms} and appendix~\ref{admin-tools-sections} for details) to allow the appropriate groups to auto-post to either section or front page for each relevant section. This is a different auto-post than described above; this one does no calculations, but bypasses the queue entirely and automatically posts the story wherever the permissions specify. This is the preferred method if you always want to bypass the queue in certain situations.
>
> \subsection{User Diaries}
> \label{features-diaries}
>
> Every user can post their own musings in their own section. Basically, it's as if every user has his own personal weblog on your site. The Diaries section can be used for anything the users want to use it for: getting to know each other, venting, or requesting feedback on a draft of an article they're working on.
>
> If the variable {\bf use\_diaries} is turned on, diaries are available to all users with the perm {\bf story\_post} (\ref{perm-story-post}). Diaries are not shown on the ``Everything'' index page, nor are they included in the site's RDF feed (see section~\ref{features-rdf} for RDF information). Diaries are not sent through the queue. Apart from that, diaries have all the same features as stories and are edited in the same way.
>
> \subsection{Story Archiving}
> \label{features-archive}
>
> For large, busy sites, the database can become too large for the server to handle; specifically, the indexes become too large to keep in memory, and the whole thing {\bf slows down drastically}. Story and comment archiving addresses that by moving older stories and comments to a secondary database.
>
> The primary database is used for new and still-active stories and their comments; the archive database is used for older stories, and {\bf does not allow new comments}, ratings, or poll votes. Archived stories are available at the same URL as they were before being archived, to prevent links bringing people to your site from breaking. To search the archive for comments and stories, the user must check the ``Search Archive'' box in the search form as the regular and archive databases are searched separately.
>
> To {\bf set up the archive database}, you must first create the database and set the access rules for it as described in section~\ref{manual-db}. This is the same procedure as for the regular database, but you must substitute the name of the archive database and its sql file in the command. The sql file for the archive database is in your scoop/struct/archive directory. You may use the same database username and password for the regular and archive databases.
>
> For Scoop to {\bf access the archive database} properly, you have to tell Apache about it in the httpd.conf file, or wherever your main Scoop config directives are:
>
> \begin{verbatim}
> # Archive config:
> # Set these vars if you use an archive database
>
> # The name of the archive database
> PerlSetVar db_name_archive __DBNAMEARCHIVE__
>
> # The host where mySQL is running
> PerlSetVar db_host_archive __DBHOSTARCHIVE__
>
> # The user to connect as
> PerlSetVar db_user_archive __DBUSERARCHIVE__
>
> # The user's database password
> PerlSetVar db_pass_archive __DBPASSARCHIVE__
> \end{verbatim}
>
> Substitute the correct values for the name, host, user, and password, then stop and start Apache (never restart). A good place to paste these commands in your config file is right after the commands for your regular database; that way they're all together.
>
> Archiving is controlled through the variables in the Site Controls Admin Tool (\ref{admin-tools-vars}).
>
> Stories and their comments are archived together; polls, even those attached to stories, are archived separately.
>
> Stories are archived based on their age and optionally their activity. The variable {\bf story\_archive\_age} sets the age of a story in days before it will be considered for archiving. Any story posted (not submitted) more days ago than this value will be archived or considered for archiving. To disable story archiving, set {\bf story\_archive\_age} to 0.
>
> If you wish to {\bf protect old but active stories} from archiving, the variable {\bf comment\_archive\_age} is what you want. Stories considered for archiving are tested for new comments; if they have any comments newer than the age in this variable, they are not archived. If the newest comment is older than the age in this variable, then the story is archived. To disable this check and archive stories purely on their age, set {\bf comment\_archive\_age} to 0.
>
> In addition to archiving stories and their comments, you have the option of {\bf archiving a story's voting record} instead of just its displaystatus (Front Page or Section). You also have the option of {\bf archiving a comment's rating history}, instead of just its score and the number of ratings. Both of these are informational only, and archiving and display will work equally well with or without them. They are set using the variables {\bf archive\_moderations} and {\bf archive\_ratings}, respectively.
>
> Polls are archived based purely on their age; there is no option to protect active polls. The variable {\bf poll\_archive\_age} sets the age of a poll in days before it will be archived. To disable poll archiving, set {\bf poll\_archive\_age} to 0.
>
> Once the archive database and archiving configuration are set, the actual {\bf process of archiving} is started using the Cron Admin Tool (\ref{admin-tools-cron}). The cron item {\bf archive\_stories} runs the code that checks the age of stories and comments, then archives those that match the criteria set in the Site Controls. The cron item {\bf poll\_archive} runs the code that checks the age of polls, then archives those that match the criteria set it the Site Controls.
>
> \subsection{Story Digest Emails}
> \label{features-digest}
>
> Scoop can send headlines and summaries of stories posted to either front page or section since the last scheduled digest email. Daily digests are sent every day, weekly digests are sent on Sunday, and monthly digests are sent on the first of the month.
>
> To configure story digests, set the variable {\bf digest\_subject} to the desired subject line of the email. The content of the digest email is set using the blocks {\bf digest\_header}, {\bf digest\_footer}, and {\bf digest\_storyformat}. If you want the header and footer of your digest email to be the same, you can also use {\bf digest\_headerfooter}. If the blocks for both the separate and combined header and footer exist, the separate header and footer blocks are used.
>
> The subject is sent as-is to the digest recipients. The blocks used to format the content of the digest contain special keys documented in the block descriptions which are used to place the relevant information. HTML and regular block references should not be used in these blocks as the HTML in the stories is removed and the email sent as plain text.
>
> Once the digests are configured as you want them, set the variable {\bf enable\_story\_digests} to 1, and in the Cron Admin Tool (\ref{admin-tools-cron}) activate the {\bf digest} cron item. It should run no more than once per day, as the code does not check if it has already run that day, it simply sends the last day's (or week's, or month's) worth of stories.
>
> When {\bf enable\_story\_digests} is turned on, users are given a control which allows them to choose at what frequency they wish to receive story digests, if at all.
>
> \subsection{Story Syndication (RDF)}
> \label{features-rdf}
>
> Many sites syndicate their headlines so other sites can link to their latest content easily. Scoop can fetch headlines from any number of other sites and allows users to choose which of those headlines they would like to see in their sidebar.
>
> Scoop can also create its own RDF feeds, and instead of just the headlines it includes the story's introduction as well.
>
> All of the variables referenced below should be in the RDF category of Site Controls.
>
> \subsubsection{Fetching Headlines}
> \label{rdf-fetching}
>
> RDF feeds to be fetched regularly are handled using the RDF Admin Tool (\ref{admin-tools-rdf}), and managing them requires the perm {\bf rdf\_admin} (\ref{perm-rdf-admin}). Enabled feeds are fetched on a schedule set in the {\bf rdf\_fetch} cron item (\ref{admin-tools-cron}).
>
> If the variable {\bf use\_rdf\_feeds} is on, then users may select from the enabled feeds for display in their sidebar. RDF feeds can be either added directly or submitted by users with the perm {\bf submit\_rdf} (\ref{perm-submit-rdf}). Submitted RDF {\bf feeds must be approved by the admin} before users can see them.
>
> Some RDF feeds include images, such as their site logo, in the feed; the variable {\bf rdf\_use\_images} determines whether or not Scoop will display that image with the RDF feed. Similarly, some feeds include text inputs, such as a search box that directs to the RDF source site; the variable {\bf rdf\_use\_forms} determines whether or not Scoop will display that form with the RDF feed.
>
> RDF feeds all include a different number of headlines, some of them quite large. You can restrict the number of headlines displayed with the variable {\bf rdf\_max\_headlines}; this number can be overridden by a user preference if the user wishes to see more headlines.
>
> \subsubsection{Publishing Headlines}
> \label{rdf-publishing}
>
> Scoop creates its RDF feed on a schedule set by the rdf cron item (\ref{admin-tools-cron}).
>
> The number of headlines included is determined by the number of stories posted either to front page or section in a certain time, set by the variable {\bf rdf\_days\_to\_show}, up to a maximum set in the variable {\bf rdf\_max\_stories}.
>
> Some meta-information can be included in the RDF file created, all set by variables. The copyright notice is set by the variable {\bf rdf\_copyright}; the RDF creator and publisher default to the site name as set in the variable sitename unless the variables {\bf rdf\_creator} and {\bf rdf\_publisher} are set, respectively. If you wish to include your site logo in the RDF feed, enter its full URL---including the http://---into the variable {\bf rdf\_image}. You should probably only include a small, button-sized image, just to avoid annoying the admins of other sites; they may reject your feed altogether if you include a large image.
>
> Finally, the file that the RDF feed is saved to is set in the variable {\bf rdf\_file}. This must be an absolute local pathname; the file {\bf must be writeable by the Apache server}'s user; and the file must be accessible from the internet.
>
> If you are using a location-based install, add an Alias line by the images Alias as below (the images Alias line is shown for reference):
> \begin{verbatim}
> Alias /scoop/ "/www/scoop/html/"
> Alias /scoop/images/ "/www/scoop/html/images/"
> \end{verbatim}
>
> 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.
99c200
< Replies to any comment take on the comment type of their parent; top-level comments allow the poster to choose whether it's topical or editorial if the story is still in the queue.
---
> Replies to any comment take on the comment type of their parent; top-level comments allow the poster to choose whether it's topical or editorial if the story is still in the queue. Once out of the queue, only topical comments can be posted.
136c237
< Comments can be posted using HTML, plain text, or ``autoformat'', a mode that translates common markup, such as what most people use in email, into HTML formatting. For example, it changes words surrounded by asterisks into bold text; *this* becomes {\bf this}. A full description of the autoformat mode is included in your Scoop database; it can be found at {\bf |rootdir|/special/autoformat\_syntax} Each user can select their preferred mode and can change the mode for a single comment when posting. You can set the default for new and anonymous users to any of the three modes using the variable {\bf default\_post\_type}. The default post type applies to both stories and comments.
---
> Comments can be posted using HTML, plain text, or ``autoformat'', a mode that translates common markup, such as what most people use in email, into HTML formatting. For example, it changes words surrounded by asterisks into bold text; *this* becomes {\bf this}. A full description of the autoformat mode is included in your Scoop database; it can be found at {\bf \latexhtml{$\vert$}{|}rootdir\latexhtml{$\vert$}{|}/special/autoformat\_syntax} Each user can select their preferred mode and can change the mode for a single comment when posting. You can set the default for new and anonymous users to any of the three modes using the variable {\bf default\_post\_type}. The default post type applies to both stories and comments.
160c261
< Dynamic comment mode is done using javascript, and only modern ``fifth-generation'' browsers can deal with it properly. That is, (FIXME: what versions exactly???) Netscape > 6; IE > 5; Mozilla and other gecko-based browsers, and later versions of Opera.
---
> Dynamic comment mode is done using javascript, and only modern ``fifth-generation'' browsers can deal with it properly. That is, Netscape \latexhtml{$>$}{>} 6; IE \latexhtml{$>$}{>} 5; Mozilla and other gecko-based browsers, and later versions of Opera. Some other browsers may work with it, but those listed here are those known to work.
167c268
< \item the file {\bf dynamic-comments.js} must be present in the site's documentroot and fetchable from the internet with no errors. Note its path. Older location-based installs don't map the base scoop directory to a filesystem location, so the file can't be fetched. To fix this, add the following to your httpd configuration, right by the Alias line that sets your images directory (the images directory line is also shown, for reference):
---
> \item The file {\bf dynamic-comments.js} must be present in the site's documentroot and fetchable from the internet with no errors. Note its path. Older location-based installs don't map the base scoop directory to a filesystem location, so the file can't be fetched. To fix this, add the following to your httpd configuration, right by the Alias line that sets your images directory (the images directory line is also shown, for reference):
173c274
< \item a block called {\bf dynamic\_js\_tag} must be present and must contain the following:
---
> \item A block called {\bf dynamic\_js\_tag} must be present and must contain the following:
178,179c279,280
< \item the blocks {\bf story\_template} and {\bf default\_template} both contain |dynamicmode\_javascript| at the end of the HEAD section of their HTML ({\bf not} in the BODY section, nor between HEAD and BODY).
< \item the block {\bf header} contains |dynamicmode\_iframe| at the end of the block. This key has no effect on the display as it is an invisible iframe, so it can actually be placed anywhere in the header block.
---
> \item The blocks {\bf story\_template} and {\bf default\_template} must both contain \latexhtml{$\vert$}{|}dynamicmode\_javascript\latexhtml{$\vert$}{|} at the end of the HEAD section of their HTML ({\bf not} in the BODY section, nor between HEAD and BODY).
> \item The block {\bf header} contains \latexhtml{$\vert$}{|}dynamicmode\_iframe\latexhtml{$\vert$}{|} at the end of the block. This key has no effect on the display as it is an invisible iframe, so it can actually be placed anywhere in the header block.
182c283
< When all of the above items are set correctly, the variable {\bf allow\_dynamic\_comment\_mode} should be turned on to allow users to choose dynamic comment display modes.
---
> When you have made sure that all of the above items are set correctly, the variable {\bf allow\_dynamic\_comment\_mode} may be turned on to allow users to choose dynamic comment display modes.
186c287
< \subsection{Story and Frontpage Polls}
---
> \subsection{Polls}
199,209c300,301
< \subsection{User Diaries}
< \label{features-diaries}
<
< Every user can post their own musings in their own section. Basically, it's as if every user has his own personal weblog on your site. The Diaries section can be used for anything the users want to use it for: getting to know each other, venting, or requesting feedback on a draft of an article they're working on.
<
< If the variable {\bf use\_diaries} is turned on, diaries are available to all users with the perm {\bf story\_post} (\ref{perm-story-post}). Diaries are not shown on the ``Everything'' index page, nor are they included in the site's RDF feed (see section~\ref{features-rdf} for RDF information). Diaries are not sent through the queue. Apart from that, diaries have all the same features as stories and are edited in the same way.
<
< \subsection{Story Archiving}
< \label{features-archive}
<
< For large, busy sites, the database can become too large for the server to handle; specifically, the indexes become too large to keep in memory, and the whole thing {\bf slows down drastically}. Story and comment archiving addresses that by moving older stories and comments to a secondary database.
---
> \subsection{Spell-checking Stories and Comments}
> \label{features-spellcheck}
211c303
< The primary database is used for new and still-active stories and their comments; the archive database is used for older stories, and {\bf does not allow new comments}, ratings, or poll votes. Archived stories are available at the same URL as they were before being archived, to prevent links bringing people to your site from breaking. To search the archive for comments and stories, the user must check the ``Search Archive'' box in the search form as the regular and archive databases are searched separately.
---
> Spell-checking requires an extra (optional) perl module installed before it will work, but no other changes to the site, beyond configuration in the admin interface. The only language currently supported is English.
213c305
< To {\bf set up the archive database}, you must first create the database and set the access rules for it as described in section~\ref{manual-db}. This is the same procedure as for the regular database, but you must substitute the name of the archive database and its sql file in the command. The sql file for the archive database is in your scoop/struct/archive directory. You may use the same database username and password for the regular and archive databases.
---
> You will need the aspell program and the Text::Aspell perl module, which provides a perl interface to aspell. Aspell, its dictionary, and Text::Aspell should be installed according to the instructions in the install section (\ref{install-recommended-programs}).
215c307
< For Scoop to {\bf access the archive database} properly, you have to tell Apache about it in the httpd.conf file, or wherever your main Scoop config directives are:
---
> Once the aspell program and perl module are installed, Apache must be stopped then started so it will find the spellchecking module in its initialization. No further Apache configuration is necessary.
217,219c309
< \begin{verbatim}
< # Archive config:
< # Set these vars if you use an archive database
---
> Spellchecking is configured through the Site Controls Admin Tool (\ref{admin-tools-vars}), in the Spellchecker category. It is turned on using the variable {\bf spellcheck\_enabled}.
221,222c311
< # The name of the archive database
< PerlSetVar db_name_archive __DBNAMEARCHIVE__
---
> Whether spellchecking is on by default or must be explicitly turned on by the user at comment posting time is set using the variable {\bf spellcheck\_default}. The specific English variant used by default is set in the variable {\bf spellcheck\_spelling}. Both of these can be overridden by a user preference.
224,225c313
< # The host where mySQL is running
< PerlSetVar db_host_archive __DBHOSTARCHIVE__
---
> Permission to use the spellchecker is given using the perm {\bf use\_spellcheck}, in the Groups Admin Tool (\ref{admin-tools-groups}).
227,228c315,316
< # The user to connect as
< PerlSetVar db_user_archive __DBUSERARCHIVE__
---
> \subsection{Macros in Stories and Comments}
> \label{features-macros}
230,232c318
< # The user's database password
< PerlSetVar db_pass_archive __DBPASSARCHIVE__
< \end{verbatim}
---
> Macros are at heart a bit like HTML tags. Instead of telling the browser what to do, though, macros tell Scoop what to do. This allows you to give users limited access to functions that could, if not limited, leave you with a security problem or stuff on your site that you don't want.
234c320
< Substitute the correct values for the name, host, user, and password, then stop and start Apache (never restart). A good place to paste these commands in your config file is right after the commands for your regular database; that way they're all together.
---
> To configure the macro system, create the macro definitions you want to use, then set the variable {\bf use\_macros} to 1. Macro definitions are created in the Macros Admin Tool (\ref{admin-tools-macros}).
236c322
< Archiving is controlled through the variables in the Site Controls Admin Tool (\ref{admin-tools-vars}).
---
> Macros can be either rendered when the story is saved or every time it's viewed using the variable {\bf macro\_render\_on\_save}. Which setting you want will depend on what your macros do. If all your macros do something completely static, then having them render on save can reduce the load on your server. If your macros are dynamic, or you want them to run with the environment and preferences of the user viewing the page instead of the story author, then macros should be rendered every time they're viewed.
238c324
< Stories and their comments are archived together; polls, even those attached to stories, are archived separately.
---
> When using the edit queue (\ref{moderation-queues}) keep in mind that the author can edit the story after it's been saved, so if macros render on saving, when the author edits the story, he will be presented with the output of the macro rather than the macro command.
240c326
< Stories are archived based on their age and optionally their activity. The variable {\bf story\_archive\_age} sets the age of a story in days before it will be considered for archiving. Any story posted (not submitted) more days ago than this value will be archived or considered for archiving. To disable story archiving, set {\bf story\_archive\_age} to 0.
---
> Macros can also be rendered `verbosely' by turning on the variable {\bf macro\_render\_verbose}, that is, extra comments will be added around the macro and the original macro command will be preserved in an HTML comment when the rendered macro is displayed.
242c328
< If you wish to {\bf protect old but active stories} from archiving, the variable {\bf comment\_archive\_age} is what you want. Stories considered for archiving are tested for new comments; if they have any comments newer than the age in this variable, they are not archived. If the newest comment is older than the age in this variable, then the story is archived. To disable this check and archive stories purely on their age, set {\bf comment\_archive\_age} to 0.
---
> When the macro system is enabled, Scoop will scan stories and comments for existing macros and replace them with the macro definition you have created. Macros are indicated in stories and comments with double parentheses around the macro name. To use the included example macro, {\bf macro\_test}, you would put {\bf ((macro\_test))} where you want the text of that macro to appear.
244c330
< In addition to archiving stories and their comments, you have the option of {\bf archiving a story's voting record} instead of just its displaystatus (Front Page or Section). You also have the option of {\bf archiving a comment's rating history}, instead of just its score and the number of ratings. Both of these are informational only, and archiving and display will work equally well with or without them. They are set using the variables {\bf archive\_moderations} and {\bf archive\_ratings}, respectively.
---
> For example, if you have a box that you want users to be able to embed in a story or comment, you would do this via a macro. Normally, boxes and blocks are not substituted in stories for security reasons. If you created a macro with the box key (\latexhtml{$\vert$}{|}BOX,boxid\latexhtml{$\vert$}{|}) as the value, then that one box can be embedded in a story while denying access to the other boxes. Any box, block, or site control that can be interpolated into a regular block via vertical pipes is available to macros.
246c332
< Polls are archived based purely on their age; there is no option to protect active polls. The variable {\bf poll\_archive\_age} sets the age of a poll in days before it will be archived. To disable poll archiving, set {\bf poll\_archive\_age} to 0.
---
> Macros can take arguments as well. If, for example, you want to allow users to embed images in their stories and comments but don't want them linking to any arbitrary picture out on the internet, you can create a macro with one argument that allows the user to specify the filename of an image in the directory you set. Arguments are used in the macro definition as {\bf ((1))} for the first argument, {\bf ((2))} for the second argument, and so on. With file uploads (\ref{features-file-uploads}) and this macro, users could put images in their upload directory into their stories but no other images.
248c334
< Once the archive database and archiving configuration are set, the actual {\bf process of archiving} is started using the Cron Admin Tool (\ref{admin-tools-cron}). The cron item {\bf archive\_stories} runs the code that checks the age of stories and comments, then archives those that match the criteria set in the Site Controls. The cron item {\bf poll\_archive} runs the code that checks the age of polls, then archives those that match the criteria set it the Site Controls.
---
> If you created a macro called {\bf img} and gave it the definition {\bf \latexhtml{$<$}{<}IMG src="\latexhtml{$\vert$}{|}upload\_link\_user\latexhtml{$\vert$}{|}((1))"\latexhtml{$>$}{>}} then a user could put {\bf ((img 2/filename.jpg))} in their story or comment, and that image would appear in their story. (The 2 in this example is the user's numeric UID.)
249a336
> If macros don't seem to be working, try putting {\bf ((macro\_test))} in a story or comment. If the system is active, that will be replaced by some red text telling you that the macro system is active. This macro is included by default as an example.
264,328c351,352
< \subsection{Headline Syndication (RDF)}
< \label{features-rdf}
<
< Many sites syndicate their headlines so other sites can link to their latest content easily. Scoop can fetch headlines from any number of other sites and allows users to choose which of those headlines they would like to see in their sidebar.
<
< Scoop can also create its own RDF feeds, and instead of just the headlines it includes the story's introduction as well.
<
< All of the variables referenced below should be in the RDF category of Site Controls.
<
< \subsubsection{Fetching Headlines}
< \label{rdf-fetching}
<
< RDF feeds to be fetched regularly are handled using the RDF Admin Tool (\ref{admin-tools-rdf}), and managing them requires the perm {\bf rdf\_admin} (\ref{perm-rdf-admin}). Enabled feeds are fetched on a schedule set in the {\bf rdf\_fetch} cron item (\ref{admin-tools-cron}).
<
< If the variable {\bf use\_rdf\_feeds} is on, then users may select from the enabled feeds for display in their sidebar. RDF feeds can be either added directly or submitted by users with the perm {\bf submit\_rdf} (\ref{perm-submit-rdf}). Submitted RDF {\bf feeds must be approved by the admin} before users can see them.
<
< Some RDF feeds include images, such as their site logo, in the feed; the variable {\bf rdf\_use\_images} determines whether or not Scoop will display that image with the RDF feed. Similarly, some feeds include text inputs, such as a search box that directs to the RDF source site; the variable {\bf rdf\_use\_forms} determines whether or not Scoop will display that form with the RDF feed.
<
< RDF feeds all include a different number of headlines, some of them quite large. You can restrict the number of headlines displayed with the variable {\bf rdf\_max\_headlines}; this number can be overridden by a user preference if the user wishes to see more headlines.
<
< \subsubsection{Publishing Headlines}
< \label{rdf-publishing}
<
< Scoop creates its RDF feed on a schedule set by the rdf cron item (\ref{admin-tools-cron}).
<
< The number of headlines included is determined by the number of stories posted either to front page or section in a certain time, set by the variable {\bf rdf\_days\_to\_show}, up to a maximum set in the variable {\bf rdf\_max\_stories}.
<
< Some meta-information can be included in the RDF file created, all set by variables. The copyright notice is set by the variable {\bf rdf\_copyright}; the RDF creator and publisher default to the site name as set in the variable sitename unless the variables {\bf rdf\_creator} and {\bf rdf\_publisher} are set, respectively. If you wish to include your site logo in the RDF feed, enter its full URL---including the http://---into the variable {\bf rdf\_image}. You should probably only include a small, button-sized image, just to avoid annoying the admins of other sites; they may reject your feed altogether if you include a large image.
<
< Finally, the file that the RDF feed is saved to is set in the variable {\bf rdf\_file}. This must be an absolute local pathname; the file {\bf must be writeable by the Apache server}'s user; and the file must be accessible from the internet.
<
< If you are using a location-based install, add an Alias line by the images Alias as below (the images Alias line is shown for reference):
< \begin{verbatim}
< Alias /scoop/ "/www/scoop/html/"
< Alias /scoop/images/ "/www/scoop/html/images/"
< \end{verbatim}
<
< 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 Digest Emails}
< \label{features-digest}
<
< Scoop can send headlines and summaries of stories posted to either front page or section since the last scheduled digest email. Daily digests are sent every day, weekly digests are sent on Sunday, and monthly digests are sent on the first of the month.
<
< To configure story digests, set the variable {\bf digest\_subject} to the desired subject line of the email. The content of the digest email is set using the blocks {\bf digest\_header}, {\bf digest\_footer}, and {\bf digest\_storyformat}. If you want the header and footer of your digest email to be the same, you can also use {\bf digest\_headerfooter}. If the blocks for both the separate and combined header and footer exist, the separate header and footer blocks are used.
<
< The subject is sent as-is to the digest recipients. The blocks used to format the content of the digest contain special keys documented in the block descriptions which are used to place the relevant information. HTML and regular block references should not be used in these blocks as the HTML in the stories is removed and the email sent as plain text.
<
< Once the digests are configured as you want them, set the variable {\bf enable\_story\_digests} to 1, and in the Cron Admin Tool (\ref{admin-tools-cron}) activate the {\bf digest} cron item. It should run no more than once per day, as the code does not check if it has already run that day, it simply sends the last day's (or week's, or month's) worth of stories.
<
< When {\bf enable\_story\_digests} is turned on, users are given a control which allows them to choose at what frequency they wish to receive story digests, if at all.
<
< \subsection{Flexible Sections and Categorization}
< \label{features-section-perms}
<
< Scoop's sections are designed to categorise the stories, but also have the ability to put one story in multiple sections, or restrict access to particular sections based on user group. Most section configuration is done using the Sections Admin Tool (\ref{admin-tools-sections}).
<
< Topics are a different way of categorising stories, and are represented by the image icon shown with the story. The topic and the section are completely independant of one another. Most topic configuration is done using the Topics Admin Tool (\ref{admin-tools-topics}).
<
< \subsubsection{Basic Sections and Topics}
< \label{sections-basic}
<
< For basic separation of content, topics and simple sections are all that is needed. You'll want to think carefully when creating your sections, because they can make content easy to find if they're set up properly, but incredibly hard to find if not.
<
< For most sites, you will want to split your sections based on the type of story that will go into it; for example, news, opinion or reviews. Such a split makes it instantly clear what will be found in each section. For more specialized sites, this may not be adequate; for example, a music or literature catalog may have sections for each genre, or if a single-genre catalogue, for each author.
---
> \subsection{Trusted Users and Mojo}
> \label{features-mojo}
330c354
< You will have to {\bf decide what set of sections best suits your site}, but it's worth thinking carefully over. If you decide to change your sections later, you will need to re-file all existing stories into their new proper sections.
---
> ``Mojo'' is the system Scoop uses to give or take certain {\bf comment-related privileges}. A user's mojo is not shown; the only way they can know approximately what it is is by whether or not they have those privileges---assuming they know what the mojo level required for the privileges is. A user's mojo is always a number in the range of possible comment ratings, set by the variables {\bf rating\_max} and {\bf rating\_min}. The perm {\bf super\_mojo} (\ref{perm-super-mojo}) overrides the mojo calculations and gives a user all the privileges gained by having high mojo.
332c356
< Topics are less constrained, but also have fewer options; for example, you can't restrict posting to a give topic the way you can with sections.
---
> Users with mojo higher than the number in the variable {\bf mojo\_rating\_trusted} are known as ``trusted users'', and uses with mojo lower than the number in the variable {\bf rating\_min} are known as ``untrusted users''. Users with mojo between these two numbers have no special name, they're just normal users.
334,335c358,361
< \subsubsection{Subsections and Stories in Multiple Sections}
< \label{sections-subsections}
---
> \begin{itemize}
> \item {\bf Trusted users} have the ability to see and rate comments one point below the minimum rating set in {\bf rating\_min}.
> \item {\bf Untrusted users} post with an initial rating matching their mojo; since by definition their mojo is below {\bf rating\_min}, only trusted users can see their comments. If a trusted user then rates the comment, the initial rating is overridden and the comment is either hidden or not, depending on the rating.
> \end{itemize}
337c363
< Sometimes you would prefer a {\bf heirarchical section structure}, rather than a flat section structure as described above. To turn on Scoop's subsection functionality, turn the variable {\bf enable\_subsections} on.
---
> Mojo is a {\bf time-weighted average of a user's comment ratings}, so a user must continually maintain his mojo level to remain trusted (or untrusted). Scoop fetches the user's most recent rated comments, limited by both number and date as set in the variables {\bf mojo\_max\_comments} and {\bf mojo\_max\_days}, respectively. If the variable {\bf mojo\_ignore\_diaries} is set, comments posted in a diary do not count towards either mojo or the maximum number of comments fetched.
339c365
< Stories filed in a heirarchical section behave much the same as stories filed in a flat section; that is, they are still posted to either the front page or the section. The navigation and display used to sort them is slightly different, however. If your {\bf index\_template} uses the box {\bf section\_title\_subsections} to display the section title, the path to the current section will be displayed in a familiar slash-delimited format, with each parent section name displayed as a link to the parent section's index page. There are no links to any child sections, however.
---
> Comments used in mojo calculations are weighted, with the most recent comments counting for the most; the most recent rated comment is given a weight equal to {\bf mojo\_max\_comments}, the second most recent is given a weight equal to mojo\_max\_comments - 1, and so on down until the last fetched comment. Both the number of ratings and the value of those ratings are multiplied by the weighting factor.
341c367
< Subsections can have {\bf more than one parent section}; in this case, the section title will have as many paths as the subsection has parents, recursively (that is, if a parent also has more than one parent section, it will also display all possible paths).
---
> 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.
343c369
< If you want a story to {\bf show up in multiple sections}, you can create a subsection and set each section you want the story to appear in as parents, then set that subsection as ``inheritable'' in the section configuration for each parent. Any story filed in the child section will then appear in each of the parent sections, even though the story's section link will be for the child section.
---
> 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.
345c371
< Yes, the inheritance is backward; parents get stories from their children.
---
> 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.
347,348c373,374
< \subsubsection{Private, Public, and Read-only Sections}
< \label{sections-perms}
---
> \subsection{Per-user File Uploads}
> \label{features-file-uploads}
350c376
< If desired, {\bf sections of the site can be made private}, denying access or even hiding the section's existence entirely, using section permissions. A section can be hidden from any user group, including just anonymous users.
---
> Scoop allows three types of file uploads. To have any file uploads at all, the variable {\bf allow\_uploads} must be turned on. The different types of uploads are given to specific user groups using Scoop's permission system.
352,356c378
< There are two ways of hiding sections:
< \begin{itemize}
< \item Scoop can return a ``permission denied'' error when the user tries to access it (Deny)
< \item Scoop can pretend the section doesn't exist if the user tries to access it (Hide)
< \end{itemize}
---
> \subsubsection{Story Text Uploads}
358c380
< Scoop shows the same behaviour for individual stories within the sections if the user finds a link directly to the story.
---
> Story text uploading allows users to write stories in their favourite program and upload the text file when posting the article; the uploaded file is then placed into the ``Extended Copy'' textarea on the submit story form when they preview. The file is not displayed in the previewed story until they preview again, it is only placed in the ``Extended Copy'' textarea.
360c382
< Some sections can also {\bf bypass the queue} entirely, for certain user groups, by giving those user groups ``Auto-post Front Page'' or ``Auto-post to Section'' permission. Those will automatically post a submitted story to the location indicated.
---
> If a file is uploaded when there is already content in the ``Extended Copy'' textarea, the content is replaced with the contents of the file. This can be useful for long articles when the author sees errors when previewing; the author can fix the error in the external program, save the file, then re-upload the corrected file and preview.
362c384
< You can also {\bf make sections read-only} for either comments or articles, based on the user group, by giving read but not post permission.
---
> Permission to upload files into the submit story form is given using the perm {\bf upload\_content} in the Groups Admin Tool. This feature is given on a per-group basis.
364c386
< Some {\bf examples of useful applications} of this feature include:
---
> \subsubsection{File Uploads}
366,370c388
< \begin{itemize}
< \item A ``Site News'' section, where only admins can post stories updating users of what's happening behind the scenes. Read and comment access is granted to all groups; Story Post permission is only given to admins, and they ``auto-post'' the story instead of sending it to the queue.
< \item An admin-only section, where only admins can post and read both comments and stories, where admins can discuss policy and problems, and all permissions are either denied or hidden to regular users.
< \item Keeping bots and casual passers-by (anonymous users) out of certain sections, but allowing registered users full access.
< \end{itemize}
---
> File upload gives the user their own directory on the server where they can upload any file, subject to the limits imposed by the admin on upload size and total directory size.
372,373c390
< \subsection{Trusted Users and Mojo}
< \label{features-mojo}
---
> Each user has his own directory and can only change his own directory, but all users can browse a user's files through the files link on the user info page.
375c392
< ``Mojo'' is the system Scoop uses to give or take certain {\bf comment-related privileges}. A user's mojo is not shown; the only way they can know approximately what it is is by whether or not they have those privileges---assuming they know what the mojo level required for the privileges is. A user's mojo is always a number in the range of possible comment ratings, set by the variables {\bf rating\_max} and {\bf rating\_min}. The perm {\bf super\_mojo} (\ref{perm-super-mojo}) overrides the mojo calculations and gives a user all the privileges gained by having high mojo.
---
> To set up the upload area, the variable {\bf upload\_path\_user} must be set to an absolute local path. Apache must have full write permissions to the directory, so it can manage files in it. The directory must also be accessible from outside via the web. The variable {\bf upload\_link\_user} must be set to an absolute external path or URL, the external address of the directory named in the previous variable. The directory named in the above two variables is used as a base directory; each user gets a subdirectory for his own files.
377c394
< Users with mojo higher than the number in the variable {\bf mojo\_rating\_trusted} are known as ``trusted users'', and uses with mojo lower than the number in the variable {\bf rating\_min} are known as ``untrusted users''. Users with mojo between these two numbers have no special name, they're just normal users.
---
> Permission to use the upload area is given using the perm {\bf upload\_user} in the Groups Admin Tool. This feature is given on a per-group basis.
379,382c396
< \begin{itemize}
< \item {\bf Trusted users} have the ability to see and rate comments one point below the minimum rating set in {\bf rating\_min}.
< \item {\bf Untrusted users} post with an initial rating matching their mojo; since by definition their mojo is below {\bf rating\_min}, only trusted users can see their comments. If a trusted user then rates the comment, the initial rating is overridden and the comment is either hidden or not, depending on the rating.
< \end{itemize}
---
> The variables {\bf upload\_delete} and {\bf upload\_rename} determine whether or not users with permission to use the upload area can also delete and rename their files, respectively. Since the file upload feature can be used to store files used by the user in stories published on the site, refusing to allow the user to delete or rename uploaded files can prevent broken links within the site.
384c398
< Mojo is a {\bf time-weighted average