##################################################################
Desktop Mascot Program for UNIX
macopix : Mascot Constructive Pilot for X
ver 3.4.0
Document in English : README
2019.12.28 Kurumi Chimari
chimari@rosegray.sakura.ne.jp
http://rosegray.sakura.ne.jp/
##################################################################
=============================================================
-- Table of Contents --
- About this program
- Environment
- Install
- How to Start
- Creating files, necessary files
- Mascots
- Launcher Menu
- Biff function
- Time Signal
- Socket Message
- Duet Animation
- SSL Support
- Tranlucent Windows
- To Do
- Copyright
=============================================================
**About this program
MaCoPiX is a Gtk based desktop mascot program running under
- UNIX (X window systems)
- Microsoft Windows (7 or later)
- macOS : OS X 10.9 (Mavericks) or later
.
Windows and macOS versions are distributed as compiled (binary) package.
Most of the text in this document describes about MaCoPiX UNIX
version. So, fo windows, please see Readme-win32.jp (sorry, Japanese
only, yet).
This program could be an evolved one from "ActX" (Activate X
window system).
Currently, you can make following types of mascots using MaCoPiX.
- Focus follower (Window sitters : likely ActX)
- Fixed style (Desktop wappen?)
Furthermore, you can select with or without a digital clock for
each types of mascots. So, MaCoPiX can be used as a sort of desktop clock
applications. (But the clock function could be still poor.)
And, the biff function is also available for POP/APOP/UNIX local
spool/qmail Maildir environments.
At once, users can create mascots and change their settings from GUI
instead of editing mascot files directly.
Please pay attention that the mascot file of MaCoPiX has no
compatibility with that of ActX.
**Environment
Basically, MaCoPiX needs UNIX / X window system or Microsoft Windows.
[for UNIX]
- Gtk+3 > ver3.22 (or Gtk+2 > ver2.24)
- glib > ver2.32
- gettext > ver0.10
- openssl > ver1.0 (or gnutls > ver1.4)
are necessary.
MaCoPiX can load all image types supported by gdk-pixbuf.
But, you need libraries to support each types of images
(ex. libtiff, libpng) in order to load each types of images.
The official MaCoPiX mascots are served in PNG files now.
[for Microsoft Windows (binary package)]
- Windows7 or later (64/32 bit) (10 [64bit] should be recommended.)
- Including TAR64.DLL / TAR32.DLL (GPL) in the binary distribution.
* You can dounload it (free-software, GPL) form the HP of
"Common Archiver Library Project".
URL http://www.csdinc.co.jp/archiver/index-e.html
- Compiled in msys2 with GtK+3 Without socket message function.
- All required libraries (Gtk+ etc.) are also included in the
binary package.
[for maOS (binary package)]
- 10.9 (Mavericks) later (64 bit)
- Compiled with Gtk+3 in Homebrew environment
- All required libraries (Gtk+ etc.) are also included in the
binary package.
**Install (Unix from source)
1. extract source archive, change directory to the created one.
2. ./configure
##################################################################
./configure options
[Gtk+] (default is for Gtk+3)
./configure --with-gtk2 (use Gtk+2)
[SSL] (default is OpenSSL)
./configure --with-gnutls (use GNUTLS instead of OpenSSL)
./configure --disable-ssl (none support for SSL; not recommended)
[Win32] (default is for UNIX)
./configure --with-win32 (making for Win32)
[TAR32] (default is off)
./configure --with-tar64 (use TAR64.DLL for 64bit)
./configure --with-tar32 (use TAR32.DLL for 32bit)
[UNLHA32] (default is off)
./configure --with-unlha32 (use UNLHA32.DLL for 32bit)
##################################################################
3. make
4. su
5. make install
(If you need to internationalize your menu message (using gettext),
you have to do "make install" as a root.)
**How to start
In anyway, at least one mascot file is necessary to use MaCoPiX.
Just running MaCoPiX, with the following command even without mascots.
% macopix
Then you will find a button to download official mascots via the
official web in the start up menu (network connection is required).
Please select one and download & install it to use MaCoPiX for
the first time.
If you already have a mascot which you want to use, please appoint
its .mcpx file in your command line like
% macopix mascot.mcpx
After starting the application, you can add mascots and change all
settings from the pop-up GUI.
The command line options appears with -h (or --help) option.
**Creating files, necessary files
MaCoPiX needs (and creates) the following files...
a. Mascot file (*.mcpx)
And a mascot includes images (and sound files, if necessary).
b. Resource file (* .rc)
c. Launcher Menu file (*.menu)
Basically, these files are copied or created in the "User Directory"
(HOME$/.macopix/ for each users).
About a., please see the following item as "Mascots".
b., the resource file is the file described the parameters kept all
times regardless of changing mascots.
If you do not appoint any files for the resource file (you can
appoint the resource file which you want to load with "-r" option),
the default one (HOME$/.macopix/macopix.rc) should be loaded.
c. is the Launcher menu in which your favorite mascots are registered.
Please see the following item "Launcher menu".
**Mascots
The mascot of MaCoPiX is made up with
- a mascot file (*.mcpx)
- image files (You can use any image types loaded by
gdk-pixbuf)
likely in the case of ActX.
Of course, you can use shaped mascots, if you appoint the shaped
images with alpha values (ex. png, gif, xpm).
At the starting time of the application, the mascot file should be
appointed as "% mascot mascot.mcpx".
In such case, MaCoPiX automatically searches the mascot file
according to the following priority.
1. absolute path or relative path from the current directory
2. User Directory ($HOME/.macopixrc/)
3. Common Directory (/usr/share/macopix/ ?)
User directory(2) should be automatically created at the first time
for using MaCoPiX.
Distribution Directory(3) will be determined by the installer
at the time of installation.
Image files should be appointed in the mascot file.
These files are also searched according to the following priority.
1. same directory where the mascot file exists
2. User Pixmap Directory ($HOME/.macopixrc/pixmap/)
3. Common Pixmap Directory (/usr/share/macopix/pixmap/ ?)
And, if you selected automatic install (option -a; saved in the
resource file), mascot files are automatically installed at the time
of loading.
Starting with the -O (--over-write) option, the priority of loading
will change to 1 > 3 > 2 in order to overwrite mascots in user
directory with ones in the distribution directory installed by
RPM package etc.
You should take care of the locale of your system to use mascots.
Mascot files are recommended to be written in one of the locale.
If you use the mascot in the different locale environment, balloons
and menus could not be presented correctly.
The author of this application will release his mascots in "ja"
(Japanese-euc) locale.
If you interested in them, please translate them for your environment.
Furthermore, if there is a gettext message file (in po/ directory of
the source tree) for your environment, you can change the dialog
messages of GUI into your language.
When you translated these files, please contact with the author.
**Launcher menu
In the field "Mascot Launcher" of the po-pup menu, you can register
your favorite mascot for easy changing.
To use this function, you have to prepare the launcher menu file (*.menu).
You can load and create it from the pop-up menu in every time.
And you can also edit it in the configuration dialog.
It is difference from the ActX one that the menu file has two levels
as "Category" -> "Mascot".
All "Mascots" have to be included in "Categories".
Each resource file can appoint one menu file as its default menu file.
If no menu files are appointed at the starting, this default menu
should be loaded.
If no mascot files are appointed at that time, a mascot selected at
random from the menu file should be loaded.
Furthermore, if you don't the appointment of the default menu in your
resource file, the menu selection dialog will appear in startup.
If you appoint a menu file at the starting time, please use "-m" (or
"--menu") option.
**Biff function
### Currently the author only checks POP3 (w/ and w/o SSL). ###
MaCoPiX can be a mail checker for the following types of the mail
environment.
1. local spool (UNIX mbox : /var/spool/mail/$USER etc)
2. POP3 (SSL/TLS)
3. POP3 (APOP auth) (SSL/TLS)
4. qmail (Maildir)
5. MH + Procmail
After preparing proper configuration, please start MaCoPiX with "-b"
(or "--biff") option, or please check "Biff Check" on the pop-up
menu.
If you use the biff checker in POP, your password are saved in the
resource file with plain text.
So, please be careful for the management of the resource files.
(Basically, the resource files can be seen only by yourself.)
- for POP3/APOP
In "Server information" of GUI, input "Address", "UserID", "Password",
"POP3 Port No."(You should not change it in usual cases.).
You don't need to edit "File" entry.
POP over SSL (SSL/TLS) has been supported from ver 1.6.2,
experimentally.
- for qmail (Maildir)
In "File" entry of "Server information" of GUI, input the
Maildir directory in which newly arrived mails are stocked
( $HOME/Maildir/new in the most of cases ).
- MH + Procmail
In "File" entry of "Server information" of GUI, input the
full-path of log file for procmail, "procmail.log". (In the most
of cases, this file are appointed in "LGFILE=" entry of
$HOME/.procmailrc )
The mail directory for MH is automatically searched as the
following order, (1) "MAILDIR" entry in $HOME/.procmailrc,
(2) $HOME/Mail .
If you want to poll to the mail server periodically via fetchmail
or something else, you should input command for polling into
"Polling" entry in "Operating Information of Biff GUI.
**Time signal function
MaCoPix has a time signal function, which do some actions (external
command, mascot changing ... etc.) every hour on the hour (00 minute).
After preparing proper configuration, please start MaCoPiX with "-s"
(or "--signal") option, or please check "Time Signal" on the pop-up
menu.
The configurations for this function are saved in the resource file.
"Mascot Random Change" cannot work, if you do not appoint any menu
files.
**Socket Message
Now mascots can speak any messages appointed in command line externally.
1. Start MaCoPiX with --sockmsg option.
You can start only one mascot at the same time.
2. From terminal command line, type
macopix --message "Hello!"
You can see this message on your mascot balloon.
You should change character code of the message following your locale.
3. If you want to change the expiration time to display each socket
messages, you can appoint it like this way.
macopix --message "Hello!" --message-expire 5000
Using this --message-expire option, you can set the expiration
time to display each messages (unit is msec).
Without this option, the default expiration time will be used.
It can be set on GUI.
4. In the socket message balloon, you can also use "Stepping mode".
This mode will set "%c" control character automcatically in your
sending message.
This can be set in GUI and also in command line options to send
a message.
**Duet Animation (only for UNIX ver)
Using socket communication, some animation can be connected between
two mascots.
If you start Sachiko-sama and Yumi at the same time, and click one
of them....
- Each mascots makes /tmp/macopix-(userID)/macopix-(mascot file) temporal
file. If MaCoPiX was stopped abnormally these files can remain,
but they will not affect the next time.
- If the two or more same mascot start, the later will use this
temporal pipe file.
But, if the former is stopped or changed, this pipe should be closed.
**SSL Support
This program can compile with a link to OpenSSL or GNUTLS libraries
(or without either) to support POP over SSL on its biff function.
Because OpenSSL is a non-GPL freeware. I have to add a special
exception for GPL to link this program with OpenSSL.
If you feel uneasy about this license issue, please link with GNUTLS.
You can switch it with ./configure option before compiling.
- OpenSSL (default)
- GNUTLS (./configure --with-gnutls)
- without SSL (./configure --disable-ssl)
When your environment for gnutls development does not satisfy to make
this program, OpenSSL will be used instead of GNUTLS.
In actual operation, GNUTLS version has some different points, compared
with OpenSSL ver.
- GNUTLS ver. always skippes confirmation on SSL certification.
If you neglect the license matter, I recommend to use OpenSSL rather
than GNUTLS.
**Tranlucent Windows
MaCoPiX ver 3 (ol later) only supports tranlucent mascot drawing
on compositing window managers.
(In 2019, the most of environments are supporting compositing.)
If you use it in non-compositing window managers, mascot / balloon
will not be drawn correctly.
The author does not know how often non-compositing window managers
are used nowadays.
If you find your environment meets this problem, please notify to the
author.
**Copyright
The code in this distribution is Copyright 2002 by Kurumi Chimari.
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, 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, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
In addition, as a special exception, K.Chimari gives permission to link
this code of this program with the OpenSSL library (or with modified
versions of OpenSSL that use the same license as OpenSSL), and distribute
linked combinations including the two. You must obey the GNU General
Public License in all respects for all of the code used other than OpenSSL.
If you modify this file, you may extend this exception to your version of
the file, but you are not obligated to do so. If you do not wish to do so,
delete this exception statement from your version.