1 Installation 
==============

   To  use  whizzytex,  you  need  Emacs  or  XEmacs,  latex2e,  and bash
   installed, and at least one DVI or Postscript previewer, such as advi,
   xdvi, or dvips combined with gv.
   WhizzyTeX  has  been developed under Linux Redhat 7.2 but has not been
   extensively  tested on other platforms. However, LAT[E]X and Emacs are
   quite  portable  and  possible  compatibility  problem  with  the bash
   shell-script should be minor and easily fixable.
   Get   the   source   whizzytex-1.3.0.tgz   from  the  [3]distribution,
   uncompress and untar it in some working directory, as follows:

        gunzip whizzytex-1.3.0.tgz
        tar -xvf whizztex-1.3.0.tar
        cd whizzytex-1.3.0

   Then,  the  installation  can be automatic (default or customized), or
   manual.

  1.1  Automatic installation
  ---------------------------

   By    default,   shell-script   whizzytex   will   be   installed   in
   /usr/local/bin/  and  all  files  will  be installed a subdirectory of
   /usr/local/share/whizzytex/  but  the  documentation,  which  will  be
   installed  in  /usr/local/share/doc/whizzytex/.  Moreover,  Emacs-lisp
   code will not be byte-compiled.
   For default installation, just type:

        make all

   This  will  create  a  Makefile.config  file  (only if nonexistent) by
   taking a copy of the template Makefile.config.in. This will also check
   the  Makefile.config (whether it is the default or a modified version)
   against  the software installed on your machine. If you wish to change
   the  default  configuration, or if your configuration is rejected, see
   ``Customizing  the  installation''  below.  This  will  also  prepared
   configured versions of the files for installation.
   Finally,  to install files, become superuser (unless you are making an
   installation for yourself) and do:

        umask 022 && make install

   The  first  line  ensures that you give read and execute permission to
   all.
   See Using WhizzyTeX (Section [4]2) to test your installation.

  1.2  Customizing the installation
  ---------------------------

   To customize the installation, you can edit Makefile.config, manually.
   You may also use either the command

        ./configure

   This  command  may be passed arguments to customize your installation.
   Call  it  with  the  option  -help  to  see  a list of all options. By
   default,  the  configuration is not interactive. However, you may call
   it with option -helpme to have the script do more guessing for you and
   prompt for choices if needed.
   Note  that  by  default,  the  Emacs-lisp  code  whizzytex.el  is  not
   byte-compiled.  You need to pass the option -elc to configure in order
   to byte-compiled it.

   -- Checking Makefile.config

   A  misconfiguration of your installation, or ---much more subttle--- a
   misconfiguration of other commands (it appears that some installations
   wrap scripts around standard commands that are sometimes incorrect and
   break their normal advertized interface) may lead to systematic errors
   when  launching  WhizzyTeX.  To  prevent delaying such obvious errors,
   some  sanity  checks  are done after Makefile.config has been produced
   and  before building other files. These include checking for mandatory
   bindings  (useful for manual configuration) and for the conformance of
   initex, latex, and viewers commands to their expected interface.
   Checking  viewers  interface  implies  simulating  a  small  WhizzyTeX
   session: a small test file is created for which a specializled version
   of  latex  format  is  built and used to run LAT[E]X on the test file;
   finally,  required  viewers  are tested on the DVI output, which opens
   windows, temporarily.
   If  the  sanity  check  fails,  at least part of your configuration is
   suspicious.  If  some  windows  remain  opened, your confirguration is
   likely to be erronesous (and so, even if not detected by the script).
   However,  if  you  really  know what you are doing, you may bypass the
   check   by   typing   make   config.force,   which   will  stamp  your
   Makefile.config as correct without checking it. Checking compliance to
   viewers interface is also bypassed if you you do not have a connection
   to   X.   Conversely,  you  may  force  checking  manually  by  typing
   ./checkconfig.
   At  the  end  of  customization,  proceed  as described in ``Automatic
   installation'' (Section [5]1.1)

      Customization notes

   By  default,  WhizzyTeX  assumes the standard convention that latex is
   the  command  name used to call LAT[E]X, initex, the command name used
   to build a new format, and that the latex predefined format is latex.
   If  your  implementation of LAT[E]X uses other names, you may redefine
   the  variables  INITEX,  LATEX,  and  LATEXFMT accordingly in the file
   Makefile.config.  For  instance,  platex  could  be  use  the  default
   configuration

        INITEX = iniptex
        LATEX = platex
        LATEXFMT = platex
        BIBTEX = jbibtex

   This would be produced directly with the configuration line:

        ./configure  -initex  iniptex -latex platex -latexfmt latex -bibtex
        jbibtex

   If  you  wish  to  run WhizzyTeX with several configurations, you must
   still  choose  a  default configuration, but you will still be able to
   call  WhizzyTeX  with  another  configuration  from Emacs (see Section
   [6]3.1.2 below).
   It is possible to customize the set up on a per-user basis by creating
   a file ~/.whizzytexrc containing, for example, the following lines:

        INITEX = iniptex
        LATEX = platex
        FORMAT = platex
        BIBTEX = jbibtex

   During  the  configuration,  you  must  at  least  choose  one default
   previewer  type  among  advi,  xdvi,  and  ps, and at most one default
   previewer for each previewer type you chose. You will still be able to
   call   WhizzyTeX   with   other   previewers  from  Emacs,  via  Emacs
   configuration (see Section [7]3.1.1).

  1.3  Manual installation
  ---------------------------

   Since WhizzyTeX only need three files to run, installation can also be
   done manually:

   whizzytex.el
 
       This  could be installed in a directory visible by Emacs, but does
       not  need to, since you can always use the full path when you load
       it or declare autoload.
       No default location.

   whizzytex
 
       This  file is a bash-shell script that should be executable. There
       is  not  reason to have it visible from the executable path, since
       it should not be used but with WhizzyTeX.
       The   variable   whizzytex-command-name  defined  in  whizzytex.el
       contains  its  full  path  (or  just  its name if visible from the
       executable path).
       Default value is /usr/local/bin/whizzytex
       You  may need to adjust the path of bash in the very first line of
       the  script, as well as some variables in the manual configuration
       section of the script.

   whizzytex.sty
 
       This  file  are  latex2e  macros.  There  is no reason to put this
       visible  from  LAT[E]X  path, since it should not be used but with
       WhizzyTeX.
       Variable  variable  PACKAGE defined in whizzytex the full path (or
       just the name if the path is visible from LAT[E]X.
       Default value is /usr/local/share/whizzytex/latex/whizzytex.sty

  1.4  Automatic upgrading
  ---------------------------

   For  convenience,  the distribution also offers a facility to download
   and  upgrade  new  versions  of  WhizzyTeX  (this  requires wget to be
   installed). If automatic upgrading does not work, just do it manually.
   All  operations  should  be  performed in the WhizzyTeX top directory,
   i.e. where you untar whizzytex for the first time, that is right above
   the directory from were you made the installation. We assume that have
   created a link to the current version subdirectory:

        ln -s whizzytex-1.3.0 whizzytex

   (the  manager  will  then  update  this  link  when  version changes).
   Alternatively, you can also use the full name whizzytex-1.3.0 in place
   of whizzytex below. The main commands are:

        make -f whizzytex/Manager upgrade
        make -f whizzytex/Manager install

   The  command  upgrade  will  successively download the newest version,
   unpack it, copy the configuration of the current version to the newest
   version,  and bring the newest version up-to-date. The command install
   will install files of the newest version.
   The following command will (re-)install an old version:

        make VERSION=<version> download downgrade install


2  Using WhizzyTeX
==================


  2.1  Loading whizzytex.el
  ---------------------------

   Maybe,  whizzytex  is already installed on your (X)Emacs system, which
   you may check by typing:

        ESC x whizzytex-mode RET

   If the command is understood, skip this section. Otherwise, you should
   first  load  the library whizzytex.el or, better, declare it autoload.
   To  do  this  permanently,  include  the following declaration in your
   Emacs  startup  file  (which  probably  is  ~/.emacs  if you are using
   Emacs):

        (autoload 'whizzytex-mode
            "whizzytex"
            "WhizzyTeX, a minor-mode WYSIWIG environment for LaTeX" t)

   This  asumes  that  whizzytex.el  has  been installed in your (X)Emacs
   load-path.   Otherwise,   you   may   either   adjust   the  load-path
   appropriately,  or  replace  whizzytex  by  the  full path to the file
   whizzytex.el,  which  depends on your installation and can be obtained
   by typing make where in the installation root directory. For instance,
   if  you  are  using  Emacs,  the  default location for whizzytex.el is
   /usr/local/share/whizzytex/lisp/whizzytex.el (but it will be different
   if you are using XEmacs or a customized installation).

  2.2  Quick start
  ---------------------------

   WhizzyTeX  runs  as  a minor mode of Emacs to be launched on a LAT[E]X
   Emacs  buffer.  The  extension of the buffer should be .tex. WhizzyTeX
   also  understands  .ltx  extensions,  but gives priority to the former
   when  it has to guess the extension. Other extensions are possible but
   not recommended.

        The  file  attached  to  the  buffer  must  exists  and either be a
        well-formed  LAT[E]X  source  file,  or be mastered, i.e. loaded by
        another  LAT[E]X  source  file.  Thus, whenever the buffer does not
        contain  a \begin{document} command), WhizzyTeX will search for its
        master  file,  asking  the  user  if need be, so as to first launch
        itself  on  a  buffer  visiting  the master file. In particular, an
        empty  buffer  will be considered as beeing mastered, which may not
        be what you intend. 

   To start WhizzyTeX on either kind of buffer, type:

        ESC x whizzytex-mode RET

   By  default,  this  should add new bindings so that you can later turn
   mode  on  and  off  with key strokes C-c C-w. This will also add a new
   menu Whizzy in the menu bar call ``the'' menu below. (If you are using
   the  auctex,  your  may  use  other configuration key strokes to avoid
   clashes (see online emacs-help).
   When  whizzytex-mode is started for the first time on a new buffer, it
   attempts   to   configure  buffer  local  variables  automatically  by
   examining  the  content  of  file,  and using default values of global
   bindings.
   You  may  customize  default  settings globally by running appropriate
   hooks  or locally by inserting appropriate comments in the source file
   ---see the manual below.
   You may also change the settings interactively using the menu, or tell
   whizzytex-mode   to   prompt   the   user  for  confirmation  of  file
   configuration  by  passing prefix argument 4 (using, for instance, key
   sequence C-u C-c C-w).

