ArchZoom Frequently Asked Questions with Answers.

------------------------------------------------------------------------------

1. About ArchZoom

  1.1  What is ArchZoom?
  1.2  What is GNU Arch and its terminology?
  1.3  Why do I need ArchZoom?
  1.4  How does it work?
  1.5  Can I run archzoom.cgi from command line?
  1.6  Why all these "?" and not "&" in urls?

2. Installation

  2.1  What should be installed and where?
  2.2  Can I make the archzoom.cgi base url shorter?

3. Configuration

  3.1  Why is the tarball option not enabled by default?
  3.2  Why do I happen to see fancy chars or question marks in summaries?
  3.3  I don't like the look of pages, what to do?

4. Troubleshooting

  4.1  Why does my browser timeout when I browse the revision listing?

==============================================================================


------------------------------------------------------------------------------

1.1  What is ArchZoom?

This is a web based application that creates a convenient interface for
browsing GNU Arch archives.  Please visit the home page for screenshots
and additional information at http://migo.sixbit.org/software/archzoom/.

==============================================================================


------------------------------------------------------------------------------

1.2  What is GNU Arch and its terminology?

GNU Arch is an advanced revision control system.  It works with hierarchical
structure of archives, categories, branches, versions and revisions.  Atomic
changesets form new revisions.  Changeset is a set of file diffs, additions,
deletions, renames and permission changes.  There is one tree (snapshot)
associated with every revision.  There is one changeset log associated with
every revision.  One revision may include several external changeset logs in
case of merges.

Please visit http://wiki.gnuarch.org/ for more information.

==============================================================================


------------------------------------------------------------------------------

1.3  Why do I need ArchZoom?

Basically, you may want to have a convenient way to 1) privately browse your
own GNU Arch archives, 2) browse public archives of others, 3) let users of
your projects to track the development of these projects.

You may also use ArchZoom to allow your users to download the development
snapshots or individual changesets.

==============================================================================


------------------------------------------------------------------------------

1.4  How does it work?

ArchZoom runs tla to gather all needed information about archives and their
contents.  Some of the data may be cached.  If the debug mode is enabled,
add "?debug" to any archzoom url to view the things archzoom does in order
to generate any given page.

==============================================================================


------------------------------------------------------------------------------

1.5  Can I run archzoom.cgi from command line?

Yes, archzoom.cgi should work perfectly from the command line and generate
html page.  It accepts two optional command line arguments, the first is the
arch name, like "migo@homamail.com--Perl-GPL/archzoom--devel--0--patch-150",
and the second is url parameters, like "log&expand&debug&charset=utf-16".

==============================================================================


------------------------------------------------------------------------------

1.6  Why all these "?" and not "&" in urls?

For consistency.  So, you may add "?expand", "?nocache", "?css=bright.css"
to any url without worrying the url already contains one "?".  Note that it
is still standard compliant and you may freely use "&" if you like, i.e.
these two are the same: "?debug?charset=koi8-r" and "?debug&charset=koi8-r".

==============================================================================


------------------------------------------------------------------------------

2.1  What should be installed and where?

There are several solutions, the easiest is to follow the instructions in
README and run "make install".  This installs 2 things, archzoom.cgi script
and archzoom-data directory with several subdirectories. You may even move
archzoom.cgi and archzoom-data later by one level up or down, and the data
location will usually still be detected.

Suppose you have /www/html as your Apache document root. Then you may have
these possible layouts (the first is what "make install" does):

  /www/html/archzoom.cgi
  /www/html/archzoom-data/

  /www/html/cgis/archzoom.cgi
  /www/html/archzoom-data/

  /www/html/archzoom.cgi
  /www/archzoom-data/

  /www/html/cgi-bin/archzoom.cgi
  /www/archzoom-data/

With some Apache configurations you may need to do "chmod g-w archzoom.cgi".

==============================================================================


------------------------------------------------------------------------------

2.2  Can I make the archzoom.cgi base url shorter?

Sure, you may configure your Apache, so that the following urls produce the
list of the managed archives:

  http://localhost/archzoom/archzoom.cgi  # AddHandler cgi-script .cgi
  http://localhost:81/archzoom.cgi        #             --.--
  http://my-domain-org/archzoom/          # Alias /archzoom /www/archzoom.cgi
  http://my-domain-org:8080/              # Alias / /www/archzoom.cgi/
  http://my-domain-org/cgi-bin/archzoom   # cp|ln archzoom.cgi archzoom
  http://archzoom.sourceforge.net/demo    # cp|ln archzoom.cgi demo

Contact your httpd.conf documentation if needed.

==============================================================================


------------------------------------------------------------------------------

3.1  Why is the tarball option not enabled by default?

Creating and downloading tarballs on the fly from any revision changeset
and tree is one of the most requested features.  The only reason it is not
enabled by default is because this is not a read-only operation, it invokes
external tar (and cp if needed) and creates temporary directory in /tmp.
I want to be conservative and let people know what they enable.  Other
than this, it is safe to set tarball_downloading = 1 in archzoom.conf.

==============================================================================


------------------------------------------------------------------------------

3.2  I don't like the look of pages, what to do?

There are several alternative css, and alternative template sets, see
archzoom.conf.  Add "?css=bright.css" or "?template=minimal" to any url to
see how these look.

Consider to create your own css or even the whole template set.  If good,
it may be included in the future archzoom versions.

==============================================================================


------------------------------------------------------------------------------

3.3  Why do I happen to see fancy chars or question marks in summaries?

Try to see whether adding something like "?charset=iso-8859-1" to the url
solves your problem.

==============================================================================


------------------------------------------------------------------------------

4.1  Why does my browser timeout when I browse the revision listing?

Unfortunately, commands 'tla abrowse' and 'tla revisions' with options like
--summary take a lot of time in case of remote archives.  Consider to mirror
archives, local archives should work much quicker.

If these tla operations exceed the browser timeout (that is usually one or
more minutes), but you (as the owner of the system archzoom.cgi runs on)
absolutely need to temporarily browse the revisions, use the following
trick.  Run: "./archzoom.cgi your--archive/category--branch--version" from
the command line.  After several minutes of running, the result will be
cached (see archzoom.conf), then you may revisit the url in the browser.

==============================================================================
