This is the mail archive of the cygwin mailing list for the Cygwin project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

First Pass at mintty documentation


Hi, I've taken a first pass at distilling my experience with
'mintty' and the [ahem] discussion, here, about it into a text
file (see attachment mintty.{h})

If there is an affinity to it, I would be happy to plug this all
into a valid man template.

For my votes on 'mintty':

* I love it the way it is.

* Favorite features:
> Speed
> Speed
> Best conformance to my personal expectation of what various
directional keys (<HOME>, <END>, <->>, <<->, etc.) should do!
(However, still bummed that <CTRL>-<->> & <CTRL>-<<-> do not
move, respectively forward and back a word on the command
line!)
* Futures expectation: My number one goal would be for it to
replace the Cygwin console for everything, although I
understand there are great difficulties with that goal.


Because of the nature of various "discussion" elements in wading
through this stuff, I am referring to my documentation "project" as:
*Diuretics*!
***********

Thank you, very much, Mr. Andy Koppe.

Signed,

L. Dave Rothstein (Lee) ;-)


MinTTY
******

* Purpose

  > MinTTY is a terminal emulator (virtual terminal) for Cygwin
    that is better- integrated than any other available terminal
    emulator into Windows.

* Features:

  > Xterm-compatible terminal emulation, including support for
    modifier keys and application mouse mode.

  > Native Windows user interface that tries to keep things
    simple.

    = Window frame
    = Scrollbar
    = Right-click menu (also reachable via menu key)
    = Options dialog, with font and color selectors
    = Copy & paste behaviour (copy-on-demand, <CTRL>-<INS>
      copies, <CTRL>-V copies, shift-left click extends)
    = Drag & drop
    = Options dialog

  > X windows compatibilities, also

    = Options dialog allows configure in an Xish way
    = MinTTY can be configured via .minttyrc

  > Drag & drop and copy & paste of text and files. (The latter
    are inserted as quoted filenames.)

  > Mousewheel events can be sent as arrow keys. (This allows
    mousewheel scrolling, e.g., in 'less'.)

  > Options are stored in a text file ('~/.minttyrc'). Ergo no
    registry entries are required.

  > Window transparency.

  > Small executable size (currently <120K).

  > Not a replacement for the Windows Command Prompt. While
    Windows console programs with simple text output should work
    fine, more complex output will likely not display correctly.

  > Unlike PuTTYcyg, MinTTY discards PuTTY's networking
    functions, which are already convered by Cygwin's OpenSSH and
    telnet packages. This results in simpler configuration, a
    leaner interface and small code size. MinTTY's most obvious
    difference to rxvt is its native Windows interface and
    configuration dialog.

* Files, Binaries, Help Sources

  > Updates and source code are available at:

     http://code.google.com/p/mintty.

  > MinTTY discussion group at:

    http://groups.google.com/group/mintty-discuss

* Credits/License

  MinTTY is copyright 2008-09 Andy Koppe.

  This program is distributed in the hope that it will be useful,
  but without any warranty; without even the implied warranty
  merchantability or fitness for a particular purpose. It is
  licensed under the terms of the GNU General Public License
  version 3 or later.

  MinTTY is based on PuTTY version 0.60 by Simon Tatham and
  contributors, available from
  ftp://ftp.chiark.greenend.org.uk/users/sgtatham/putty-0.60. Big
  thanks to everyone involved. Thanks also to KDE's Oxygen team
  for the program icon.

* Environment

  > Should work on Windows 2000 and upwards, although so far it
    has been tested on XP and Vista (32b & 64b) only.

* Installation/Program Configuration

  > MinTTY requires Cygwin, so Windows needs to be able to find
    the Cygwin DLL (cygwin1.dll) when starting mintty.exe. There
    are several ways to ensure this:

    = Start it from within an existing Cygwin session.

    = Place mintty.exe alongside cygwin1.dll in the Cygwin /bin
      directory and start it from there.

    = Add the Cygwin bin directory (normally C:\cygwin\bin) to
      the Windows PATH variable, which can be found under
      'Environment Variables' on the 'Advanced' tab of the System
      Properties. This is a good idea anyway, as it makes all the
      Cygwin commands available from the Windows 'Command Prompt'
      and 'Run...' dialog.

    = Create a shortcut to mintty.exe with the working directory
      set to the Cygwin bin directory. The create_shortcut.js
      script will do this for you.

  > Windows Shortcuts

    = Can have arguments too, which have to be listed after the
      program location in the 'Target:' box of their properties.
      This can be very useful with MinTTY, for instance for
      creating icons for 'ssh' sessions or your favourite editor.

    = To invoke 'bash' within mintty as a login/interactive shell
      (e.g., as a Win shortcut):

      mintty bash -li

* CLI Options/Arguments

  > --version -- print version

  > --help -- print usage information.

  > --config -- By default, MinTTY will store its configuration
      into a file called .minttyrc in your Cygwin home ('~')
      directory. This can be overridden with the --config command
      line option.

  > Any other command line arguments are interpreted as the
    command to execute in the terminal session. If no command is
    given, MinTTY will look up the current users default shell in
    /etc/passwd. If that is not set, it will run /bin/sh.

  > 'mintty' runs synchronous to the shell it's invoked from.
    Therefore if running from a batch file (like 'cygwin.bat'):

    start mintty bash --login -i

    will allow the batch file that invokes 'mintty' to terminate
    while the invoking terminal session continues.

* Interactive configuration

  > Full screen mode/Sized screen mode available from Title Bar
    Right Icons

  > Options Menu Hierarchy:

    = Options menu is accessible through Title Bar, left icon,
      left click.

    = Or, is accessible from the keyboard: <ALT><SPACE>o
                                           <MENU>o
  > Options Hierarchy

      Window
        # Columns
        # Rows
        ... Size information is automatically input to these
        fields when a window is resized using the mouse cursor
        and the lower left corner of the terminal window. Also, a
        pop-up box above the left corner of the title bar list
        what the new sizing is ...
        Transparency
          Off
          Low
          Medium
          High
        Disable transparency when active
        Show scrollbar
        Close on <Alt><F4>
      Looks
        Colors
          Foreground
          Background
          Cursor
        Show bold text as bright
        Allow text blinking
        Cursor
          Block
          Line
          Underline
        Enable Cursor blinking
      Font
        Select [font name and size]
          ... Default font point size is 10; be sure to pick
          fixed pitch font ...
        Smoothing
          System Default
          Antialiased
          Non-Antialiased
          Clear Type
        Codepage
          ... all Windows/int'l choices ...
      Keys
        Key Codes
          Backspace
            ^H
            ^?
          Escape
            ^[
            ^\
        Control key on its own sends ^[
        Modifier key for scrolling
          Shift
          Ctrl
          Alt
      Mouse
        Right click action
          Show Menu
          Extend
            [Use the right click for extending the text
            selection, X style. <Shift><left-click>, Win
            standard, always extends.]
          Paste
        Copy on select
        Application mouse mode
          [The mouse pointer  changed according to application
          mouse mode and override key.]
          Default click target
            Application
            Window
          Modifier key for overriding default
            Shift
            Ctrl
            Alt
      Output
        Printer
          None
          ... Windows available printers ...
        Bell
          Action
            None
            System sound
            Flash window
          Taskbar indication
            Disabled
            Steady
            Blinking

  > Alternatively, the config file,  '~/.minttyrc' can be edited directly.

    = Here's an example '.minttyrc' file:

      Columns=140
      Rows=42
      Transparency=3
      OpaqueWhenFocused=1
      Scrollbar=1
      CloseOnAltF4=1
      BoldAsBright=1
      AllowBlinking=1
      CursorType=2
      CursorBlinks=1
      FontIsBold=0
      FontHeight=14
      FontCharset=0
      FontQuality=0
      BackspaceSendsDEL=0
      EscapeSendsFS=0
      AltSendsESC=0
      ScrollMod=1
      RightClickAction=0
      CopyOnSelect=1
      ClickTargetsApp=1
      ClickTargetMod=1
      BellType=1
      BellIndication=2
      Font=Consolas
      Codepage=ISO-8859-1:1998 (Latin-1, West Europe)
      Printer=
      ForegroundColour=0,255,255
      BackgroundColour=0,0,32
      CursorColour=255,0,0

* Invoking 'mintty'

  > MinTTY's current behaviour is the same as rxvt's and xterm's,
    and therefore it makes sense not to execute the profile when
    starting a new terminal from within an existing session using
    just 'rxvt &' or 'mintty &'.

  > To invoke 'bash' within mintty as a login/interactive shell
    (e.g., as a Win shortcut):

      mintty bash -li

  > 'mintty' runs synchronous to the shell it's invoked from.
     Therefore if running from a batch file (like 'cygwin.bat'):

       start mintty bash --login -i

     will allow the batch file that invokes 'mintty' to terminate
     while the invoking terminal session continues.

* Rodentology

  > Mousewheel events can be sent as arrow keys. (This allows
    mousewheel scrolling e.g. in less.)

    When on the alternate screen and not in application mouse mode,
    mousewheel-up/down sends arrow-up/down combined with the scroll
    modifier configured under Keys, so with the default Shift you
    get ^[[1;2A and ^[[1;2B. (Replace the 2 with 3 for Alt or 5 for
    Ctrl).

    @@ What "alternate screen"? @@

    The thinking behind that is that this replaces the terminal
    scrollback when on the alternate screen, and that plain
    arrows mean cursor movement rather than scrolling. And a word
    of warning: the feature doesn't work in Vista when the
    scrollbar is shown. Looks like the inactive scrollbar is
    swallowing the mousewheel events.

  > Activate mousewheel scrolling in 'less' with the following two
    lines in your .lesskey file. Don't forget to run 'lesskey' to
    compile it into less's internal format.

    \eO1;2A back-line
    \eO1;2B forw-line

    BTW, it's 'O' rather than '[' here, because 'less' switches
    into "application cursor key" mode. (Yep, the world of
    terminals is full of fascinating yet strangely pointless
    details like that.)

* Terminal definition for 'mintty' -- termcap/terminfo

  > There is none!

  > Options to be used in profile (?):

    TERM=cygwin
    TERM=xterm

  > This will tell you what you've got/possible:

    $ set | grep TERM

  > Comments

    The proper GNUIsh thing to do would be to set TERM to
    "mintty", but that would require 'termcap' and 'terminfo'
    entries. I guess that might be worth considering for a MinTTY
    package, although iirc KDE's Konsole and GNOME's terminal
    also just set it to "xterm", because like MinTTY they aim to
    be compatible with (the default config of) xterm. Would make
    life easier for everyone to settle on that as a standard.

* Interactive Use

  > Scrollback buffer.

    = Not currently an option.

    = Arbitrarily fixed it at 16 KB.

  > Copy & Paste

    = Middle-click paste is always available
    = Copy-on-select
    = Right-click extend select can be enabled on the Mouse page of
      the options.
    = File drag and drop pastes in a Win32 path.
    = Pasting of multiple lines into apps like 'vim' works properly.

  > Options

    = Available via

      + <SHIFT>-<RIGHT>-<CLICK> on screen of virtual terminal window
      + <RIGHT>-<CLICK> on Windows context menu key
      + Right-click on Title Bar

  > Keys

    = <F1> to <F4> send xterm-compatible VT220-style keycodes

    = <ALT>-<F4> closes mintty window, but can be disabled from
      Options menu

    = Characters can be entered via Windows
      <Alt>-<NUMPAD_decimal_number> codes

      + Extending on the standard Windows behavior, codepoints
        beyond 255 are supported and octal codes can be entered
        by typing zero as the first digit.

* Bugs / Confusions

  > Alternate Screen

    = Is there an alternate screen toggle in 'mintty' as there is
      in 'xterm'?

    = How do you invoke it?

  > <CTRL>-<LEFT-ARROW>/CTRL>-<RIGHT_ARROW> does not appear to
    work to move back forward one word on command line. How do
    you fix this?

--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Problem reports:       http://cygwin.com/problems.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]