ConvertAll ReadMe

# ReadMe file for ConvertAll

## a unit conversion program

Written by Doug Bell
Version 0.7.3
October 15, 2017

## Contents

- Background
- Features
- Legal Issues
- System Requirements
  - Linux
  - Windows
- Installation
  - Linux
  - Windows
- Using ConvertAll
  - Basics
  - Combining Units
  - Non-Linear Conversions
  - Shortcuts
  - Options
  - Command Line Usage
- Revision History
- Questions, Comments, Criticisms?

## Background

Why write another unit converter? There are plenty of them out there. Well, I couldn't find one that worked quite the way I wanted.

With ConvertAll, you can combine the units any way you want. If you want to convert from inches per decade, that's fine. Or from meter-pounds. Or from cubic nautical miles. The units don't have to make sense to anyone else.

Since I'm not in the software business, I'm making this program free for anyone to use, distribute and modify, as long as it is not incorporated into any proprietary programs. If you like the software, feel free to let others know about it. And let me know what you think - my email address is doug101 AT bellz DOT org

## Features

- The base units for conversion may be either typed (with auto-completion) or selected from a list.
- As a unit is typed, the unit list is automatically filtered to show only units with matching words.
- In general, either a unit's full name or its abbreviation can be used.
- Units may be combined with the "*" and "/" operators.
- Units may be raised to powers (squared, cubed, etc.) with the "^" operator.
- Units in the denominator may be grouped with parenthesis.
- Units with non-linear scales, such as temperature, can also be converted.
- Recently used unit combinations may be picked from a menu.
- Numbers may be entered on either the "From" or the "To" units side, for conversions in both directions.
- Basic mathematical expressions may be entered in place of numbers.
- Options control the formatting of numerical results.
- The unit data includes over 500 units.
- The format of the unit data file makes it easy to add additional units.
- Command line options are available to do conversions without the GUI.
- The user interface and the unit data are available in English, French, German, Russian and Spanish.

## Legal Issues

ConvertAll is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either Version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY. See the `LICENSE` file provided with this program for more information.

## System Requirements

### Linux

ConvertAll requires the following libraries:

- Python (Version 3.4 or higher)
- Qt (Version 5.4 or higher - see Qt Project for more information)
- PyQt (Version 5.4 or higher - see Riverbank for more information)

### Windows

Using the files provided in the binary distribution, ConvertAll should run on any computer running Windows XP, Vista, 7, 8 or 10.

## Installation

### Linux

Extract the source files from the convertall tar file, then change to the `ConvertAll` directory in a terminal. For a basic installation, simply execute the following command as root: `python install.py`

If your distribution defaults to Python 2.x, you may need to substitute `python3` for `python` in these commands.

To see all install options, use: `python install.py -h`. To install ConvertAll with a different prefix (the default is `/usr/local`), use: `python install.py -p /prefix/path`

### Windows

To install for all users, execute the `ConvertAll-x.x.x-install-all.exe` file. Administrator permissions are required.

To install for a single user (administrator rights are not required), execute the `ConvertAll-x.x.x-install-user.exe` file.

For a portable install, execute the `ConvertAll-x.x.x-install-user.exe` file, uncheck the shortcuts and uninstaller tasks, and check the portable config task.

## Using ConvertAll

### Basics

Simply type a unit name in the "From Unit" edit window. As you type, the list below the window will be filtered to show only matching units. Matching unit names contain words starting with the words that are typed. Either type the complete unit name/abbreviation or hit the return key to use the unit highlighted (blue letters) in the list. Of course, clicking with the mouse on a unit in the list will also add the unit to the edit window. You may also use the up and down arrow keys to highlight nearby units from the list.

Repeat the unit selection in the "To Unit" edit window. When done, if the units are compatible, the numeric edit windows below the unit lists will activate. A number may be entered into either numeric window and the other window will display the conversion result.

### Combining Units

The real strength of ConvertAll lies in its ability to combine multiple units. Simply type the unit names with an '*' or a '/' between them. This allows the entry of units such as "ft * lbf" or "mi / hr". The '^' symbol may be used for exponents, such as "ft^3" or "ft * lbm / sec^2". Negative exponents are allowed for units such as "sec^-1" (per second), but may switch the multiplication or division symbol ("ft * sec^-2" becomes "ft / sec^2").

Multiplication and division have the same precedence, so they are evaluated left-to-right. Parenthesis may also be used to group units in the denominator. So "m / sec / kg" can also be entered as "m / (sec * kg)". The version with parenthesis is probably less confusing.

The buttons below the unit text boxes can also be used to add operators to the active unit that is closest to the cursor. The Square and Cube buttons will add or replace exponents. The Multiply and Divide buttons will add "*" and "/" operators.

Similarly, clicking on a unit from the list generally replaces the unit nearest the cursor.

The "Clear Unit" button below the operator buttons may be used to empty the unit edit window to allow a new unit to be entered.

The "Filter List" button can be used to show only one type of unit in the list. Note that this doesn't show units that could be combined to form a type.

### Non-Linear Conversions

The conversion of some units is non-linear. Examples of these include the Fahrenheit and Celsius temperature scales (due to an offset zero point) and the American Wire Gauge (logarithmic). The non-linear units are labeled as such in the comments column.

These units can be converted only when they are not combined with other units or used with an exponential operator. Otherwise the conversion would not be meaningful.

### Shortcuts

When typing unit names, spaces are ignored, so they may be skipped. It is also generally ignored if a plural form of the unit name is typed. For squared and cubed units (positive exponents of 2 or 3) the "^" symbol does not need to be typed.

When a partially typed unit is highlighted in the list (blue lettering), hitting enter will complete the name. The up an ddown arrow keys can be used to highlight nearby units in the list prior to hitting enter. The unit closet to the cursor will be replaced.

The "Recent Unit" button opens a menu of recently used units and unit combinations. The current unit combination is replaced with any selections from this menu.

The tab key can be used to cycle between the "From" and "To" unit test boxes and the "From" and "To" number editors.

The number to be converted may be entered in either the "From" or "To" unit side. Standard or scientific notation may be used, or an expression including the normal math operators (+, -, *, /, **) and parenthesis may be entered.

### Options

The "Options..." button allows for changing several default settings. These settings are automatically stored so that ConvertAll will re-start with the settings last used.

The first options control the display of numerical results, including the use of scientific notation and the number of decimal places. Be cautious about setting the number of decimal places to a low value, which can result in a significant loss of accuracy. Six places or higher is recommended (eight is the default).

There is an option to set the number of recent units to be saved. Setting it to zero will disable the Recent Unit buttons. Another option will automatically load the most recent previous units at startup.

There are options to hide the operator text buttons (first row), and the unit buttons (second row). These can be hidden to save space if the keyboard will be used to enter the operators.

Buttons are also included on the options dialog to control the colors of the text fields.

### Command Line Usage

Conversions may be done from the command line (Linux or DOS console) without invoking the graphical interface. Enter the command ("convertall" on Linux, "convertall_dos" from the Windows binary), the number, the from unit and the to unit (separated by spaces) to do the conversion. Unit names containing spaces should be surrounded by quotes. Or, to be prompted for each unit entry, use the "-i" option ("convertall -i" on Linux, "convertall_dos -i" from Windows).

After the conversion is done, ConvertAll will prompt for a new number to do the same conversion. Or "n" can be entered to start a new conversion, "r" to reverse the conversion or "q" to quit.

For a more detailed list of options, use the "-h" option ("convertall -h" on Linux, "convertall_dos -h" on Windows).

## Revision History

### October 15, 2017 - Release 0.7.3

Updates:
- Added the boiler horsepower unit.

Bug Fixes:
- Fixed a crash if a zero value is entered when the engineering notation option is enabled.
- Fixed an initialization issue that caused problems with some versions of Python.

### February 20, 2017 - Release 0.7.2

Bug Fixes:
- Fix a crash due to an overflow error whem typing part of an exponent in the denominator of the second unit.
- Avoid flipping the preceeding operator between multiplication and division as a unit exponent of 0.5 is typed.

### February 4, 2017 - Release 0.7.1 (Linux only)

Bug Fixes:
- Replaced outdated dependency checks in the Linux installer - it now runs checks for Qt5 libraries.
- Fixed a timing issue in the Linux installer so that byte-compiled files do not have old timestamps.

### January 8, 2017 - Release 0.7.0

New Features:
- Dual unit lists have been replaced with a single list that works with the active unit line editor.
- As a unit is typed, the listing of units is reduced to only include units that match the typed words.
- The unit list can be sorted by clicking on the column headings.
- The unit list can be filtered to only show units of a certain type.
- Simple unit exponents (positive 2 and 3) can be typed with just the number (leaving out the "^" character).
- Now permits decimals to be entered for unit exponents, supporting roots of units.
- ConvertAll has been ported from the Qt4 to the Qt5 library.

Updates:
- Since the main unit list can now be searched, sorted and filtered, the Unit Finder Dialog has been removed.
- Added the British Std Wire Gauge non-linear unit.
- Added the ton imnperial unit.
- Added the cable nautical unit.
- Added the MBH (1000 Btu/hr) unit.
- Added Cape foot, square perch and rood units.

Bug Fixes:
- Corrected some unit definitions in the French translation, including avogadro's number, lambert, poise and the gravitational constant.

### September 10, 2015 - Release 0.6.1

New Features:
- Added an option to output results in engineering notation (a version of scientific notation with exponents divisible by three).
- A Russian translation was added. Thanks to vantu5z for translating.

Updates:
- Added the dram mass unit.
- Added the fluid dram and the minim volume units, in both US and Imperial versions.
- Added the smoot length unit.
- Added "dm" as an abbreviation for the decimeter length unit.
- Added "avoirdupois" to the comment column for applicable mass and weight units.
- Added "fresh water" to the comment column for applicable depth-based pressure units.
- The German translation was updated. Thanks to Thomas Helmke for translating.
- Added some MSVC runtime DLL files to the Windows installers to avoid problems on PCs that do not already have them.
- Clarified some dependency checker error messages in the Linux installer.

Bug Fixes:
- Fixed an error in the unit data formula for the AWG area unit.
- Changed the value of the caliber unit to be equivalent to inches (typical written usage), not hundredths of an inch (typical verbal usage).

### February 1, 2014 - Release 0.6.0

New Features:
- ConvertAll has been ported from Python 2 to Python 3. This porting includes some code cleanup.
- Added an option to automatically load the last used units at startup.
- Added an introductory tip dialog box that explains combined units. There is also an option to hide this dialog.
- There is an additional Windows installer for users without administrator rights and for portable installations.
- Added a Windows installer option to add a config file to the program's directory for portable installations. If that file is present, no config files will be written to users' directories.

Updates:
- The Windows binaries are built using more recent Python, Qt and PyQt libraries.
- The user interface and unit data language translations are now included in the main installation files.
- Added the long ton unit (Imperial version of the ton).
- Added the kilopond unit as a synonym of kilogram-force.
- Added the micron of Hg pressure unit.
- Added the lunar distance (LD) astronomical distance unit.
- Added the rack unit (height of an electrical rack).
- Added the versta Russian length unit.

Bug Fixes:
- Fixed the operation of the "Clear" button in the Unit Finder dialog.
- Fixed a problem with the definition of the BTU unit in the French translation.

### November 2, 2011 - Release 0.5.2

Updates:
- Added the microliter volume unit.
- Added the galileo acceleration unit.
- Added the stremma land area unit.

Bug Fixes:
- Changed the method of identifying a "unitless" portion of a unit to avoid falsely reporting incompatibility between some units when using language translations.

### March 31, 2011 - Release 0.5.1

Updates:
- Added the link length unit.
- Added US survey variations of the mile and chain length units.
- Added the centigray radiation dose unit.
- Use DOS newline characters in the Windows version of the unit data file for easier editing by users.

Bug Fixes:
- Fixed incorrect definition of the rad radiation dose unit (it was off by a factor of 10).

### May 2, 2010 - Translation Update 0.5.0b

Updates:
- Added a Spanish translation. The French and German translations remain unchanged.

### April 23, 2010 - Release 0.5.0

New Features:
- Multiplication and division operators now have the same precedence. In previous versions of ConvertAll, a series of units after a division symbol were assumed to be in the denominator. Now, a division operator only affects the unit (or the unit group in parenthesis) immediately after the operator.
- Parenthesis are now supported to group units in the denominator of a combined unit. For example, ""m / sec / kg" can also be entered as "m / (sec * kg)".
- "Recent Unit" buttons have been added that open a menu of recently used units and unit combinations. A unit selected from the menu will replace the current unit combination. There is also a new option dialog entry that controls the maximum length of this menu.

Updates:
- Added the tonne force metric force unit.
- Added hundredweight long and hundredweight short mass units.
- Added an American Wire Gauge (AWG) area unit in addition to the existing AWG diameter unit.
- Added the tonne oil equivalent and the tonne coal equivalent energy units.
- Added the ton refrigeration power unit.
- Added the darcy and millidarcy permeability units.
- French and German translations have been added for the user interface and the unit data. To use them, download and install the "convertall-i18n..." file for your platform (in addition to installing the standard ConvertAll package).

Bug Fixes:
- Fixed problems with running in the command line mode from Linux consoles without X11 present.

### September 24, 2009 - Release 0.4.3

New Features:
- Prepared ConvertAll for translation efforts by properly handling Unicode characters in unit data and by marking internal program strings for translation. Volunteers for translating ConvertAll into other languages are welcome.

Updates:
- Added solar mass and pennyweight mass units.
- Added therm and thermie energy units.
- Added gauss and maxwell magnetic units.
- Added the US survey foot length unit.
- Added the mpg imp mileage unit.
- Changed the value of the point unit from the old American point to the more modern desktop publishing point.

Bug Fixes:
- A critical QString conversion bug that caused ConvertAll to not run with the latest version of PyQt (4.5.4) was fixed.
- Command line quiet mode was fixed to avoid an interactive prompt when bad unit data is entered.

### May 28, 2008 - Release 0.4.2

Updates:
- Added the "liter per 100 km" unit for fuel consumption.

Bug Fixes:
- Changed the "mach" unit from 331.46 m/s to 340.29 m/s. It is now correct for STP conditions (15 degrees C). The previous value was for 0 degrees C.
- Fixed a bug that could hide messages about errors in a manually edited unit data file.

### January 22, 2008 - Release 0.4.1

New Features:
- An optional command line mode was added to do conversions without the graphical interface. Enter the command ("convertall"), the number, the from unit and the to unit (separated by spaces) to do the conversion. For a more detailed list of options, enter "convertall -h" on the command line.

Updates:
- The icon used for ConvertAll has been updated. Thanks to Ricardo Berlasso for the new artwork.
- Alternate units have been added for kilobyte, megabyte, etc., marked "IEC std". These convert using powers of 10, rather than powers of 2.
- Troy pounds and troy ounces have been added.
- Gigapascal, hectopascal and megabar have been added.
- Hogshead units for wine and beer have been added.
- The Swedish mil unit of distance has been added.
- The Thai rai and ngaan units of land area have been added.

### October 5, 2006 - Release 0.4.0

New Features:
- ConvertAll was ported to the Qt4 library. This involved a significant rewrite of the code. The previous versions used Qt3.x on Linux and Qt2.3 on Windows. Benefits include updated widgets and removal of the non-commercial license exception in Windows.

Updates:
- On Windows, the ConvertAll.ini file has been moved from the installation directory to a location under the "Documents and Settings" folder. This avoids problems on multi-user systems and for users with limited access rights.

### October 5, 2006 - Release 0.3.2

Updates:
- Added Imperial (UK) gallons, quarts, pints and fluid ounces.
- Added gigagram and teragram units.
- Added the pound-mole unit and clarified that the existing mole is a gram-mole.

### February 14, 2005 - Release 0.3.1

Updates:
- Added the decare unit for land area.
- The Linux installer has been updated to be more robust and give more install directory options.

Bug Fixes:
- The barn unit, used in particle physics, was corrected. It had been incorrectly listed as a length unit instead of an area unit.

### March 11, 2004 - Release 0.3.0

New Features:
- A unit finder window was added to allow the unit list to be filtered and searched.
- The size and position of the main and finder windows are now saved at exit.
- A new option allows the operator text entry buttons (x, /, ^2, ^3 and Clear Unit) to be hidden.
- An install program has been added for windows.

Bug Fixes:
- Fixed Linux install script problems with certain versions of Python.

### November 18, 2003 - Release 0.2.4

Updates:
- Keyboard shortcuts and tab-focus order for the main dialog have been improved.
- An install script was added for Linux and Unix systems.
- The windows build now uses Python version 2.3 and PyQt version 3.8.

### March 24, 2003 - Release 0.2.3

Updates:
- When an expression using division is entered for the number to be converted, floating point division is now used even if the entries are integers (Python 2.2 or greater only).
- Mouse wheels are now supported in the unit lists.
- Icon files are now provided with the distribution files.

### May 28, 2002 - Release 0.2.2a

Bug Fixes:
- A fix of the Windows binary only. Fixes major problems by upgrading the library version to PyQt 3.2.4.

### May 16, 2002 - Release 0.2.2

Updates:
- ConvertAll has been ported to Qt 3.x. It now works with both Qt 2.x and 3.x using the same source code.
- The help/readme file has been rewritten and now includes section links.
- The binaries for windows have been updated to Python 2.2 and PyQt 3.2 (but are still using Qt 2.3 Non-commercial).

### September 17, 2001 - Release 0.2.1

Bug Fixes:
- Some window captions and icons were corrected.
- A window maximizing bug was fixed.

### August 20, 2001 - Release 0.2.0

New Features:
- A major rewrite was done of the conversion engine.
- A new data file format makes it easier to add and verify units.
- The unit name and abbreviation are now listed separately for better sorting and searching.
- Entering of units has been improved by changing operator precedence, by ignoring spaces and plurals, and by changing the partial selection list highlight.
- An expression can now be used for the number to be converted.

Updates:
- Many additional units were added to the database.
- For MS Windows users, the binary files were upgraded to PyQt Version 2.5.

### August 10, 2001 - Release 0.1.1

New Features:
- Added color controls to the options dialog.

Updates:
- The convertall.ini file on windows was moved to the program directory.

Bug Fixes:
- Fixed problems with using the same unit twice in a combined unit.
- Fixed an occasional shutdown when auto-completing.
- Fixed a problem with the updating of the unit label.

### July 28, 2001 - Release 0.1.0

Initial release.

## Questions, Comments, Criticisms?

I can be contacted by email at: doug101 AT bellz DOT org
I welcome any feedback, including reports of any bugs you find. Also, you can periodically check back to www.bellz.org for any updates.