/ 
minivend-4.00
/ makecat

NAME

makecat - Build a MiniVend catalog from a template

SYNOPSIS

makecat [--options] name

VERSION

$Id: makecat,v 1.3 2000/02/06 01:53:09 mike Exp mike $

INTRODUCTION

The makecat program builds a MiniVend catalog from a template based on your server configuration. It interrogates for parameters like the directories to use, URL to base the catalog in, HTTP server definitions, and file ownership. It is self-documenting in that it asks verbose questions and gives relevant examples.

On UNIX, if you want to check on something during the process you can usually hit <CTRL-Z> to suspend the program and do something and then type fg to return to <makecat>. Also, if your input begins with an exclamation mark (!), it will be interpreted as a shell command. An exclamation mark (!) alone should drop you into a shell.

If you have the Term::ReadLine::Perl and Term::ReadKey modules installed, the <UP> and <DOWN> arrows will cycle between suggested defaults; and the following features will be in place:

TAB       Completes file name
<UP>      Cycle suggestion up
<DOWN>    Cycle suggestion down
<CTRL-P>  Cycle suggestion up
<CTRL-N>  Cycle suggestion down
<CTRL-B>  Go back one question (if possible)
<CTRL-U>  Erase line
<LEFT>    Command-line editing left
<RIGHT>   Command-line editing left

Also, if you make a mistake at some stage of the interrogation, you can often hit the <CTRL-B> key to return to the previous query. If you don't have Term::ReadLine installed, then you can enter an at sign (@) by itself on the line.

OPTIONS

usage: makecat [options] [catalogname]

The makecat program can build a catalog based completely on a command line description. An example is in eg/makecat.sh.

There are just a few flag-based options:

-F

Force make of catalog with defaults supplied on command line.

-f

Configuration file -- default is makecat.cfg in Minivend Confdir (etc) directory.

-l

File to log to (default makecat.log)

-r

Reconfigure defaults normally set in makecat.cfg; this is done automatically the first time the program is run.

The remainder of the options are supplied on the command line as named parameters followed by an = sign, followed by the value, i.e.

--parameter=value

Normally, if makecat supplies a default you might guess at that. It is fairly intelligent if you have an Apache server and it has found the httpd.conf file. If you are on a Netscape or other web server, it is less likely to be right.

The options set at reconfig time, i.e. the first time the program is run:

--basedir=directory

Base directory for catalogs. This defaults to catalogs in the home directory of the catalog user.

--cgibase=url_fragment

Base URL for link programs. This is normally either blank (your programs are made with .cgi extension) or /cgi-bin (you have a CGI directory).

--documentroot=directory

The directory where HTML is based. This is the root directory of the web server, i.e. DocumentRoot.

--minivendgroup=group

The default group files should be owned by.

--minivenduser=username

The user ID which runs MiniVend.

--serverconf=filename

Location of httpd.conf; you will be queried otherwise.

--vendroot=filename

Location of MiniVend software.

--homedir=directory

Use instead of \$HOME to set defaults

These are options which are required to be set for any catalog; the default will often be correct if you have set the above options correctly.

--catroot=directory

Directory where MiniVend catalog files go. This is the base directory for this catalog.

--cgidir=directory

The directory the CGI link should go to. This is the CGI directory; if your CGI programs all end in .cgi then this would normally be the same as documentroot; if you have a cgi bin directory it should be used.

--servername=server

Name of server (www.whatever.domain). You can supply a port:

www.foo.com:8080

or a username:

www.foo.com/~bar

For testing on your local machine, just use localhost.

--cgiurl=url_fragment

The path to the CGI link (no server name). For a catalog named simple, this would normally be one of:

--cgiurl=/cgi-bin/simple

or

--cgiurl=/simple.cgi
--demotype=template

The template catalog. The default is <simple>.

--mailorderto=email

Email address to send orders

--catuser=username

The user files should be owned by (option only operative if root).

The rest of the parameters need not be supplied on the command line as intelligent defaults can be derived from the above parameters.

--samplehtml=directory

The directory where template HTML goes.

--imagedir=directory

The directory where template images go.

--imageurl=url

The URL to prefix images with.

--nocfg

Don't add to minivend.cfg.

--nocopy

Don't actually copy the files, just test.

--norunning

Don't add to running server.

--reference

Return hash of config as string (sets -F, no write). This is for passing back to the makecat program in a autobuild environment.

--linkprogram=file

Use file as link program instead of vlink/tlink.

--linkmode=mode

UNIX or INET (link program vlink or tlink).

--sampleurl=url

URL to access HTML for catalog.

--noumask

Don't set umask to the value implied by mode.

DESCRIPTION

makecat needs a template catalog to operate on. The simple and basic demo templates are distributed with MiniVend. You can also look for older demo catalogs (mostly for ideas) at ftp.minivend.com.

IMPORTANT NOTE: You only make a catalog once. All further configuration is done by editing the files within the catalog directory.

A catalog template contains an image of a configured catalog. The best way to see what the makecat program does is to configure the simple demo and then run a recursive diff on the template and configured catalog directories:

diff -r mvend/simple catalogs/simple

NOTE: diff is usually only available on UNIX.

You will see that the files are mostly the same, except that certain macro strings have been replaced with the answers you gave to the script. For example, if you answered www.mydomain.com at the prompt for server name, then you would see this difference in the catalog.cfg file:

# template
Variable SERVER_NAME  __MVC_SERVERNAME__

# configured catalog
Variable SERVER_NAME  www.mydomain.com

The macro string __MVC_SERVERNAME__ was substituted with the answer to the question about server name. In the same way, other variables are substituted, and include (at least):

MVC_BASEDIR      MVC_IMAGEDIR
MVC_CATROOT      MVC_IMAGEURL
MVC_CATUSER      MVC_MAILORDERTO
MVC_CGIBASE      MVC_MINIVENDGROUP
MVC_CGIDIR       MVC_MINIVENDUSER
MVC_CGIURL       MVC_SAMPLEHTML
MVC_DEMOTYPE     MVC_SAMPLEURL
MVC_DOCUMENTROOT MVC_VENDROOT
MVC_ENCRYPTOR

(Not all of these are present in the simple or sample templates, and quite a few more may be defined.) In fact, any environment variable that is set and begins with MVC_ will be substituted for by the makecat script. So if you wanted to set up a configurable parameter to customize the COMPANY variable in catalog.cfg, you could run a pre-qualifying script that set the environment variable MVC_COMPANY and then place in the catalog.cfg file:

Variable   COMPANY   __MVC_COMPANY__

All files within a template directory are substituted for macros, not just the catalog.cfg file. There are two special directories named html and images. These will be recursively copied to the directories defined as SampleHTML and ImageDir.

IMPORTANT NOTE: The template directory is located in the MiniVend software directory, i.e. where minivend.cfg resides. You normally do not edit files in the template directory. If you want to try creating your own template, it is recommended that you name it something besides simple and copy the simple demo directory to it as a starting point. Templates are normally placed in the MiniVend base directory, but can be located anywhere -- the script will prompt you for location if it cannot find a template.

In addition to the standard parameters prompted for by MiniVend, and the standard catalog creation procedure, you may define four other files in the config directory of the template:

additional_fields  -- file with more parameters for macro substitution
additional_help    -- extended description for the additional_fields
precopy_commands   -- commands passed to the system prior to catalog copy
postcopy_commands  -- commands passed to the system after catalog copy

All files are paragraph-based; in other words, a blank line (with no spaces) terminates the individual setting.

The additional_fields file contains:

PARAM
The prompt. Set PARAM to?
The default value of PARAM

This would cause a question during makecat:

The prompt. Set PARAM to?.....[The default value of PARAM]

If the additional_help file is present, you can give additional instructions for PARAM.

PARAM
These are additional instructions for PARAM, and they
may span multiple lines up to the first blank line.

The prompt would now be:

These are additional instructions for PARAM, and they
may span multiple lines up to the first blank line.

The prompt. Set PARAM to?.....[The default value of PARAM]

If the file config/precopy_commands exists, it will be read as a command followed by the prompt/help value.

mysqladmin create __MVC_CATALOGNAME__
We need to create an SQL database for your Minivend
database tables.

This will cause the prompt:

We need to create an SQL database for your Minivend
database tables.
 
Run command "mysqladmin create simple"?

If the response is "y" or "yes", then the command will be run by passing it through the Perl system() function. As with any of the additional configuration files, MVC_PARAM macro substitution is done on the command and help. Obviously you must have proper permissions for the command.

The file config/postcopy_commands is exactly the same as precopy_commands except you are prompted after the catalog files are copied and macro substitution is performed on all files.

ABOUT MINIVEND IN GENERAL

MiniVend has many, many, functions and features; they are too numerous to describe in this venue. Complete information can be found at its web site:

http://www.minivend.com

MiniVend requires Perl 5.005 or higher; more information on Perl can be seen at:

http://www.perl.com

LICENSE

MiniVend comes with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome to redistribute and modify it under the terms of the GNU General Public License.

COPYRIGHT

Copyright 1995-2000, Mike Heins. All rights reserved except as in the license.

AUTHOR

Mike Heins, <mikeh@minivend.com>. Please do not contact the author for direct help with the system. Use the Minivend mail lists:

minivend-users@minivend.com (English, subscribe at majordomo@Minivend.com)
minivend-de@minivend.com    (Deutsch, subscribe at majordomo@Minivend.com)

General information and documentation for Minivend is at:

http://www.minivend.com