FMcalc – Calculations in FrameMaker

FMcalc is an ExtendScript package which provides functions for calculations in FrameMaker:

• FMcalc uses two marker types: #calc and #series.
• Results can be stored in variables, which can be used in both types of markers.
• Results from the #calc marker can be inserted immediately after the marker in the document.
• The formulas can contain mathematical constructs (#calc: of significant complexity).
• With #series markers nearly arbitrary numbering becomes possible.
• Both marker types can be created with building blocks to avoid typing errors.
• Markers can be evaluated individually or in 'batch mode' in a document or in a book.
• The script adapts its UI language to the FM-UI-language (de, en, fr).

Appreciation: This script would not have been possible without the generous help form the FrameMaker ExtendScript community. In particular I want to thank Klaus Göbel, Jang F.M. Graat, Jongware, Rick Quatro, Russ Ward and Markus Wiedenmaier.

Note: This page does not describe all features of FMcalc. See the full documentation (pdf).

Side Note: If you are looking for a more Excel like interface of the calculations in FrameMaker tables, get in contact with Jang F.M. Graat. With his FrameMaker circus he makes FrameMaker jump through hoops: Frexels is a scripted solution mimicking Excel in FrameMaker tables for the most used functions (+ - * / and SUM) [2019-11-16].

Marker types
Functions of the script
Document settings
Downloading and installing FMcalc

Marker types

#calc markers define formulas and how the results is stored and formatted

Marker content	Remarks
#xpos = #length * Cos(#alpha * @PI)	There are a large number of functions (Cos) and constants (@PI) avialable via building blocks to avoid typos.
#something = Sin(Sqrt(@PI/3)) {E5}	Optional formatting information is in {}. I (integer), Jn (Integer with leading zeroes), Fn (decimal), En (scientific) {E5} will create something like -1.23456×10-5 (5 decimal figures).
= #VAT * Prod(Left) "xmpl 02";	Valid only in table cell (referring to all cells to the left of the current). No resulting variable is defined: output is directly after the marker. Comments can be anywhere and are enclosed in straight quotes.
#total = Sum (Above) * (1 + #VAT)	Valid only in a table cell. It refers to all cells above the current cell. Result is stored in FM variable #total.

• In tables formulas can use absolute cell addressing or relative cell addressing.
• A variable my receive a list of values (vector), which can be passed to functions such as Sum, Prod or SumProd.
• Evaluated (calculated) results can be stored in a FrameMaker variable or directly placed after the marker.
• When the marker is within a table cell, input can come from one or more cells around the current cell (relative addressing) or from a particular cell (absolute addressing).
• Output (inserted into the document) can be highlighted to indicate that is a calculated value.
• Real values can be formatted with a defined number of decimals (-12.123), in scientific notation (1.27×10^-5)
• Integer values can be formatted as such (17), with leading zeroes (0017) or as roman numerals (XVII, xvii).
• The decimal separator and the thousands separator can be defined individually for each document (all options are defined on a reference page).

#series markers are an "extension to automatic numbering"

The idea for series came from the demand of 'decrementing counters', which is not possible with auto-number in paragraphs.. The result of series markers is always inserted in the document.

Marker content	Generated series in text with appropriate character format
Series= reverse_1; Scheme= Numeric; Start= 18.5; Incr= -4.1; Decimals= 2;	18.50, 14.40, 10.30, 6.20, 2.10, -2.00, -6.10, -10.20, …
Series = series_2; Scheme = ROMAN; Start = 5; Incr = -1;	V, IV, III, II, I, NaN, NaN (NaN stands for Not a Number: negative values are not defined for roman numerals).
Series= LeadingZeros; Scheme= Num000; Start= 15; Incr= -6;	0015, 0009, 0003, NaN (NaN stands for Not a Number: negative values are not defined).
Series = zeiten; Scheme = OldTimesDE; Start = 1; Incr = 1	in alten zeiten This starts the textual numbering. früher And here it is continued. vor kurzem Shortly ago. heute Today.
Series = hebrew_rainbow; Scheme = קשת;	אדום Hebrew rainbow, 1st item (red) כתום Hebrew rainbow, 2nd item (orange) צהוב Hebrew rainbow, 3rd item (yellow)

• The definitions are stored in markers of type #series.
• To a series with name seriesName a corresponding character format seriesName exists.
• Text which will receive the series items uses this character format (thus being replaced by the generated series items). This character format must exist in the catalogue (or it will be created with "All AsIs").
• Numbering (placing the series) is performed in the text flow after the #series marker.
• The text which shall receive the first series item must be marked: It must contain the functional character Optional Hyphen (\x05).
• The series evaluation is stopped at the end of the document. The same series can be started again by a marked text element. It is possible to nest series of different name.
• The items for textual series (scheme = AName) is defined in dialog Document Settings.

Functions of the script

• The script installs a menu:
  

  Document menu	Book menu

• Documentation is available also via Help button in the panels.
• For both #calc markers and #series markers a panel (which stays open during manipulation in a document) allows all operations on these markers:
  - Create marker contents from building blocks and free editing.
  - Syntax check this marker before insertion at current location.
  - Navigate through existing markers (to first, previous etc.).
  - Insertion/update or evaluation of a marker is only possible if no syntax errors are reported.
  - The evaluation process may also issue error messages.
  

  Handle #calc markers	Handle #series markers

Document settings

This dialogue has tabs to set the various options for a document. These are stored on the reference page FMcalc.

• Locations are the building blocks for cell references.
• Formats are the building blocks for the output formats.
• Text schemes define the items for the textual schemes.
• Document settings define the decimal separator or whether thousands should be separated. Also debugging is set here.

Downloading and installing FMcalc

Attention: Windows Defender may react to this installation with a virus warning. This is a false positive. You may check this with an upload to Virustotal
Please consult the complete documentation for instructions how to avoid intervention by Windows Defender. This most useful feature has the quirk to quarantine most compiled AHK scripts.

Note: All software from D+DD is Donationware - if you find it helpful for your work, think about supporting also my work.

1. Download the script file

FM version	Date	Version	Installation file(s)	Latest changes
11 and later	2017-03-21	1.0	Inst-FMcalc.zip	First issue of FMcalc
	2017-11-03	1.1		Corrections: documentation; handling of non-numeric input from file; handling of boolean document settings.
	2017-12-30	1.2		Additional function Arc (deg, min, sec). FMcalc_OpenPdf.exe renamed to FMxxx_OpenPdf.exe
	2018-03-09	1.3		Installation routine, name change for ZIP to Inst-FMcalc.zip Changed project structure and documentation Bug hindering use of source files corrected. Keyboard short cut for documentation changed to ESC q m d
	2018-10-29	1.4		Corrections: Thousands separator; Roman numerals; documentation Additional function Median
	2019-09-16	1.5		Corrections: Some math functions (e.g. Sum) did not skip NaN values; Errors on opening new document; Colour definition for character format calculated independently of UI language. Additional functions StdDev (standard deviation), MeanA (arithmetic mean), MeanG (geometric mean) and MeanH (harmonic mean) and Median. For data input (from table or file) the decimal separator can now be period or comma. (Within FMcal the decimal separator (in marker text) is always a period. For output presention the character can be defined.) Constants adapted to SI-definitions 2018-11
	2021-09-15	2.0		Localisation changed to XML method Notify process reduced to one trigger → in rare cases the Refresh button must be used after change of active document Allow definition of new formats {r} and {R} in Document Settings panel Correction for argument lists containing zeroes (created error in evaluation). Correction for NaN results (no error message, no output) Documentation change
	2022-06-02	2.1		Documentation updated with detailed installation process and remark concerning Windows Defender. Errors corrected.
	2023-07-19	2.2		Corrections: Reference Error: CreateMatrix is not a function

2. Before installing a new (updated) version, uninstall the current version: start the installation program from the short cut in the Start-menu > D+DD. Then use the Un-Install button.
3. UnZip the file to the desktop (you get a file and a directory).
4. Execute the file PrepareInstallation.exe (run as Administrator)
   The language of the installation dialogues adapts to the UI language of your current FM installation (de, en, fr).
   This program modifies some values in the file InstallThis\config.ini.
   
5. The last six FM-versions present in your %appdata%/Adobe/FrameMaker/ are listed in the dialogue (on your system there may be only one).
   
   
6. Select the FM-version for which you want to install FMmarkers.
7. Use Continue. This opens the installation program:
   
8. Select the appropriate option(s):
• Use the first option to start the script automatically at FM-start.
• Use the second option if you wish to start the script on demand from a trusted source. You can define the script in File > Scripts … > Cataloge (Script Library) as Favourite: use the Add button and navigate to My Documents\Adobe Scripts\FMcalc\FMcalc.jsx
9. With Install the script and associated files will be transferred into the relevant locations.
10. A message indicates the end of the installation. The desktop icons will be removed.

Uninstall the script

To uninstall the script, start the installation program from the short cut in the Start-menu > D+DD. Then use the Un-Install button.

This removes the script only from the locations defined in the options. You can later use the installation program again.

To get completely rid of the script you need to remove the following in addition to the un-installation:

• The short cut in the start menu
• Directory %appdata%\D+DD\FMcalc

Caveat

Any software from D+DD is provided by the author and contributor "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.