pkg://genscheme-1.1.tar.gz:32227/genscheme-1.1/genscheme.1  downloads

.TH genscheme 1 "December 27, 1996" "genscheme 1.1" "genscheme 1.1"
.UC
.ll +10
.SH NAME
genscheme \- generate appearance schemes from a template

.SH SYNOPSIS
.B genscheme
[
.B \-o dir
]
[
.B \-T dir
]
[
.B \-appendfn filename
]
[
.B \-m4opts args
]
[
.B \-suffix suffix
]
[
.B \-regex regex
]
.B template

.SH DESCRIPTION
\fBgenscheme\fP translates the output of \fIgetscheme\fP using Perl,
the m4 preprocessor, and template files (\fBgenscheme\fP is a Perl
program while \fIgetscheme\fP is a Win32 program).  Note that this
program has nothing to do with the Scheme language.  Perl 5 is
required for operation. See the Examples section below for usage
examples.

.SS OPTIONS
.IP "\-o \fBdir\fP"
Specifies the output directory name.  This is also defined as
OutputDir during m4 preprocessing.

.IP "\-T \fBdir\fP"
Specifies an alternate template file directory.  Running
\fBgenscheme\fP without arguments displays the default template
directory (defined at install-time).

.IP "\-appendfn \fBfilename\fP"
Specifies the append filename, if the template uses one.  The default
is \fIappend.out\fP.

.IP "\-m4opts \fBargs\fP"
Specifies additional arguments to pass to m4 when preprocessing.
Additional defines should be placed here.

.IP "\-suffix \fBsuffix\fP"
Specifies a suffix to append to all output files, including the append
file (the output directory remains unaffected).

.IP "\-regex \fBregex\fP"
Specifies a Perl regular expression. Schemes will only be processed if
they match \fIregex\fP (e.g., -regex "/VGA/i" will do a
case-insensitive substring match). See Perl 5 documentation for
detailed information.

.SS TEMPLATES
A template is a directory which contains up to four plain text files,
all of which are preprocessed through m4 (and are thus subject to m4
rules).  The files "init_append," "append" and "end_append" are used
to create the \fIappend.out\fP file (set with -appendfn) in the output
directory, in that order.  Then, the "foreach" file is used to
generate each scheme file in the output directory, where each filename
is that of the scheme itself.  If any of the files are not present,
the step is simply skipped.  Output files are always opened in append
mode so that specific templates can act as "modifiers" (i.e., see the
X resource modifying template example below).

The "init_append" file is piped through m4 once and appended to
\fIappendfn\fP.  Then, for each available scheme, the "append" file is
piped through m4 with the scheme's colors defined and appended to
\fIappendfn\fP.  Finally, "end_append" is piped through m4 like
"init_append."

The "foreach" file is piped through m4 for each available scheme, with
all of the scheme's colors available as defines.  The output of the
pipe is then appended to a file in the output directory which has the
same name as the scheme (plus any suffix added with -suffix).

All four files can access the name of the output directory in the
OutputDir define (changed with -o).  Options specific to each template
can be passed with the -m4opts command-line argument (for example, the
"MenuName" define for the fvwm2 templates can be set this way).

.SH EXAMPLES
First you need to obtain the raw data for input.  You can do this with
the \fIgetscheme\fP program (on a Win32 machine):

.in +2
\fIgetscheme\fP -all -rgb1 > schemes.txt
.in -2

Then transfer the file schemes.txt to your Unix machine (you do not
need to strip the carriage returns).  Now, for example, we would like
to convert the schemes.txt on our Unix machine to an fvwm2rc-readable
format.  Using the fvwm2 template file we could issue the following
command:

.in +2
\fBgenscheme\fP < schemes.txt fvwm2
.in -2

Unfortunately this command leaves much up to genscheme, leaving you
with an output dir named genscheme.out and a menu file named
append.out.  Let's try again and specify those:

.in +2
\fBgenscheme\fP < schemes.txt -o MySchemes -appendfn Schemes.fi fvwm2
.in -2

Okay, this is slightly better.  We now have a directory named
"MySchemes" which also contains a file named Schemes.fi.  The
Schemes.fi file in turn can be read into fvwm2 with the "Read" command
to construct a menu:

.in +2
Read "MySchemes/Slate"

Read "MySchemes/Schemes.fi"

AddToMenu "SomeMenu"

+ "Schemes" Popup Schemes
.in -2

This would give you a menu with a menu entry for each translated
scheme.

What if you want to have multiple menus?  We can pass on a define to
the m4 preprocessor to alter the menu name.  Note that this is a
specific feature of the fvwm2 templates (only the new option is shown,
just add it to the previous command line):

.in +2
-m4opts "-DMenuName=\\"Other Schemes\\""
.in -2

Now, instead of the default menu name of Schemes, a menu named "Other
Schemes" is created instead.  In a similar fashion for fvwm2 template,
you can specify the font used for menus:

.in +2
-m4opts "-DFont=9x15"
.in -2

To specify both (or more):

.in +2
-m4opts "-DFont=9x15 -DMenuName=\\"Other Schemes\\""
.in -2

Say that you wanted to modify or create a new set of templates.  An
easy way to do that is to copy a sample template directory into a new
directory then use the -T option to specify the alternate template
directory.

.SS X RESOURCES
Changing only the aspects of the window-manager do not affect all
aspects of the "look" in X/Windows.  The first item you might want to
change is the background color of the screen.  Instead of putting the
line into the fvwm2 template file, you could use the command modifier
template.  After creating the above setup, add the \fIcmd\fP modifier:

.in +2
\fBgenscheme\fP < schemes.txt 
.in +1
 -m4opts
 "-Dcmd=\\"Exec xsetroot -solid \\\\\\"Background\\\\\\"\\"" cmd
.in -1
.in -2

This will add an xsetroot command to all of the schemes to setup the
background color (note the multiple backslashes to make sure the
quotes do not get removed).  Another use of the command modifier
template is to change X resources.  Changing X resources do not affect
running applications but only ones which start after the resource
merge.  There are two included example templates which can be used to
do this for the fvwm2 setup example.

The first template just creates files which can be loaded with the
xrdb command.  However, since we want these files to be separate from
the fvwm2 scheme files (but grouped with other resource modifiers), we
need to use the -suffix option to give the filename an extension.  A
sample template named Motif_res is included which sets up some
rudimentary Motif-related resources (you can create other modifier
templates and run genscheme again to add it to the same set of .xrdb
files).  Copy the Motif_res to another file to create a resource
definition for a different widget set.

The second is the command template used above which simply adds the
resource file merge command to the fvwm2 scheme files.  The background
setting command is also included in the following example, yielding a
fairly complete color scheme change.  Make sure you get the
backslashes correct:

.in +2
\fBgenscheme\fP < schemes.txt -o MySchemes fvwm2

\fBgenscheme\fP < schemes.txt -o MySchemes -suffix .xrdb Motif_res

\fBgenscheme\fP < schemes.txt -o MySchemes
.in +1
 -m4opts
 "-Dcmd=\\"Exec xrdb -m \\\\\\"OutputDir/Name.xrdb\\\\\\"\\"" cmd
.in -1

\fBgenscheme\fP < schemes.txt -o MySchemes
.in +1
 -m4opts
 "-Dcmd=\\"Exec xsetroot -solid \\\\\\"Background\\\\\\"\\"" cmd
.in -1
.in -2

The first line creates the fvwm2 related color scheme files.  The
second line creates corresponding but independent Motif-related
resource files (the included sample sets only a few resources).  The
third line generates fvwm2 commands to merge the resources in, while
the last line adds an fvwm2 command to set the background color.  The
fvwm2 menu file is created as append.out in the MySchemes directory,
but it might be easier to rename it to something else than specify the
-appendfn argument for each of the above.  Likewise, you might leave
out the -o MyScheme option and just rename the genscheme.out directory.

To simplify the above process, you might make a shell script similar
to the following (works best for the fvwm2* templates):

.in +2
#! /bin/sh
.br
if [ "$#" != 3 ]; then
.br
	echo "usage: $0 <color file> <output dir> <template>";
.br
	echo "warning: output directory will be removed!";
.br
	exit 1;
.br
fi
.br
rm -rf "$2"
.br
genscheme < "$1" -o "$2" -m4opts \\
.br
  "-DFont=-adobe-helvetica-medium-r-*-*-12-*-*-*-*-*-*-*" \\
.br
  -appendfn Schemes.fi "$3"
.br
genscheme < "$1" -o "$2" -m4opts \\
.br
  "-Dcmd=\\"Exec xsetroot -solid \\\\\\"Background\\\\\\"\\"" cmd
.in -2

.SH FILES
\fBgetscheme.exe\fP \-\- Win32 executable to obtain color schemes

\fBtemplates/*\fP \-\- sample templates

Running \fBgenscheme\fP without arguments will display the directory
location of the above files.

.SH AUTHOR
Andrew Veliath <veliaa@rpi.edu>