'alphac' help

Name:	alphac
Version:	5.0
Last update:	2021-05-21 14:43:29

This file documents the command line tool alphac provided by Alpha. This tool lets you edit files or open new windows in Alpha from a Terminal window or from a shell script and lets you also set the selection, the mode and the encoding. Technically it communicates with Alpha via a socket as explained in the Alpha Server Help.
For a simple tool that just opens one or several files in Alpha, see alphaed. To edit a file located on a remote server through an ssh tunnel, see ralpha.

Usage

The script can be found inside the application bundle in the $APPLICATION/Contents/Resources directory. Here $APPLICATION designates the path of the Alpha application (click here to place this path in the Clipboard).
It is also distributed with Alpha's ExtraTools: click here to download the ExtraTools.
You may copy this script to a location on your shell PATH to make it more easily accessible or just make a soft link pointing to it.
The general syntax of this script can take two forms:

alphac ?options? ?linespec? ?--? file [file+]
alphac ?options? ?linespec? -c ?--? name [string|-]

The first form is used to open one or several files. This is useful if you use alphac as a command line editor. See the Command line editor section.
The second form, with the -c argument, is used to create a new window in Alpha. This is equivalent to the proc [new] defined in AlphaTcl. In this form, the last argument may be

one or several strings which will be concatenated to form the initial contents of the window
a dash '-' to read the initial contents from standard input. This allows to use alphac in pipes.

Both forms of the command support the following options:

-a	use AppleScript (bypass the AlphaServer)
-c	create a new window
-d	print debugging information
-e enc	encoding (default is UTF-8)
-h	print help
-m str	mode
-p num	port number
-s	print Alpha Server's port
-u str	user name
-v	verbose
-V	print version
-w	wait
--	end of options

The optional -w (or -wait) argument makes alphac wait for the edited/created windows to be closed.
The linespec argument lets you specify a region to hilite. The format is:

+line1[.col1][,line2[.col2]]

If .col1 is omitted, the selection will start at the beginning of line1. If .col2 is omitted, the selection will stop after the end of line2. If the second part of the linespec (line2[.col2]) is omitted, then it is equal to the first one. The linespec argument applies to the last opened file.
If the script fails to connect to the Alpha Server, it resorts to sending its editing request to Alpha via an AppleScript. The -a option allows you to force the use of AppleScript (that is to say by-pass the Alpha Server).
See the Examples section below.

Command line editor

The alphac script also allows Alpha to serve as EDITOR or TEXEDIT to open a file at a given line.
Setting the environment variable TEXEDIT in a terminal window to

$APPLICATION/Contents/Resources/alphac +%d %s

will make the teTeX versions of tex (and pdftex) use Alpha when "e" is typed at an error prompt. In this instruction, you must replace $APPLICATION by the path of the Alpha application as explained at the beginning of this file.
alphac may also be used as the system editor by setting the EDITOR environment variable to

$APPLICATION/Contents/Resources/alphac -w

The -w option will make alphac wait until you close the window of the edited file, letting the system know that you have finished.

Advanced options

The -p option lets you specify the port number on which the Alpha Server is listening. Normally you would not have to use it because alphac attempts to find it automatically. For more information, see the Alpha Server Help.
The -u option lets you specify the name of the user who launched Alpha in case it differs from the user executing the script. This is used by alphac to find the file containing the port number.
The -s option reports the number of the port the Alpha Server is listening on and exits.
The -v and -d options are meant for developers. They provide a more verbose output and debugging information respectively.

Examples

To edit a file:

> alphac /path/to/some/file

To edit a file in TeX mode and in macRoman encoding:

> alphac -m TeX -e macRoman /path/to/some/file

To edit a file and select line 30:

> alphac +30 /path/to/some/file

To edit a file and select lines 30 to 34:

> alphac +30,34 /path/to/some/file

To edit a file and select from line 30 column 5 to line 34 column 10:

> alphac +30.5,34.10 /path/to/some/file

To open a file and wait until it is closed:

> alphac -w /path/to/some/file

To create a new window called somename:

> alphac -c somename

To create a new window with some text:

> alphac -c somename "foo bar baz"

To create a new window with the contents of another file, use any of the following commands:

> alphac -c somename - < /some/other/file
> cat /some/other/file | alphac -c somename -

Known problems

Please report any problem or bug you encounter to Alpha's Bug Tracker.

License and Disclaimer

Copyright (c) 2003-2021, Frédéric Boulanger.
All rights reserved.
The alphac package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Frédéric Boulanger nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL FRÉDÉRIC BOULANGER BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.