to perform upgrades and makes it impossible to use tools such as
mod_perl, at least if you want more than one site on the machine.
+F<bse.cfg> is read as a utf-8 encoded file.
+
=head1 CONFIGURATION ENTRIES
=head2 [site]
Default: no front-end server configured.
+=item secret
+
+A secret used (currently) for hashing cookie values passed between the
+secure and non-secure parts of the site. This must be set. A
+suitable value can be created with:
+
+ openssl rand -base64 32
+
=back
=head2 [paths]
templates directory. This can contain references like $(section/key)
to other configuration entries. Split on the system's PATH separator.
+=item public_html
+
+Web server document root. Static pages are generated under this
+directory. Default: $CONTENTBASE.
+
=item images
Where uploaded images are stored. This is not yet completely
Local search path for BSE::Custom, or the class configured by
C<custom_class> in [basic].
+=item scalecache
+
+The directory where cached versions of scaled thumbnails are stored.
+Defaults to I<[paths].images>F</scaled>. This must be in the document tree. If
+you set this you should also set I<[uri].scalecache>.
+
=item siteuser_images
Where uploaded siteuser images are stored. This must be set in the
Pregenerated dynamic article pages are stored here. This must be
defined if you site contains any dynamicly generated pages.
-=item scalecache
-
-The directory where cached versions of scaled thumbnails are stored.
-Defaults to image_dir/scaled. This must be in the document tree. If
-you set this you should also set scalecacheurl.
-
-=item scalecacheurl
+=item public_files
-The URL to the directory represented by scalecache. Defaults to
-/images/scaled.
+The directory to store public BSE::TB::File content in (currently used
+for application specific files.)
=back
Catalog editor page. Default admin/edit_catalog.tmpl
-=item 1
+=item Z<>1
-=item 2
+=item Z<>2
-=item 3
+=item Z<>3
-=item 4
+=item Z<>4
-=item 5
+=item Z<>5
Article edit pages. Default admin/edit_<number>.tmpl
The salt used in generating the has for redirect_links. Default: an
empty string.
+=item validate
+
+If non-zero then any HTML output is validated with HTML::Tidy.
+Validation errors and warnings are sent to the audit log. See [html
+tidy].
+
+=item tagformat
+
+The default tag formatting to use for C<< <:= ... :> >> tags.
+Default: C<html>.
+
+=item formatter_image_class
+
+The default class to use for image[...] tags in body text. Default:
+C<bse_image_inline>.
+
=back
=head2 [basic]
=over
-=item cookie_lifetime
+=item access_control
-The expiry time for cookies. This should be in the form supported by
-CGI.pm for the -expires parameter. Typically you want a plus ('+'), a
-number, and a time character (s - seconds, m - minutes, h - hours, d -
-days, M - months). Default: +3h
+If this is true then the user/group/permissions database is used to
+control access to the system. Default: False.
-=item cookie_domain
+=item access_filter_parents
-This overrides the domain value set for cookies. This is useful if
-you allow the site to run under both example.com and www.example.com,
-if you set cookie_domain to example.com then a user visiting
-www.example.com will still have their cookies when they visit
-example.com.
+If this is true, then the drop-down lists of possible parents on the
+newsletter edit pages are filtered for access control.
+Default: False.
-=item cookie_name
+=item access_filter_steps
-This overrides the cookie name used to store the session id. Default:
-sessionid. This is useful when you have 2 sites under the same
-top-level domain, and helps disambiguate the cookie returned by the
-browser.
+If this is true, then the drop-down lists of possible stepparents and
+stepchildren on the article edit pages are filtered for access control.
+Default: False.
-=item minpassword
+=item alias_prefix
-Minimum password length in characters. Default: 4.
+The prefix applied to articles that use a linkAlias url. This should
+start with a /.
-=item randomdata
+=item alias_recursive
-Device to read random data from. This device should not block when it
-runs out of entropy.
+If this is non-zero then the link is formed by the C<alias_prefix>,
+followed by slash (C</>) separated aliases from the ancestors starting
+from the section, followed by the C<alias_suffix>. You may need to
+change your redirect handling if you enable this. Default: Off.
-=item sign
+=item alias_suffix
-If this is true then the encrypted messages containing the customer's
-credit card number are sent to the shop owner signed. To avoid
-keeping a passphrase and signing key on the server you can set this to
-false (0). This has the effect that anyone could send you an unsigned
-message encrypted with your public key, though this may not be a
-security threat. Default: True.
+If this is non-zero then the title is cleaned up (all but
+alphanumerics removed) and appended to the alias URL generated.
-=item link_titles
+=item all_dynamic
-If this is true then the links to your articles within BSE will be
-followed by a / and then by a simplified version of the article title.
-The aim is to include at least some title information in the URL
-without modifying the name of the HTML file. Default: False.
+If true then all articles are treated as dynamic. Default: false.
-=item access_control
+=item auto_images
-If this is true then the user/group/permissions database is used to
-control access to the system. Default: False.
+By default, if the author doesn't use any image tags, BSE will insert
+any unnamed article images into the body text of an article. You can
+disable this on a per-article basis in the image tool, or disable it
+globally by setting C<auto_images> to 0.
-=item access_filter_steps
+An alternative is to set C<imagePos> in C<[article defaults]> to
+C<xx> which will default articles to not auto-inserting images.
-If this is true, then the drop-down lists of possible stepparents and
-stepchildren on the article edit pages are filtered for access control.
-Default: False.
+=item cache_templates
-=item access_filter_parents
+If true, BSE will cache compiled templates using the configured BSE
+cache, if any. Depending on the configured cache this may slow things
+down. Default: disabled.
-If this is true, then the drop-down lists of possible parents on the
-newsletter edit pages are filtered for access control.
-Default: False.
+=item cache_templates_locally
-=item server_auth
+If true, BSE will cache compiled templates in memory. This may
+significantly improve performance but may increase memory use.
+Default: disabled.
-Set this to non-zero to enable authentication via server
-authentication (usually Basic Authentication.) You should normally
-set this if you set htusers below. Default: 0 (disabled)
+=item cache_thumbnails
-=item htusers
+If set to zero the results of the thumbimage/gthumbimage body/template
+tags will not be cached. Default: 1 (caching is enabled).
-This should be the path to a file to be updated with the list of users
-and crypt() versions of their passwords. If this is set then the
-security system will check for a user set by the browser before
-attempting a form based logon. Default: None.
+=item cookie_domain
+
+This overrides the domain value set for cookies. This is useful if
+you allow the site to run under both example.com and www.example.com,
+if you set cookie_domain to example.com then a user visiting
+www.example.com will still have their cookies when they visit
+example.com.
+
+=item cookie_lifetime
+
+The expiry time for cookies. This should be in the form supported by
+CGI.pm for the -expires parameter. Typically you want a plus ('+'), a
+number, and a time character (s - seconds, m - minutes, h - hours, d -
+days, M - months). Set to an empty string for session cookies.
+Default: +3h
+
+=item cookie_name
+
+This overrides the cookie name used to store the session id. Default:
+sessionid. This is useful when you have 2 sites under the same
+top-level domain, and helps disambiguate the cookie returned by the
+browser.
=item custom_class
used for article editing customizations. This class should derive
from BSE::CustomBase. Default: BSE::Custom.
-=item jit_dynamic_pregen
+=item default_popupimage
-If this is true, then pre-generation for dynamic pages will be delayed
-until the page is displayed to a user. Default: off.
+This is the default popup image class for the popimage[] and
+gpopimage[] tags. Default: popup.
-=item staticajax
+=item dynamic_access_filter
-If true, the ifAjax and ajax tags will be active for static pages.
+If set to 0, dynamic article iterators will no access control filter
+their results. Default: 1.
-=item cache_thumbnails
+=item error_not_defined
-If set to zero the results of the thumbimage/gthumbimage body/template
-tags will not be cached. Default: 1 (caching is enabled).
+If non-zero, during dynamic page generation, inserts a message
+explaining which variable is not set, instead of just leaving the tag
+unreplaced. Default: 1.
-=item static_thumbnails
+=item http_only_session
-If true and cache_thumbnails is true then thumbnails for the thumbnail
-cache will be generated when a static page is regenerated, and the
-link from the page will link to the image in the cache rather than to
-C<thumb.pl>. Default: 1 (static thumbnails enabled).
+If this is non-zero, the default, the session cookie sent to the
+browser has the C<HttpOnly> attribute set. This can prevent session
+cookie hijacking. Default: 1.
-=item alias_prefix
+=item htusers
-The prefix applied to articles that use a linkAlias url. This should
-start with a /.
+This should be the path to a file to be updated with the list of users
+and crypt() versions of their passwords. If this is set then the
+security system will check for a user set by the browser before
+attempting a form based logon. Default: None.
-=item use_alias
+=item index_file
-If this is non-zero then an article with linkAlias set will use an
-alias url instead of the "real" url. You will need to configure a
-RewriteRule or ErrorDocument to page.pl to direct the user to the
-correct URL. Default: 1.
+The name of the file to generate for static articles when the link is
+terminated by "/". Default: C<index.html>.
-=item alias_suffix
+=item jit_dynamic_pregen
-If this is non-zero then the title is cleaned up (all but
-alphanumerics removed) and appended to the alias URL generated.
+If this is true, then pre-generation for dynamic pages will be delayed
+until the page is displayed to a user. Default: off.
-=item default_popupimage
+=item link_titles
-This is the default popup image class for the popimage[] and
-gpopimage[] tags. Default: popup.
+If this is true then the links to your articles within BSE will be
+followed by a / and then by a simplified version of the article title.
+The aim is to include at least some title information in the URL
+without modifying the name of the HTML file. Default: False.
-=item warn_obsolete
+=item make_userid_cookie
-Some obsolete tags will warn to stderr if this is non-zero. Default:
-don't warn.
+If this is non-zero, the default, then when the site member logs in, a
+javascript visible cookie, C<userid> will be set that contains the
+login name of the user. BSE's back-end doesn't use this cookie, its
+only use is for Javascript to enable/disable user interface elements.
+Default: 1.
+
+=item minpassword
+
+Previously the minimum length of site user passwords in characters.
+You must now set C<length> in C<[siteuser passwords]>.
=item no_cache_dynamic
I<templatename>C<].no_cache_dynamic> and [article].no_cache_dynamic.
Default: 1.
+=item preload_template
+
+Preload the named template, searching the template search part. Any
+text that would normally be produced by the preloaded template is
+ignored. This can be useful for common definitions and variables for
+use in many templates. Default: none.
+
+=item randomdata
+
+Device to read random data from. This device should not block when it
+runs out of entropy.
+
=item redir_to_alias
If true then page.pl will 301 redirect (Moved Permanently) requests
for an article by its id to the generated link if the article has a
link alias. Default: false. Must only be used with use_alias true.
+=item secure_session
+
+If this is non-zero then the session cookie sent to the browser has
+the C<Secure> attribute set. This means that the cookie will only be
+visible over https. This is only useful when the only URL the site is
+visited over is a https URL. Default: 0.
+
+=item server_auth
+
+Set this to non-zero to enable authentication via server
+authentication (usually Basic Authentication.) You should normally
+set this if you set htusers below. Default: 0 (disabled)
+
+=item sign
+
+If this is true then the encrypted messages containing the customer's
+credit card number are sent to the shop owner signed. To avoid
+keeping a passphrase and signing key on the server you can set this to
+false (0). This has the effect that anyone could send you an unsigned
+message encrypted with your public key, though this may not be a
+security threat. Default: True.
+
+=item staticajax
+
+If true, the ifAjax and ajax tags will be active for static pages.
+
+=item static_thumbnails
+
+If true and cache_thumbnails is true then thumbnails for the thumbnail
+cache will be generated when a static page is regenerated, and the
+link from the page will link to the image in the cache rather than to
+C<thumb.pl>. Default: 1 (static thumbnails enabled).
+
=item track_uploads
If this is non-zero, and a cache is configured (see [cache]), file
upload progress information to the user. The upload state is updated
a maximum of once a second.
-=item http_only_session
-
-If this is non-zero, the default, the session cookie sent to the
-browser has the C<HttpOnly> attribute set. This can prevent session
-cookie hijacking. Default: 1.
-
-=item secure_session
+=item use_alias
-If this is non-zero then the session cookie sent to the browser has
-the C<Secure> attribute set. This means that the cookie will only be
-visible over https. This is only useful when the only URL the site is
-visited over is a https URL. Default: 0.
+If this is non-zero then an article with linkAlias set will use an
+alias url instead of the "real" url. You will need to configure a
+RewriteRule or ErrorDocument to page.pl to direct the user to the
+correct URL. Default: 1.
-=item make_userid_cookie
+=item warn_obsolete
-If this is non-zero, the default, then when the site member logs in, a
-javascript visible cookie, C<userid> will be set that contains the
-login name of the user. BSE's back-end doesn't use this cookie, its
-only use is for Javascript to enable/disable user interface elements.
-Default: 1.
+Some obsolete tags will warn to stderr if this is non-zero. Default:
+don't warn.
=back
being sent to a member record, will be sent as HTML, if the HTML
template is available.
+=item inline_css
+
+If this is C<style> (the default) then use CSS::Inliner to attempt to
+inline CSS in mail if the text "<style" is found in the generated
+HTML.
+
+If this is C<force> then we always attempt to inline CSS.
+
+If this is any other value then don't inline CSS.
+
+=item inline_css_flags
+
+A comma separated list of flags to supply to CSS::Inliner->new().
+Reasonable flags are C<strip_attrs> to strip C<id> and C<class>
+attributes, and C<leave_style> to leave the HTML style block in place.
+
+Default: no flags.
+
+=item inline_css_report
+
+If this is true and CSS inlining fails, log an error to the audit
+log. This is intended for use in debugging and should be disabled in
+production. Default: false (disabled)
+
=back
=head2 [children of I<id>]
The field specific word match regular expression for the built-in
search indexer. Default: the value of C<wordre>.
-=back
+=item indexer
-=head2 [search highlight]
+Module used to build the search index. Default: BSE::Index::BSE.
-Sets the prefix and suffix used for highlighting matches for different
-fields.
+=item index_priority
-These are used by the highlight_result, excerpt, pageTitle, author,
-keywords and matchFile tags.
+For C<BSE::Index::BSE>, the optimization priority. The default of
+C<speed> builds the index in memory and is very fast, but can consume
+a lot of memory. Otherwise, set this to C<memory> to reduce memory
+usage.
-Each field has a prefix and suffix entry. The key is
-I<fieldname>_prefix or I<fieldname>_suffix. For file fields this is
-file_I<fieldname>_prefix and file_I<fieldname>_suffix.
+C<memory> priority index building requires that the C<DBM::Deep>
+module be installed.
-The default prefix is <b>. The default suffix is </b>.
+=item level
-For example you can do:
+Articles with a higher level than this are indexed as their ancestor.
+Default: C<$SEARCH_LEVEL> which defaults to 5.
+
+=item case_sensitive
+
+Level of case-sensitivity in the search engine. This can be one of:
+
+=over
+
+=item *
+
+C<none> - no case-sensitive searches
+
+=item *
+
+C<context> - case-sensitive if there are any upper-case characters in
+the search string, case-insensitive otherwise.
+
+=item *
+
+C<controlled> - case-sensitive via a query parameter. This is
+currently not supported by the built-in search engie.
+
+=back
+
+Renegerate your search indexes after changing this value. Default:
+context.
+
+=back
+
+=head2 [search highlight]
+
+Sets the prefix and suffix used for highlighting matches for different
+fields.
+
+These are used by the highlight_result, excerpt, pageTitle, author,
+keywords and matchFile tags.
+
+Each field has a prefix and suffix entry. The key is
+I<fieldname>_prefix or I<fieldname>_suffix. For file fields this is
+file_I<fieldname>_prefix and file_I<fieldname>_suffix.
+
+The default prefix is <b>. The default suffix is </b>.
+
+For example you can do:
[search highlight]
body_prefix=<span class="searchfound">
body_suffix=</span>
+
+The default prefix and suffix can also be redefined:
+
+ [search highlight]
+ prefix=<mark>
+ suffix=</mark>
=head2 [shop]
2 - contact customer for details
+=item *
+
+4 - paypal - see L<paypal.pod>
+
=back
Other types can be added by adding entries to the [payment type names]
To email for emailed orders sent by the shop. Overrides $SHOP_TO_EMAIL
in Constants.pm
+=item bcc_email
+
+BCC email address for order confirmation emails sent to the customer.
+Default: No bcc.
+
=item noencrypt
If this is true then orders sent to you by the shop will not be
distinct products (with options) in the cart, not the total
quantities. Default: Unlimited.
+=item currency_code
+
+The shop currency as a 3-letter currency code. Default: AUD.
+Currencies other than "AUD" aren't supported by most of the system.
+
+=item country_code
+
+Set to non-zero if you're using country codes in the order country
+field. If this is set then the delivCountry is supplied as is to
+various parts of the system, otherwise it is translated from a country
+name to a country code. Default: 0.
+
+=item require_fields
+
+A comma separated list of extra fields to require during checkout.
+This is in addition to the usual fields required during checkout.
+Default: none.
+
+=item require_delivery
+
+If true, and the C<need_delivery> CGI parameter is true, treat the
+following delivery fields as required during checkout: delivFirstName,
+delivLastName, delivStreet, delivSuburb, delivPostCode and delivCountry.
+Default: true.
+
+=item require_delivery_fields
+
+If C<require_delivery> is true, and the C<need_delivery> CGI parameter
+is true, add the comma separated fields listed here to the required
+checkout fields list. Default: none.
+
=back
=head2 [shipping]
AustraliaPost::Air". These will be made available as shipping methods
on the checkout page.
+=item quoted
+
+If true then a default "Quote shipping charges later" shipping method
+will be added to the shipping methods list.
+
=item sourcepostcode
The post code from which products are shipped.
If non-zero then the ifUserCan tag will output some trace information
to STDERR.
+=item trace_noimpl
+
+Enables some trace messages from tags that return an ENOIMPL
+exception. This can be useful for tracking down why a tag isn't being
+replaced. This will produce a lot of output during page regeneration.
+
=back
=head2 [uri]
=over
+=item articles
+
=item cgi
The URI to the CGI directory. Default: /cgi-bin
+=item dist_images
+
+The URI where images included with BSE can be found.
+
+This includes images such as F<trans_pixel.gif> and C<admin/error.gif>.
+
+Default: C</images>
+
=item images
-The URI where images are kept. Default: /images
+The URI where managed images are kept which should correspond to
+C<images> in C<[paths]>.
-=item shop
+Default: C</images> (from C<$Constants::IMAGES_URI>)
-=item articles
+=item scalecache
+
+The URL to the directory represented by scalecache. Defaults to
+I<[uri].images>F</scaled>.
+
+=item public_files
+
+The URL to the directory configured as I<[paths].public_files>.
+
+=item shop
=back
=item require_name2
-=item require_address
+=item require_street
-=item require_city
+=item require_suburb
=item require_state
If non-zero then email id C<notify_register_customer> will be sent to
new user on registration. By default this uses template
user/email_register, subject "Thank you for registering" which can be
-overridden in [email notify_register_customer]
+overridden in [email notify_register_customer] or via the
+C<set_subject> tag.
+
+=item notify_register_customer_admin
+
+If non-zero then the behaviour described for
+C<notify_register_customer> will take place when a new member is added
+by an administrator. Defaults to the value of
+C<notify_register_customer>.
=back
1=some name
[query group some name]
- sql=select id from site_users where id = ? and name1 like '%some%'
+ sql=select id from bse_siteusers where id = ? and name1 like '%some%'
Each entry also has a corresponding [Query Group I<name>] section.
=back
-=over
-
-=back
-
=head2 [inpho]
This is used to configure the DevHelp::Payments::Inpho module.
[cookie names]
userid=altuserid
-=item [siteuser updates]
+=head2 [siteuser updates]
Each key identifies an update specification for userupdate.pl, the
value is a description of the specification.
-See L<<[siteuser update I<specid>]>> for the rest of the import
+See L<< [siteuser update I<specid>] >> for the rest of the import
specification.
+
=head2 [siteuser update I<specid>]
Currently contains only a single key:
=back
+=head2 [paypal]
+
+Configuration for BSE's PayPal integration.
+
+It shouldn't be necessary to change any of the URLs.
+
+=over
+
+=item *
+
+test - if true, then the PayPal sandbox is used, and the configuration
+entries starting in C<test_> are used. If false, PayPal is live, and
+configuration entries starting in C<live_> are used. Default: 1.
+
+=item *
+
+test_api_username, test_api_password, test_api_signature - API
+credentials for test mode. Required in test mode.
+
+=item *
+
+live_api_username, live_api_password, live_api_signature - API
+credentials for live mode. Required for live mode.
+
+=item *
+
+test_ws_url - URL to make NVP requests through in test mode. Default:
+https://api-3t.sandbox.paypal.com/nvp
+
+=item *
+
+test_refresh_url - PayPal URL to refresh to in test mode. Default:
+https://www.sandbox.paypal.com/webscr
+
+=item *
+
+live_ws_url - URL to make NVP requests through in live mode. Default:
+https://api-3t.paypal.com/nvp
+
+=item *
+
+live_refresh_url - PayPal URL to refresh to in live mode. Default:
+https://www.paypal.com/cgibin/webscr
+
+=back
+
+=head2 [paypal custom]
+
+Extra parameters supplied to the SetExpressCheckout API. See the
+Express Checkout Advanced Features Guide (from PayPal) for details.
+
+Some settings that may be useful:
+
+=over
+
+=item *
+
+PAGESTYLE - the style of payment page to use from those listed in your
+account profile.
+
+=item *
+
+HDRIMG - https URL to an image to use in the payment page header.
+
+=item *
+
+HDRBACKCOLOR - a 6 hex digit color to use as the background of the
+payment page header.
+
+=item *
+
+HDRBORDERCOLOR - a 6 hex digit color to use as the border of the
+payment page header.
+
+=back
+
+=head2 [audit log]
+
+=over
+
+=item *
+
+mail - if non-zero any emails sent through BSE::ComposeMail are logged
+in the audit log. Default: 0.
+
+=item *
+
+mail_max_dump - if non-zero this is the size limit of the dump stored
+in the audit log when [audit log].mail is enabled. Default: 50000.
+
+=back
+
+=head2 [audit log I<facility>]
+
+Most commonly C<[audit log bse]>. Controls whether given events or
+families of events are logged.
+
+The key is one of:
+
+=over
+
+=item I<component>
+
+=item I<component>C<:>I<module>
+
+=item I<component>C<:>I<module>C<:>I<function>
+
+=back
+
+with the longer keys overriding the shorter keys, and defaulting to
+all actions being logged.
+
+=head2 [mail audit log]
+
+This enables sent when an event is logged in the audit log. Warning:
+for common events this will result in large amounts of email.
+
+=over
+
+=item *
+
+to - the email address to send the email to
+
+=item *
+
+emerg, alert, crit, error, warning, notice, info, debug - if present
+and true then events at these levels result in an email. If the value
+contains an C<@> then the value is used as the recipient address.
+
+=item *
+
+I<facility>-I<component>
+
+=item *
+
+I<facility>-I<component>-I<module>
+
+=item *
+
+I<facility>-I<component>-I<module>-I<function>
+
+Controls sending an email for specific events or families of events.
+If the value is true, send an email for that event. If the value
+contains an C<@> then the value is used as the recipient address.
+
+=back
+
+with the longer keys overriding the shorter keys, and defaulting to
+all actions being logged.
+
+=head2 [html tidy]
+
+Contains options to pass to HTML::Tidy. Anything not listed below is
+passed directly to HTML::Tidy->new.
+
+=over
+
+=item *
+
+ignore_types - types of message to ignore separated by commas, any,
+all or none of info, warning, error.
+
+=item *
+
+ignore_text_I<key> - messages to ignore, I<key> is not used, just the
+value.
+
+
+=back
+
+=head2 [email I<token>]
+
+Controls emails sent via F<cgi-bin/admin/sendemail.pl>.
+
+=over
+
+=item *
+
+template - plain text template
+
+=item *
+
+html_template - HTML template (defaults to the value of I<template>
+followed by C<_html>
+
+=item *
+
+subject - subject of the email, can be overridden with the
+C<set_subject> tag.
+
+=item *
+
+from - from email address, defaults to the shop from address
+
+=item *
+
+from_name - from name
+
+=item *
+
+allow_html - controls whether HTML is allowed. By default this is
+based on the user's settings.
+
+=back
+
+=head2 [lost password]
+
+=over
+
+=item *
+
+daily_limit - the number of recovery attempts permitted per day.
+Default: 3.
+
+=item *
+
+age_limit - the id included in the email is valid for this many days.
+Default: 7.
+
+=back
+
+=head2 [link replacement]
+
+For formatted text, this is a list of URL prefixes to replace.
+
+The key is a sort key, replacements are checked in alphabetical order.
+
+The value is the original prefix, followed by ";", followed by the
+replacement.
+
+Replacement is performed case-insenitively. Regexp metacharacters
+
+=head2 [article categories]
+
+=over
+
+=item *
+
+ids - a comma separated list of category ids. There are (currently)
+no restrictions on the contents of these ids, but alphanumerics are
+recommended to simplify templates.
+
+=item *
+
+I<id> - a description for a particular category id. Overridden by the
+C<name> key in C<< [article category I<id>] >>. Default: ucfirst of
+the id.
+
+=back
+
+=head2 [article category I<id>]
+
+=over
+
+=item *
+
+name - name of the article category.
+
+=back
+
+Other keys may be used as desired, eg. to make it simpler to configure
+article behaviour based on the category.
+
+=head2 [article menu]
+
+This section can be used to add new menu items to the menu displayed
+on article edit pages.
+
+The keys are used for sorting only.
+
+The value is comma-separated:
+
+=over
+
+=item *
+
+target script name
+
+=item *
+
+target identifier, to be set to 1 on making a request to the script.
+
+=item *
+
+the label for the item in the menu.
+
+=back
+
+eg.
+
+ sample,a_foo,Sample Item
+
+will generate a link like:
+
+ <a href="/cgi-bin/admin/sample.pl?id=10&a_foo=1">Sample Item</a>
+
+where 10 is the id of the article being edited.
+
+Keys with a prefix of C<bse_> are reserved for BSE internal use.
+
+=head2 [undeletable articles]
+
+Keys are the ids of articles that may not be deleted.
+
+This applies if the value of the entry is a true perl value.
+
+ [undeletable articles]
+ 1=home page
+ 2=more home page
+ ; article 3 is deletable
+ 3=
+
+=head2 [dummy shipping methods]
+
+Configures extra shipping methods only selectable from the order
+detail page.
+
+Entries are sorted by value.
+
+If the value contains a comma the text up to the comma is removed and
+the remains used as the label, otherwise the key is used as the label.
+
+=head2 [article custom fields]
+
+=head2 [product custom fields]
+
+=head2 [catalog custom fields]
+
+These can be used to define article, product and catalog custom fields
+respectively, in a similar manner to L<formmail>.
+
+The field names are predefined, C<customDate1>, C<customDate2>,
+C<customInt1>, C<customInt2>, C<customInt3>, C<customInt4>,
+C<customStr1> and C<customStr2>, but are only active if a description
+is defined for the field:
+
+ [article custom fields]
+ customInt1_description=Stock Level
+
+=head2 [siteuser passwords]
+
+Rules for validating (not verifying) site user passwords. Possible
+keys are:
+
+=over
+
+=item *
+
+C<length> - the minimum length of passwords. This replaces
+C<minpassword> in C<[basic]>.
+
+=item *
+
+C<entropy> - the minimum password entropy as measured by
+L<Data::Password::Entropy>.
+
+=item *
+
+C<symbols> - if non-zero, the password must contain non-alphanumerics.
+
+=item *
+
+C<digits> - if non-zero, the password must contain digits.
+
+=item *
+
+C<mixedcase> - if non-zero, the password must contain both upper and
+lower case letters.
+
+=item *
+
+C<categories> - the number of categories out of 5 required out of
+symbols, digits, upper case, lower case and extended ASCII/Unicode.
+This should typically never be 5.
+
+=item *
+
+C<notuser> - the password and user name may not match each other
+case-insensitively.
+
+=item *
+
+C<notu5er> - the password may not match the user name
+case-insensitively, even with symbol replacement (e.g. "5" for "S".
+
+=back
+
+=head2 [admin user passwords]
+
+Rules for validating (not verifying) administrative user passwords.
+See L</[siteuser passwords]> on the keys that can be set.
+
+=head2 [site user lockouts]
+
+Controls when accounts and IP addresses are locked out due to repeated
+site user authentication failures.
+
+=over
+
+=item *
+
+I<account maximum failures> - the maximum number of login failures for
+a given account in I<account time period>. A successful login of the
+account resets the count. Default: 3.
+
+=item *
+
+C<account_time_period> - the number of minutes in which
+C<account_maximum_failures> login failures occurring will cause an
+account lock-out. Default: 10.
+
+=item *
+
+C<account_lockout_time> - the number of minutes to lock out an account
+that fails too many logins. Default: 60.
+
+=item *
+
+C<ip_maximum_failures> - the maximum number of login failures for a
+given IP address with-in C<ip_time_period>. A successful login of any
+account at the IP address resets the count. Default: 10.
+
+=item *
+
+C<ip_time_period> - the number of minutes in which
+C<ip_maximum_failures> login failures occurring causes an IP address
+lock-out. Default: 30.
+
+=item *
+
+C<ip_lockout_time> - the number of minutes to lock out an IP
+address that fails too many logins. Default: 120.
+
+=item *
+
+C<ip_maximum_failures2> - the maximum number of login failures for a
+given IP address with-in C<ip_time_period>. A successful login of any
+account at the IP address I<does not reset> the count. Default: 50.
+
+=item *
+
+C<ip_lockout_time2> - the number of minutes to lock out an IP address
+that fails too many logins against C<ip_maximum_failure2>. Default:
+120.
+
+=back
+
+Note: an administrator unlocking an account resets the account lock
+count but has no effect on the IP address lock count. An
+administrator unlocking an IP address resets both IP address lock
+counts, but has no effect on account lock counts.
+
+=head2 [admin user lockouts]
+
+Control account and IP address lockouts for admin user authentication.
+
+See L</[site user lockouts]> for details of the configuration
+possible.
+
+=head2 [pregenerate]
+
+Defines templates to be generated as base templates.
+
+Each entry is of the form:
+
+=over
+
+I<output-template>=I<profile-name>,I<input-template>
+
+=back
+
+where:
+
+=over
+
+=item *
+
+I<output-template> - the output template name, stored in the directory
+defined by [paths].templates
+
+=item *
+
+I<profile-name> - used to select a section in the config file to load
+dummy article settings from, as C<< [I<profile-name> settings] >>.
+
+=item *
+
+I<input-template> - the source template to generate from.
+
+=back
+
=head1 AUTHOR
Tony Cook <tony@develop-help.com>