'othereditor' help

Name:	othereditor
Version:	0.1
Last update:	2021-05-21 14:43:29

This file documents the command line tool othereditor provided by Alpha. This tool is meant exclusively to enable synchronization between a TeX file and a pdf file when you use the TeXShop front end to typeset your LaTeX documents. This means that you can use Alpha as an external editor with TeXShop: each time TeXShop needs to jump to a given location in your TeX document or to display an error in the log file, it will open the relevant files at the appropriate location using Alpha.
This works with TexShop version 4.24 or greater.
If you are looking for a command line tool that lets you edit files with Alpha from a Terminal window or from a shell script, see the following tools:

alphaed to quickly edit one or several files with Alpha.
alphac to edit a file in Alpha at a given line, in a given mode and encoding.
ralpha to edit in Alpha a file located on a remote server through ssh.

Usage

The script can be found inside the application bundle in the $APPLICATION/Contents/Resources/Libraries/Extras 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.
The general syntax of this script is:

othereditor ?-d? linespec file
othereditor [-h|-v]

The command supports the following options:

-d	print debugging information
-h	print help
-v	print version

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.

Integration with TeXShop

In order to enable synchronization between Alpha and TeXShop so that TeXShop uses Alpha as an external editor and can go back to the source file when necessary, you must perform the following tasks:

configure TeXShop to use an external editor by selecting the Configure for External Editor preference found in the Source panel of the of TeXShop's preferences.
execute the following command from a Terminal window in order to enable synchronization with an external editor
```
defaults write TeXShop OtherEditorSync YES
```
This is a TeXShop hidden preference and there is currently no other way to set it.
copy the othereditor script to the /usr/local/bin directory. TexShop's internal mechanism expects this script to be named exactly like this and to be located in this directory. Alternatively you can make a soft link called othereditor in this directory pointing to the real script. In both cases, you need admin privileges to do this. Also make sure that the script has the executable bit set.

That's all there is to it. Now, if an error occurs during typesetting, you may click on the Goto Error button of TeXShop's console to go back to the source file in Alpha at the line where the error was encountered.

Known problems

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

License and Disclaimer

Copyright (c) 2019-2021, Bernard Desgraupes.
All rights reserved.
The othereditor 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 Bernard Desgraupes 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 BERNARD DESGRAUPES 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.