=head1 NAME

Bric::FAQ - Bricolage Frequently Asked Questions

=head1 VERSION

$LastChangedRevision$

=head1 DATE

$LastChangedDate: 2004-06-21 09:57:14 -0700 (Mon, 21 Jun 2004) $

=head1 DESCRIPTION

This document tries to answer questions asked frequently
on the mailing list or other questions that people might
have when starting out with or evaluating Bricolage.

=head1 FAQs

=head2 Evaluating Bricolage

This section answers questions that someone evaluating
Bricolage might have.

=head3 Does Bricolage support databases other than PostgreSQL?

Currently only PostgreSQL support is maintained. There is an Oracle driver,
but it's old and not known to work. A port to MySQL 4.1 is reportedly
underway.

=head3 Is there any pre-compiled packages for Bricolage?

There is a FreeBSD port for Bricolage 1.8. To use it, simply update your ports
tree, and then:

  cd /usr/ports/www/bricolage
  make
  make install

There is currently only a tentative start for a bricolage debian package, and
unfortunately, it is rather out of date. The location of the package is
L<http://people.debian.org/~erich/bricolage>.

To use this package, add the following line to your F</etc/apt/sources.list> file:

   deb http://people.debian.org/~erich/bricolage   /

Then update your package database and install bricolage using C<dselect> or
standard C<apt-get> commands.

As of this writing, the package downloads and installs all necessary packages,
but you still need to read through the instructions in
F</usr/share/doc/bricolage/README.Debian> to setup a usable Bricolage
installation. Please also note that the debian package may be out-of-sync with
the standard distribution.

=head3 Are there any Bricolage System that runs directly from CD?

There is currently an effort to make a KNOPPIX-style CD for
Bricolage. Informally this CD is known as KNOPPIX with Bricolage. It is a CD
that contains a Linux Distribution (Debian in this case) with Bricolage
preinstalled. The system is self-contained on a CD and the user merely needs
to boot an i386-compatible computer from the CD. The CD will not in any way
alter the content of your hard disk. This CD is useful for evaluating
Bricolage since it removes the hassle of installation. Although it is
certainly possible to transfer the Bricolage installation on the CD to your
hard disk, we do not expect this to be the standard procedure to install
Bricolage after evaluation. Rather, it is better to download the Bricolage
sources from sourceforge.net and install it.

The KNOPPIX with Bricolage CD is based on Erich Schubert's Debian package, and
was created by Mark Jaroski as a demonstration of Bricolage.
as Brico-Knoppix.

The CD is available here: L<http://www.geekhive.net/~mark/brico-knoppix-1.0.iso>

=head3 How well does Bricolage perform?

As far as we know, no one has performed any benchmarks comparing Bricolage to
other content management systems. But the performance of Bricolage is
irrelevant to a public facing site. As a back office content management and
publishing system, Bricolage does not host web sites or serve content. Rather,
when documents are published in Bricolage, they are pushed through templates
and the resulting files are distributed to your Web server. So if your
Bricolage templates output static HTML, your public Web server should serve
your content very fast indeed since performanc depends entirely on the
scalability of your Web server.

=head3 Advantages of using Bricolage

The separation of the content management and publishing server from the front
end Web server is one of the major strength of Bricolage:

=over 4

=item *

It makes it easy add more capacity to your site to meet increasing demand:
just add another Web server and configure Bricolage to distribute files
to it.

=item *

It improves security, as a compromise of the front-end Web server does not
compromise your data, which is stored on in the Bricolage database server on
the back end, possibly behind a firewall.

=item *

The overhead of serving user requests can be kept at the minimum. In fact,
unless you explicitly write code for your Web server to access Bricolage, no
Bricolage code actually runs when serving pages.

=back

Other advantages of Bricolage include:

=over 4

=item *

Great flexibility for customization. Bricolage is designed from ground up to
give site creators the ability to customize it to meet their needs. This is
done by defining new element types, elements, templates and output channels.

=item *

Great documentation and support. Check out
L<http://www.bricolage.cc/documentation.html>. Information on Mason can be
found at L<http://www.masonbook.com> and L<http://.www.masonhq.org>.

=item *

Open source. Bricolage is distributed under the modified BSD license.

=back

=head3 How does Bricolage compare to other content management systems?

It has received praise for being as good as or better than commercial
alternatives. For example, see
L<http://www.eweek.com/article2/0,3959,652977,00.asp>

=head3 Who uses Bricolage?

Some that we know of are:

=over 4

=item *

The PIRT Group - L<http://thepirtgroup.com/>

=item *

World Health Organization - L<http://www.who.int/>

=item *

Dimensional Fund Advisors - L<http://dfafunds.com/>

=item *

Macworld - L<http://www.macworld.com/>

=item *

MacCentral - L<http://www.maccentral.com/>

=item *

Kineticode - L<http://www.kineticode.com/>

=item *

Ad Council - L<http://www.adcouncil.org/>

=item *

Open Forum Europe - L<http://www.openforumeurope.org/>

=item *

The Lab School of Washington - L<http://my.labschool.org/>

=item *

Brain Mapping Unit, University of Cambridge -
L<http://www-bmu.psychiatry.cam.ac.uk/>

=item *

Architectural Energy - L<http://www.archenergy.com/>

=item *

2: The Magazine for Couples - L<http://www.2magazine.com/>

=item *

Performance Learning Systems - L<http://www.plsweb.com/>

=back

=head3 Are there any commercial support offerings for Bricolage?

Yes. Kineticode, founded by Bricolage maintainer and lead developer David
Wheeler, offers a range of technical support and templating support options,
as well as Bricolage consulting services. Learn more at
L<http://www.kineticode.com/services/>.

=head2 Installation

=head3 Why does mod_perl have to be statically compiled into Apache? I've been using mod_perl as a DSO and have had no problems with it at all.

You are very fortunate, because mod_perl 1.x is just not too stable as a
DSO. Weird things tend to happen. That's not to say that some haven't set it
up as a DSO and just had it work, but we've seen all sorts of unexplainable
problems just evaporate when users have switched from a DSO to a static
mod_perl. And it's not Bricolage so much as Mason where the problems are
noticed. The Mason site (L<http://www.masonhq.com/>) has a
couple of FAQs that mention the issue:

=over 4

=item *

L<http://www.masonhq.com/docs/faq/#why_am_i_getting_segmentation_fa>

=item *

L<http://www.masonhq.com/docs/faq/#does_mason_leak_memory>

=back

You can also search the Mason Users list archives
(L<http://marc.theaimsgroup.com/?l=mason>) and the mod_perl
Users list
archives (L<http://marc.theaimsgroup.com/?l=apache-modperl>) for some
discussions of this issue.

=head2 Errors

This section contains questions about error messages output
by Bricolage.

=head3 If C<make cpan> fails, what can I do?

Bricolage depends heavily on CPAN modules. The purpose of C<make cpan> is to
verify that the required CPAN modules exist and, if not, fetch and install
them from CPAN, whenever possible. In the worst case where it cannot handle
the an error automatically, it gives instruction on how to do it manually.
Usually, the instruction tell you to

  perl -MCPAN -e shell
  look package::module
  perl Makefile.PL
  make
  make test
  make install

where C<package::module> is the name of the file to look for.

Sometimes, it will exit with a error without telling you what to do. Read the
last few lines of the output. See which C<package::module> caused the
error. Then manually install the module using the procedure outlined
above. If, when carrying out the procedures described above, C<make test>
fails, you might still want to go ahead with C<make install>
nonetheless. However, bear in mind that the module might not be installed
properly. After this, rerun C<make cpan>.

For an example, at this writing (2 August 2003), C<Apache::ConfigFile> can
cause a permission problem. C<make cpan> will report a strings of

  cannot set uid=88nnnn, gid=nnnnn

Read a few line before the error message to determine the actual location of
the download file, it is usually something like
F</root/.cpan/sources/authors/id/N/NW/NWIGER/Apache-ConfigFile-0.14.gz>. C<cd>
into the F</root/.cpan/sources/authors/id/N/NW/NWIGER/> directory and untar
the F<tar.gz> file:

  tar -zxvf Apache-ConfigFile-0.14.tar.gz

You will get the same error messages. Note, however, that untar is successful
and the directory F<Apache-ConfigFile-0.14> is created. C<cd> into this
directory and run

  perl Makefile.PL
  make
  make test
  make install

This should succeed. After this, rerun C<make cpan> again. More information
can be founded in L<http://bugzilla.bricolage.cc/show_bug.cgi?id=435>.

Sometimes, C<make cpan> reports that a CPAN module is not found. This could be
because it is trying to get an older version of the CPAN module which CPAN no
longer hosts because your CPAN index file is out-of-date and needs to be
refreshed. To refresh your CPAN index file,

  perl -MCPAN -e 'reload index'

and repeat C<make cpan>.

Sometimes you might need to update your CPAN bundle, itself:

  perl -MCPAN -e 'install Bundle::CPAN'

=head3 Why does C<make install> exit with the error 'Missing or empty inst/bricolage.sql!'?

You checked Bricolage out from Subversion and didn't run C<make dist>. Do
something like this:

    # make dist
    [lots of output...]
    # cd bricolage-1.5.0
    # make install

=head3 Why does C<make install> exit with the error 'Unable to set bricolage.conf variable APACHE_BIN to "/usr/local/apache/bin/httpd"'?

Most likely it's because you're installing Bricolage on Red Hat 8 or later and
haven't got 'round to reading F<README.RedHat>. In fact, a fair number of Perl
modules will fail to install or test properly with Perl 5.8 on Red Hat 8. This
is because Red Hat is configured such that it defaults to a Unicode character
set. Bricolage prefers this, of course, since all Bricolage data is stored in
the database in Unicode. However, it does require that you set the C<LANG>
environment variable on Red Hat 8, like this:

  export LANG=en_US

From what we've heard, C<LANG> must not include "utf8". Presumably you should
set C<LANG> to a value for your local language. At any rate, you'll need to
make sure that this is set in your shell in order to install Bricolage and all
of its modules, and you may need to include it in your F<httpd.conf> file, as
well:

  PerlSetEnv LANG en_US

We've also heard that you can set the LANG environment variable globally in
the F</etc/sysconfig/i18n> file. Then you wouldn't need to worry about it
anywhere else.

=head3 Why does C<make install> exit with the error 'IDENT authentication failed for user "postgres"'?

I'm not sure why the IDENT fails. In F<inst/db_grant.pl>, we switch EUID to
that of 'postgres'. Maybe more things need to be set in order to convince
postgresql that you're logging in as 'postgres' instead of 'root'?

I worked around the problem by ignoring it; in pg_hba.conf,

  #local  all         all                                         ident sameuser
  #host   all         all         127.0.0.1        255.0.0.0      ident sameuser
  local   all         all                                         trust
  host    all         all         127.0.0.1        255.0.0.0      trust
  host    all         all         0.0.0.0          0.0.0.0        reject

A Short introduction to F<pg_hba.conf> can be found in L<Bric::DBA|Bric::DBA>,
and it is more thoroughly documented at
L<http://www.postgresql.org/docs/current/interactive/client-authentication.html>.

=head3 Why do I get a 404 when I connect to the Bricolage UI and get an error like the following in Apache's F<error_log>?

  [error] [client 127.0.0.1] Error executing AccessHandler: Bric::App::Session -- /usr/local/lib/perl5/site_perl/5.8.0/Bric/App/Session.pm -- 236
  Difficulties tie'ing the session hash to file '/tmp/bricolage/session'

Most likely it is because one or more files or directories in your Bricolage
temp directory are no longer writable by the Apache user. You need to C<chown>
the temp file directories and restart Bricolage:

  sudo chown -R nobody:nobody /tmp/bricolage
  sudo bric_apachectl restart

=head3 When I try to login to Bricolage, I get redirected to F</login>, but the page is blank. There's nothing in the HTML source except C<< <html><head></head></html> >> or nothing at all. There are no errors in the error log or the access log. What's wrong?

I've seen this a couple of times, but the cause was different each time. On
one occasion, there was a F<FilesMatch> directive in a separate VirtualHost
directive in F<httpd.conf> that was preventing Mason from seeing any of the
Bricolage UI components. The directive that caused the problem looked like
this:

  <FilesMatch "\.mas">
    SetHandler  perl-script
    PerlHandler Bric::App::Handler
  </FilesMatch>

I have no idea why this would have caused a problem, but when it was removed,
Bricolage started working again.

On another occasion, a user noticed that the files F<comp/login/dhandler> and
F<comp/login/welcome.html> were empty. This caused the equivalent of a
"Document Contains No Data" error, only it didn't. In fact, in my tests, under
these circumstances, the browser had no HTML source at all (although I was
later told that a Mozilla setting can force the C<< <html><head></head></html>
>> to be added). At any rate, the problem was fixed by reinstalling Bricolage
(a C<make upgrade> would probably do the trick, too), but it's likely that
simply copying these two files from the Bricolage source directories to your
installed component root will correct the problem. Holler on the
bricolage-general mail list if it doesn't.

=head3 When I try to login to Bricolage, I get redirected to F</login>, but the web server reported a "500 Internal Server Error". What's wrong?

Look in your Apache F<error_log> file. If you find an error along the lines of

 cannot login ...

Then you need to update your F<pg_hba.conf> file as described in the section
L</"Why does C<make install> exit with the following error?">. In fact, as
David Wheeler suggested in one of the email in the C<bricolage-general>
mailing list, if you issue the following command on the command line:

  /usr/local/pgsql/bin/pgsql -U bric bric

you will get

  IDENT authentication failed for user "bric"

Thus demonstrating that you're dealing with a PostgreSQL configuration issue,
rather than a Bricolage issue.

=head3 I'm trying to restore a backup of the Bricolage database, but I keep getting an error like this: "ERROR: Function login_avail(varchar, numeric, numeric) does not exist". What gives?

This is a known issue with PostgreSQL's C<pg_dump> utility -- it's not smart
enough to handle circular dependencies. The PostgreSQL developers are aware of
the issue. See this bug report for details:
L<http://archives.postgresql.org/pgsql-bugs/2002-09/msg00278.php>.

In the meantime, the workaround is to edit your SQL dump file so that the
Bricolage database will load properly. In your SQL dump file, search for and
remove the line containing the string 'CONSTRAINT "ck_usr__login"'. This
should remove the creation of the constraint that uses the C<login_avail()>
function before the function is created. Next, go to the very end of the
SQL dump file and add these lines:

  ALTER TABLE usr ADD CONSTRAINT ck_usr__login
  CHECK (login_avail(LOWER(login), active, id));

This will add the constraint at the very end of the load, when both the "usr"
table and the C<login_avail()> function have been created. Now you should be
able to load the database and get back to work!

=head3 Why do I get the error 'Can't locate object method "" via package "HTML::Mason::Lexer"'?

This is a bug with Perl. It is caused by the presence of Unicode in a Mason
template, and dates from a period when Perl's regular expressions had some
difficulty with Unicode. It was fixed in Perl 5.8.1. Upgrade to the latest
version of Perl and you should be good to go.

=head3 I keep clicking the "Click here to start" link on the very first Bricolage page I see, but it keeps just opening up a new window with "Click here to start" again. What gives?

I'm going to go out on a limb here and guess that you're using Safari 1.1.1 or
earlier on Mac OS X. Prior to the release of version 1.2, Safari has a
JavaScript bug wherein it doesn't know the name of a window. The "Click here
to start" link opens a new named window, but since Safari doesn't know that
it's named, Bricolage's JavaScript can't tell that it's named, either, and so
keeps trying to get you to open a window with the correct name. It'll never
happen. Apple should be aware of this issue, as I've filed a bug report for it
using Safari's bug reporting interface, and have reported it again via Apple's
official bug database (Bug # 3485193).

Until Apple fixes the bug, there are two ways to resolve this issue: First,
don't use Safari. This is the preferred solution, and since there are some
other great Browsers for Mac OS X (notably Camino, Firebird, and Mozilla),
it's a real option for most Bricolage users. The second solution is to disable
the named window by adding the undocumented configuration directive
C<NO_TOOLBAR> to your F<bricolage.conf> file with a false value. The downside
of this approach, however, is that all users of Bricolage will now be using
Bricolage in a window with the back button, and this can potentially lead to
problems with the state of story objects while you're editing them. However,
if you never use the back button, it should be fine.

=head3 Sometimes the left navigation doesn't render properly, and the interface for adding fields doesn't work at all. What gives?

Most likely you're using Safari on Mac OS X to access the Bricolage
interface. Unfortunately, that browser seems to have some bugs related to
rendering layers. The only workaround is to use a different browser. I
recommend Camino, Firebird, or Mozilla.

=head3 Bricolage seems to be automatically changing my accented and other non-ASCII characters: when I enter element content with accented characters 'à's become 'Ã¨'s and similar things occur to other accented characters. What's going on?

You need Perl 5.8.0 or later for Bricolage to properly handle
non-ASCII characters. Also, PostgreSQL database for Bricolage must be
using UNICODE encoding. Please see L<Bric::Admin|Bric::Admin> for further
information on recommended setup for letting Bricolage correctly handle
non-ASCII content.

=head3 Accented and other non-ASCII characters look right in Bricolage's internal preview, but not on my own preview server or my production server. What gives?

You need to make sure that your non-Bricolage server or virtual host knows
that it's server Unicode characters. If you're running an Apache server, just
add this to your F<httpd.conf> and restart:

  AddDefaultCharset utf-8

Consult the documentation for your Web server for more information.

=head3 The Bricolage SOAP server segfaults when I try to use it. What gives?

Apache inadvertantly compiled the wrong expat XML parser into itself. Rebuild
Apache, this time using the C<--disable-rule=EXPAT> option.

=head2 Element Administration

=head3 I added a field to an element and deleted it, and now I can't add a new field with the same name. Why not?

Fields cannot have the same name, even if they've been deleted. This is
because you might have older stories around that use the old name, and still
republish them to templates that use the old name.

The solution is to give the new version of the field a different name, but
make the "Label" the same. So you might have a name like "new_paragraph" and
the label "Paragraph". Just remember to change any references to the old field
name in your templates to use the new field name.

=head3 I created a new subelement type element but it does not appear in the list of elements for which I can choose to create a template. Where is it?

Did you add it as a subelement to a document type element, or as a subelement
to any element that's part of a document type element hierarchy? If not, it
won't show up in the template select list. This behavior has to do with sites;
only story type and media type elements are associated with sites, so to
create a new template in a workflow (which is associated with a site), it
looks for all the story type and media type elements associated with that
site, and then adds all subelements of those elements. So unless your new
subelement is associated with a story type or media type element, you won't
see it when you go to create a new template.

=head2 Miscellaneous

This section contains questions that didn't fit in the other
sections.

=head3 What does "Bricolage" mean?

Click on the Bricolage log in in the UI to see the "About" section of the
online help.

=head3 How did Bricolage get started? What is its history?

[In the beginning there was chaos....]

=head3 Where can I get more information?

Read the F<README> document in the directory where you unpacked Bricolage to
learn about other documents on specific things like Bricolage administration,
usage, or hacking. The project's web site is
L<http://www.bricolage.cc/>. The
web site lists information about mailing lists.

=head3 I can't get my head around the idea of workflow. Is there any documentation on it?

Not really, no. We'll likely write some one of these days. in the meantime,
you might find some use in a presentation given at the 2000 OSCON by Ian
Kallen, in which he discussed what Salon needed out of a CMS (including
workflow) and how he came to select the tools to use the CMS that was the
proof-of-concept for Bricolage. The article is at
L<http://www.arachna.com/edu/talks/iswp/index.html>.

=head3 Why do searches return only objects with fields that start with my query string, rather than containing the query string anywhere in the field?

This behavior is intentional. The search interface goes directly into an SQL
query, and thus support SQL wild card characters. Unless you query for a
string at the beginning of a column, the index on that column won't be
used. So we default to only searching at the beginning of a field in order to
take advantage of the speed provided by an index.

However, you can get around this functionality in two ways. You can by put a
'%' in front of your search string, thereby forcing the SQL query to be a
full substring query. Or you can enable on the "FULL_SEARCH" F<bricolage.conf>
directive and restart Bricolage. But know that either of these methods I<will>
a lot slower (though you probably won't notice much until you have 1000s of
documents).

=head3 Why can't I see all the stories I should see in Find Stories/Find Media/Find Templates ?

What is your 'Filter search results by site context' preference set to? When this preference is set to 'On',
Bricolage filters search results according to the Site context selected.

=head3 Does Bricolage have a memory leak?

No. Bricolage can use a lot of memory resources, especially if you publish a
lot of documents at once, such as via the SOAP interface. Perl grabs the
memory it needs, but it never releases it back to the operating system,
although it will reuse it before asking the OS for more. So if you've
published a lot of stories at once or done anything else to cause Bricolage to
load a lot of data (such as used the search interface to get a list of all
10,000 stories in your Bricolage database), then the process that handled your
request will become quite large and stay that way for its lifetime.

There are a number of ways to address this issue:

=over 4

=item *

If you're using C<bric_soap> to execute big SOAP requests, use its C<--chunks>
option whenever possible to cut down on the amount of work any one request is
doing.

=item *

Change your Apache configuration to get a better handle on your process
sizes. Set C<MaxSpareServers> and C<MinSpareServers> to a reasonable numbers,
and set C<MaxRequestsPerChild> to limit the number of requests any one child
handles. See the Apache documentation at L<http://httpd.apache.org/docs/> for
more information on these and related directives.

=item *

Use Bricolage's support for Apache::SizeLimit. This support is enabled via the
C<CHECK_PROCESS_SIZE> F<bricolage.conf> directives, and you can tune it using
the C<MAX_PROCESS_SIZE>, C<CHECK_FREQUENCY>, C<MIN_SHARE_SIZE>, and
C<MAX_UNSHARED_SIZE> directives, as well. See
L<Apache::Admin|Apache::Admin/"Apache Configuration"> for details.

=item *

If you are using any character sets besides UTF-8, specify these
character sets with the C<LOAD_CHAR_SETS> directives.  This will make
sure that the character sets you are using are pre-loaded during
server startup.  This is especially important for large character sets
like Big5 or Shift-JIS.

=item *

If you are using any languages besides "en_us", specify these
languages with the C<LOAD_LANGUAGES> directives.  This will make sure
that the languages you are using are pre-loaded during server startup.

=back

=head2 Template Administration

=head3 I added a template to a category and then deleted it, and now I can't add a new
template with the same name. Why not?

Deleted template profiles don't actually get deleted but instead marked
inactive in the database. This prevents creating a new template with the same
name in them same category in the same output channel. In a future release, an
easy way to reactivate deleted template profiles will be integrated in the
GUI.

In the meantime, deleted (that is, deactivated) template can be brought back
by using a updating the database directly and querying against the output
channel ID and the template's file name:

  psql -U [username] -d [databasename] -c \
    "UPDATE formatting SET active = 1 WHERE output_channel__id = [ocid] \
     AND file_name = '[path]'"

The arguments in brackets above are:

=head3 I get an compile error when I try to use C<$story> or C<$element> in a
Mason template C<< <%once> >> block. What gives?

To check the syntax of a Mason template as you develop it, Bricolage creates a
Mason interpreter and compiles the template. Because C<< <%once> >> blocks are
designed to execute only once, Mason actually executes them during the
compile. Of course, there is no C<$story> or C<$element> object when you're
editing a template, only when you're publishing or previewing a story.

But since these objects are available in a C<< <%once> >> block during a
publish or preview, and as of Bricolage 1.6.14 and 1.8.0 the C<$burner> object
is always available, you can use the C<$story> or C<$element> object in a C<<
<%once> >> block like this:

  <%once>;
  unless ($burner->get_mode == SYNTAX_MODE) {
      # Do stuff with $story or $element.
  }
  </%once>

=over 4

=item username

The username for your Bricolage PostgreSQL user. This is the username the
Bricolage installer created for you, and which is listed as the C<DBI_USER>
F<bricolage.conf> directive.

=item databasename

The name of the Bricolage database. This is the database the Bricolage
installer created for you, and which is listed as the C<DB_NAME>
F<bricolage.conf> directive.

=item ocid

The ID of the output channel that the template is in.

=item path

The full URI path name of the template. This is a combination of the category
path and the name of the template, usually constructed from the element for
which it is created. For example, a Mason template created for the "Book
Review" element in the category "/reviews/books" would be called
F</reviews/books/book_review.mc>.

=back

=head1 AUTHOR

Scott Lanning <slanning@theworld.com>

David Wheeler <david@kineticode.com>

=head1 SEE ALSO

F<README>,
L<http://bricolage.cc/>,
L<Bric::Admin|Bric::Admin>

=cut
