'\" t
.\" aegis - project change supervisor
.\" Copyright (C) 2003, 2004, 2006-2008, 2010, 2012 Peter Miller
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
.\" General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
.\"
.so etc/libdir.so
.so lib/en/man1/z_name.so
.ds n) aeget
.TH "aeget" 1 \*(N) "Reference Manual" ""
.SH NAME
aeget \- Aegis CGI file access
.XX "aeget(1)" "Aegis CGI file access"
.SH SYNOPSIS
.B \*(n)
.SH DESCRIPTION
The
.I "\*(n)"
command is used with Apache (or CGI conforming any other web server)
to access the files of an Aegis project.
The files are searched for along the appropriate search path,
including all ancestor baslines,
not just the baseline of the branch.
.PP
This is useful when developing web sites using Aegis.
.SS Install
In order to use \fIaeget\fP(1), you need to copy it into your
\fIcgi\[hy]bin\fP directory.
.PP
You may prefer to use a symbolic link, as this will be more stable
across Aegis upgrades.  However, this requires a corresponding
\fIfollow\[hy]symlinks\fP setting in your web server's configuration file.
.SS Usage
Once \fIaeget\fP(1) is installed,
files may be accessed via
.RS
http://localhost/cgi\[hy]bin/aeget/\fIproject\[hy]name\fP/
.RE
If no project name is given, a list of projects will be generated.
This will lead you through a series of menus, giving access to manu
useful pages of information about your projects.
.SS Cascading Style Sheets
The web interface uses Cascading Style Sheets.  You can give the
web interface a personalised look and feel, by creating stylesheets
in the web server's Document Root directory.
The interface will use it's default styles, then styles from a global
style sheet called \f[CW]aedefault.css\fP, and then styles from a project
stylesheet called \fIprojectname\fP\f[CW].css\fP (replace \fIprojectname\fP
with the name of the project).
.PP
There is an example style sheet in
\f[CW]\*(D)/aedefault.css\fP which demonstrates the style elements used.
This particular stylesheet is not designed to be aesthetically pleasing,
but to exercise all of the elements.
Using this stylesheet unmodified will give psychedelic results.
Use it as a template.
.SH PROJECT ATTRIBUTES
You can set your own project specific page headers and footers by using
the "html:meta", "html:body\[hy]begin" and "html:body\[hy]end" project specific
attributes.
.RS
.nf
.ft CW
project_specific =
[
  {
    name = "html:body\[hy]begin";
.fi
.in +4m
value = "<i>This text goes immediately after the &lt;BODY&gt; and before
any text generated by <i>aeget</i>(1).</i>";
.in -4m
.nf
  },
  {
    name = "html:body\[hy]end";
.fi
.in +4m
value = "<i>This text goes immediately before the &lt;/BODY&gt; and after
all text generated by <i>aeget</i>(1).</i>";
.in -4m
.nf
  },
];
.ft P
.fi
.RE
These fields may be used to customize your web pages for your
project\[hy]specific or company\[hy]specific needs.
Each project is configured independently.
.SH CHANGE ATTRIBUTES
If you wish to prevent a change set appearing in the change set
inventory used by \fIaedist \-replay\fP to determine what needs to be
downloaded, set the following change set attribute:
.RS
.nf
.ft CW
attribute =
[
  {
    name = "aeget:inventory:hide";
    value = "true";
  },
];
.ft P
.fi
.RE
You must use the \fIaeca\fP(1) command for this, the \fItkaeca\fP(1)
command can not edit change set attributes.
.SH DEBUGGING and TESTING
You can run the \fI\*(n)\fP(1) program from the command line if you set
the appropriate environment variables.
This is how you debug or test \fI\*(n)\fP(1) command.
.TP 8n
REQUEST_METHOD
This is how the script is being invoked.
For \fI\*(n)\fP(1) command, this is always "\f[CW]GET\fP".
.TP 8n
SCRIPT_NAME
This is the path of the script name, from the HTTP client's point of view.
Typically this is "\f[CW]/cgi\[hy]bin/aeget\fP".
.TP 8n
PATH_INFO
This is the portion of the URL between the script name and the question
mark.  For \fI\*(n)\fP(1) this is usually the project name or the
project name and the change number.
No project name will get you the project list page.
.TP 8n
QUERY_STRING
This the portion of the URL after the question mark.
.PP
The above will not means much if you are not familiar with CGI scripts.
For the URL \f[CW]http://localhost/cgi\[hy]bin/aeget/aegis.4.1.C10?menu\fP
would have Apache set the following environment variables
.RS
.nf
.ft CW
REQUEST_METHOD=GET \e
SCRIPT_NAME=/cgi\[hy]bin/aeget \e
PATH_INFO=/aegis.4.1.C10 \e
QUERY_STRING='menu' \e
aeget
.ft P
.fi
.RE
Output is written to stdout.  Tests scripts can easily capture this and
compare it with expected results.  Make sure you avoid false negatives
because of the date tacked onto the end of most pages.
.SS Apache
If you see "serious server error" pages when accessing \fI\*(n)\fP(1) via
a web server, the stderr text is usually available in the server's error log.
.so lib/en/man1/z_cr.so
.\" vim: set ts=8 sw=4 et :