[MD:462]Meadow Manual(2)

[Miyashita Hisashi(宮下 尚:HIMI) <himi@xxxxxxxxxxxxxxxxxxxxxxxxx>]

とりあえず、早く出したいので、現在のFinal Draftを出します。
修正要求は早くください。

From himi

***************************************************************************
     Meadow 0.50 Basic Manual.
       (Multilingual enhancement to gnu Emacs with ADvantages Over Windows)
	Written by Miyashita Hisashi <himi@xxxxxxxxxxxxxxxxxxxxxxxxx>
	Edited by Takeyori Hara <takeyori@xxxxxxxxxxxxxxxxxxxxxxxxx>
***************************************************************************

1..... Introduction

  Meadow is multilingual enhancement to gnu Emacs that is runnable on
Windows95/NT.  It is based on GNU Emacs 20.x currently.  I plan to
extend many features to Meadow.  Thus, Meadow may change from original GNU
Emacs, maybe or not maybe. :-)

2..... Installation

  Installation is very easy.  Please read `INSTALL.Meadow.'

3..... Configuration

  Fundamentally, the configuration of Meadow is identical to original Emacs.
This chapter explains Meadow specific configurations.  As to other configurations,
please refer the original documentations of Emacs.

------------------------------------------------------

3.1..General features.

3.1.1.... w32-system-coding-system.

  To this variable, you must set the coding system that is sent to
Windows operating system.  It is used for encoding menu strings,
fontname strings, title bar strings, and so on.

3.1.2.... (Meadow-version)

  You can retrieve the version strings of the Meadow.

3.1.3.... (w32-set-modifier-key KEY MODIFIER)

  You can set modifier keys by this function.
Please read documentation strings.

3.1.4.... Console Mode and Terminal Mode

  You can use Win32 console, by adding option `-nw' and
you must set TERM environment variable to `CMD'.
e.g
    set TERM=CMD
    MeadowNT -nw or Meadow95 -nw

  You can't use IME on console mode on Windows95.

  Or you can use terminal mode with adequate telnet service.
You must prepare `termcap' file.  For example when you put termcap c:\,

    set TERMCAP=c:\termcap
    set TERM=vt100        (Set your terminal ID.)
    MeadowNT -nw or Meadow95 -nw

  You can't use IME on terminal mode.

3.1.5.... Mouse features.

  Meadow is aware of 3button mouse including IntelliMouse.
Buttons can be remapped by these variables.

w32-lbutton-to-emacs-button
w32-mbutton-to-emacs-button
w32-rbutton-to-emacs-button

  These indicates button number that is sent to Meadow when
left, middle, or right buttons are pressed or depressed respectively.

  When IntelliMouse wheel is rotated, Meadow receives an event as shown
here.

(mouse-wheel1 ([WINDOW | FRAME] POSITION (X . Y) TIME DELTA))

[WINDOW | FRAME] shows a window or frame where the mouse cursor is.
POSITION shows which area the mouse cursor is in.
(X . Y) shows a coodinate of the mouse cursor.
DELTA shows a rotation angle of wheel.
You can pass DELTA to this function to obtain the amount of scroll lines.
--
(w32-get-mouse-wheel-scroll-lines DELTA)
--

  The default setting of wheel operations are scrolling buffer
contents when a mouse cursor is at a buffer window, or moving mode
line when a mouse cursor is at a mode line.

------------------------------------------------------

3.2..fontset setting.

;; (himi) ここは重点的に直します。logfontの説明を頭に持っていきます。
;; とりあえず、原さんの修正が入っています。漏れがあれば、教えてください。

  A fontset will be set automatically.  You can use `default-fontset' by default.
If you want to make another fontset, you can use the functions in the section (3.2).

  Meadow's fonts have properties. Properties are used to store logfonts.

  `Logfont' is an abbereviation of `logical font' that is mapped to a real
 font by Meadow.  Currently, we can use BDF(Bitmap Distributed Format),
Windows fonts(both bitmap and TrueType), and others); the following types
are allowd.

1.... Windows logfont.
  Windows logfonts are specified by a list like follows,
--
(w32-logfont <NAME> <WIDTH> <HEIGHT> <WEIGHT> <ITALIC-P> <STRIKEOUT-P>
             <CHARSET> <QUALITY> <OUTPRECISION> <PITCH&FAMILY>)
--

  NAME.......... the font name within 31bytes.
  WIDTH......... width of the font(number)
  HEIGHT........ height of the font(number)
  WEIGHT........ weight of the font(number)
                 Normal weight is 400.
                 Bold weight is 700.
  ITALIC-P...... Non-nil specifies an italic font.
  STRIKEOUT-P... Non-nil specifies a strikeout font.
  CHARSET....... Specifies a charset number of the font.
  PITCH&FAMILY.. Specifies whether a font is fixed or not,
                 and a font family.

  This list is based on Windows logfont.
When you want to know your desired logfont, please use
---
(w32-query-get-logfont)
---
  This function pop up a font selection dialog box, and return the logfont
of the selected logfont.

2.... BDF font.
  Meadow can use BDF fonts.
BDF fonts' logfont are specified by a list as shown here.
--
(bdf-font "FILENAME")
--
  FILENAME must be a valid filename of a BDF font.

Properties are discriminated by a number ranged 0-15.
And each number means as followd.

0...... Normail font
1...... Bold font
2...... Italic font
3...... Bold-Italic font

4-7.... Reserved for extension

8...... Normal font for printings
9...... Bold font for printings
10..... Italic font for printings
11..... Bold-Italic font for printings

12-15. Reserved for extension

  For example, if you set a `courier' windows logfont to the property 2
of a font, Meadow will display a `courier' font when a emacs lisp library would 
display this font as a `italic'.

  When the desired property has not been setted yet, the most
significant non-zero bit of the number is cleared, and iterate to
search a setted property.  When Meadow can't find any logfonts
even in property 0, Meadow use the default logfont as follows.

Property 0
   (w32-logfont "FixedSys"
                <get from font attribute>
                <get from font attribute> 400 0 nil nil 128 0 0 1)
Property 1
   (w32-logfont "FixedSys"
                <get from font attribute>
                <get from font attribute> 700 0 nil nil 128 0 0 1)
Property 2
   (w32-logfont "FixedSys"
                <get from font attribute>
                <get from font attribute> 400 0 t nil 128 0 0 1)
Property 3
   (w32-logfont "FixedSys"
                <get from font attribute>
                <get from font attribute> 700 0 t nil 128 0 0 1)

3.2.1......high level APIs.

3.2.1.1....fontset requests

----
(create-fontset-from-request NAME REQUIRED RECOMMENDED)

NAME is name of the fontset you want to create.
REQUIRED and RECOMMENDED are a-lists.
REQUIRED means that all fonts that are selected MUST satisfy
these conditions.
RECOMMENDED means that fonts that satisfy these condition
are given priority over creating a fontset.

New fonts are created with name of "NAME-CHARSET" for 
each available charset, and configured to property 0 
automatically.

Following keys are awared in these a-lists.
(Others are ignored)

o..... family (STRING)
  family name of the font (Regular expressions are not allowed.)

o..... width  (NUMBER)
  width of the font(pixel)

o..... height (NUMBER)
  height of the font(pixel)

o..... weight (NUMBER)
  weight of the font.
  It is normail about 400.
  It is bold about 700.

o..... fixed  (nil or t)
  nil means that the font is not fixed-pitch.

o..... italic (nil or t)
  nil means that the font is not italic.

e.g.

(create-fontset-from-request
  "myfontset"
  '((width . 8)
    (height . 12)
    (fixed . t)
    (italic . nil))
  '((family . "Courier")
    (family . "MS Gothic")))

----
(change-fontset-from-request NAME REQUIRED RECOMMENDED PROPERTY)

  Change configurations of fonts in the fontset of NAME.
You can specify PROPERTY that must be a number of property.
This function set this property from your reguest.
REQUIRED and RECOMMENDED are the same meanings in
(create-fontset-from-request)
----

3.2.2......low level APIs.

  Low level APIs handle logfonts directly.


3.2.2.1....(w32-add-font NAME ALIST)

This function regist font.  Then Meadow can use this font by NAME.
NAME must be string.  ALIST is used for description of the font
to use.

ALIST may contain the following keys.
You can use w32-default-font-alist.
Meadow use this variable to compensate ALIST.
Of course settings of ALIST have precedence over
ones of w32-default-font-alist.
------------------------------
Required key.

o..... width
o..... height
o..... base
o..... overhang

  These set metrics of the font.

o..... encoding-type

  This sets encodings ot the font.  You can set 0, 1, 2, 3, 4 to this.
When you set `encoder' key, this setting is used for the octet length
of one character.

0..... Code points are not encoded.
       The octet length of One character depends on a dimension of the charset.
1..... Code points are encoded by bitwise-or of 0x80.
       One character is one octet.
2..... Code points are encoded by bitwise-or of 0x8000.
       One character is two octet.
3..... Code points are encoded by bitwise-or of 0x0080.
       One character is two octet.
4..... Code points are calculated by SHIFT-JIS encoding methods.
       One character is two octet.

Optional key.

o..... relative-compose
o..... default-ascent

  These set metrics of the font.  If these are omitted, Meadow use 0.

o..... encoder

  This set the encoding method.  You can set the symbol of the encoder.
This symbol must have a property list that has `ccl-program' key.
(In the future, other keys may be allowed.)

  The entity of a key `ccl-program' must be a vector of CCL program,
which is used for calculating code points to print the font.

3.2.2.2....(w32-change-font-attribute NAME ALIST)

  You can reconfigure the font settings.
NAME is a font name that has been added.
ALIST has the same meanings in (w32-add-font)

3.2.2.3....(w32-change-font-logfont NAME LOGFONT PROPERTY)

  Set a LOGFONT to PROPERTY of font(NAME).
LOGFONT must be a valid logfont.

3.2.2.4....(w32-get-font-logfont NAME PROPERTY)
3.2.2.5....(w32-get-font-info NAME PROPERTY)
3.2.2.6....(w32-get-logfont-info NAME PROPERTY)


3.2.2.7....(w32-font-list)
3.2.2.8....(w32-enum-logfont FAMILY &optional DEVICE)
3.2.2.9....(w32-query-get-logfont)
3.2.2.10...(w32-check-logfont LOGFONT)

  Please read documentation strings. :-)

3.2.2.11...w32-default-font-alist

  Please read documentation strings, and (w32-add-font).

------------------------------------------------------

3.3..Argument Editing

  Meadow can invoke external processes.  But arguments of the external
process is very different from the UNIX style.

  In the UNIX style, arguments have the style like this.

argv[0] = /usr/bin/ls
argv[1] = -l
argv[2] = "/home/himi/foo"

  But on Windows, arguments must be a single string.  To take
matters worse, how to connect these strings depend on each program.

o...Normal Style.
  Only connect them.  They are separated by " "(SPACE).
In the above example, the result is
`/usr/bin/ls -l "home/himi/foo"'.

o...Microsoft Visual C++ Style.
  Microsoft Visual C++ connects these arguments with quoting by `"'.
And each arguments are separated by " "(SPACE).
If a argument contains `"', quote it by `\'(Backslash).
If its `"' is located after `\', quote the `\'  by `\', too.

o...Cygnus system style.
  Cygnus system connects these arguments with quoting by `"'.
And each arguments are separated by " "(SPACE).
If a argument contains `"', convert it to `""'.

  Therefore Meadow have the facility of Argument Editing.
You can edit arguments arbitrary by this facility.

  Argument Editing select the method of editing from the program name.
It is specified by regular expressions.  Argument editing system
compaires these settings to the program name that is about to be
invoked by Meadow.  If it is matched by a setting, Meadow call the
function that is associated by the setting to edit arguments.

You can configure Argument Editing by the following functions and variables.

---------------
  (define-process-argument-editing PROCESS FUNCTION &optional METHOD)

  Set argument editing.
PROCSSS is a regular expressions to specify the process whose
arguments are edited by FUNCTION.  Argument editing system compaires
path of the processe that is complete and separated by `/' with PROCESS.
When PROCESS matches tha path of the process, Argument editing system
call FUNCTION to edit argument.

FUNCTION is called with a list of arguments that are supposed to be
passed to the process.  FUNCTION must return one of the following manners.

o....a string of argument.
  If FUNCTION returns string, the process is created with this string
as an argument.

o....(PROGRAM . ARGUMENT)
  Both of them must be strings.
  If FUNCTION returns this type, argument editing system create a process
of PROGRAM with ARGUMENT as an argument.


METHOD specifies how this setting is registered.
The followings are allowed.

o.... 'first
  Register this setting at first.
Thus this setting have the highest precedence.

o.... 'last
  Register this setting at last.
Thus this setting have the lowest precedence.

o.... 'append
  Append this setting.
If PROCESS has been registerd already, nothing happens.
If not so, register this setting at first.

o.... 'replace
  Replace this setting.
If PROCESS has been registerd already, replace the setting.
If not so, nothing happens.

o.... nil
If PROCESS has been registerd already, replace the setting.
If not so, register this setting at first.

---------------

  (remove-process-argument-editing PROCESS)
  (find-process-argument-editing-funciton PROCESS)
  default-process-argument-editing-function (variable)

  Please read documentation strings.

---------------

  (general-process-argument-editing-function ARGUMENT QUOTING ARGV0ISP
                                             &optional EP H2SP QP S2ISP)

  This is a general function to edit argument.
ARGUMENT must be a list of arguments.
QUOTING specifies how to quote arguments.
The followings are allowed.

o.... nil
  Only connect them.  They are separated by " "(SPACE).
o.... 'msvc
  Quotes arguments in the style of Microsoft Visual C++.
o.... 'cygnus
  Quotes arguments in the style of Cygnus libraries.

  If ARGV0ISP is non-nil, convert a separator of argv[0] to `\\'.

  After connecting arguments in the sytle of QUOTING into a single string,
the string is converted according to  EP, H2SP, QP, and S2IPS.

If H2SP is non-nil, '-' in a string will be converted to '/'.
If S2ISP is non-nil, '/' in a string will be converted to '\\'.
If EP is non-nil, regards '\\' as an escape character, thus,
any character followings to '\\' is NEVER converted.
If QP is non-nil, regard a part enclosed with ' or " as a quoted-string,
thus it is NOT converted.

------------------------------------------------------

3.4..Input Method Editor(on Windows)

  Of course you can use IME on Windows.
Meadow have IME automatic control system, you can use it by this setting.
-----
(mw32-ime-initialize)
-----
Please add this line to the head of your .emacs.

And then, please select the `MW32-IME' input method by this setting.
-----
(select-input-method "MW32-IME")
-----
If you want to turn off the input method, add this setting.
-----
(inactivate-input-method)
-----

  You can set IME composition font by specifying `ime-font' key
in the frame-alist.  But this MUST BE a Windows font.

e.g.
(setq default-frame-alist
      (cons '(ime-font . "IME font")
	    default-frame-alist))

------------------------------------------------------

3.5..Other functions, variables

<Reserved>

------------------------------------------------------

4...Annotation

------------------------------------------------------------
  Meadow can use Extended CCL, so you will use MULE-UCS soon.

  MULE-UCS is the library that can translate another coding systems
that is deferrent from ones based on ISO-2022.

  This library also have ISO-10646 configurations normally.
So you can use ISO-10646 coding systems with a little settings.
------------------------------------------------------------


------------------------------------------------------------
  Meadow does NOT retrieve FQDN in its startup.
Therfore, (system-name) would not give the FQDN in case of default.
But you can get the FQDN of your host by (w32-get-fqdn) function.

For example, you can set the following setttings in your start up file
(.emacs, site-start.el .etc), and you could get the FQDN by (system-name)

---------------
(setq system-name (w32-get-fqdn))
---------------

This setting maybe make your system popup the dialup network dialog.
You want to cease this dialog, plese check the following.

o....Set the correct domain name and host name in the Control Panel.

  You should set the domain name and host name by the Control Panel.
Pop up the Control Panel, and then Select 'Network', click 'Protocol' tab,
select 'TCP/IP Protocol' by double click, and then click 'DNS' tab.

  You will see two edit controls---'Host name' and 'Domain'.
For example, we assume your full qualified domain name(FQDN) is
`machine1.anonymous-u.ac.jp'.
You must set `machine1' to the `Host name' entry, and `anonymous-u.ac.jp'
to the `Domain' entry.

Have you resolved this problem? 
If you can't, please check the next.

o....Set the `hosts' file.

  Windows socket system also resolve domain names by hosts file.
Therefore, you can resolve your host by setting this file.
First, you should copy `hosts.sam' file in the Windows directory.
Then please change the `localhost' entry into what is like this.
-----------------------
127.0.0.1	localhost <YOUR HOST NAME(FQDN)>
-----------------------

------------------------------------------------------------

5..... Informations of mailing lists.

There are two mailing lists for discussing about Meadow.
But this service is temporal, and in the future, we will change.

meadow-users-en@xxxxxxxxxxxxxxxxxxxxxxxxxxx (English)
If you want to join, please send empty mail to
  <meadow-users-en-subscribe@xxxxxxxxxxxxxxxxxxxxxxxxxxx>.
If you want to unsubscribe, please send empty mail to
  <meadow-users-en-unsubscribe@xxxxxxxxxxxxxxxxxxxxxxxxxxx>.
A confirmative mail is sent to you automatically.

meadow-users-jp@xxxxxxxxxxxxxxxxxxxxxxxxxxx (Japanese)
If you want to join, please send empty mail to
  <meadow-users-jp-subscribe@xxxxxxxxxxxxxxxxxxxxxxxxxxx>.
If you want to unsubscribe, please send empty mail to
  <meadow-users-jp-unsubscribe@xxxxxxxxxxxxxxxxxxxxxxxxxxx>.
A confirmative mail is sent to you automatically.

6..... Acknoledgement

I thank many people for contributing to Meadow.

I have a great deal of gratitude to...
   Kenichi Handa
   Satoru Tomura
   Yutaka Niibe
   and Electrotechnical Laboratory Mule Project!
This software can't exist without their contribution.

And this manual is fixed by Takeyori Hara.
Without his help, this manual may be senceless. ^^;;;
I thank him a lot.

And people who contributed.

Chris Szurgot (ftp.exe)
Hiroya Tsubakimoto. (telnet.exe)
Shuhei Yamaguchi. (mw32script, and others)
Shuichi Kitaguchi. (fiber.exe)

Of course I want to thank Free Software Foundation.

Lastly, thanks to
"Mule for Win32 mailing list" and "Meadow development mailing list" members!.



------------------------------------------------------------
A..... License

  Fundamentally, Meadow follows the original license of GNU Emacs,
which is GPL (gnu General Public License) Version 2, or (at your
option) any later version.

  You should have received a copy of the GNU General Public License
along with Meadow(GNU Emacs); see the file COPYING.  If not, write to
the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

  But `ftp.exe' included in the binary distribution of Meadow is an
exception.  This program is allowed to include in the package by
Chris Szurgot<szurgot@xxxxxxxxxx>.
If you want to know its correct license, please contact him.
(Original source is distributed in the BSD style aka "AS-IS".)

  And `telnet.exe' included in the binary distribution of Meadow is another
exception.  This program is ported by Hiroya Tsubakimoto.
This program is allowed to include by Hiroya Tsubakimoto<zorac 4000do.co.jp>.
Its original is also distributed int the BSD style.

B.....File name.

  Packages of Meadow is named the following file names.

Meadow-${VERSION}-src.tar.gz		Source package
Meadow-${VERSION}-i386.tar.gz		Intel x86 Binary
Meadow-${VERSION}-Alpha.tar.gz		Alpha Binary

  If you want to rename them in 8.3 filename to redistribute,
please rename under the following rule.

Meadow-${VERSION}-src.tar.gz -> MW${VERSION}s.tgz
Meadow-${VERSION}-i386.tar.gz -> MW${VERSION}i.tgz
Meadow-${VERSION}-Alpha.tar.gz -> MW${VERSION}a.tgz

  Its reason is simple.  Various names would confuse me.
------------------------------------------------------------