Marco: User Manual

Table of Contents

Introduction
What does Marco Do?
Who can use Marco?
What Units of Measure does Marco Use?
What is MathLib?
Getting Started
Installing Marco
Starting the Program
Beaming Marco
General Layout of Screens
Entering Information
Contect-Specific Help
Curves
Horizontal Curves
Vertical Curves
Center Line for Curves
Lines and Objects
Intersection
Proportion
Inverse
Center Line for Lines
Grading PI
Solvers
Area of a Polygon
Triangles
Angle Converter
Quadratic Formula Solver
Utility
Edit Points
Preferences
Manage Databases
Appendixes
Registration Information
Upgrades
Calculators
Frequently Asked Questions (FAQ)
Contacting the Author

What does Marco Do?

        Back to the Table of Contents

It acts like a specialty calculator that is geared towards surveyor's work. The software speeds up the planning process involved with field work, and can produce quick, accurate numbers in a pinch. It is much faster to turn on and smaller than a laptop, making it more convienient in odd situations. When the motors are running and contractors are standing around waiting for an answer to a problem, this program can get them back to work quickly.


Who can use Marco?

        Back to the Table of Contents

The software was designed to be as easy to use as possible. When compared to some of the specialty calculators on the market, this blows them away. The friendly prompts have descriptive explanations, and built-in help is available for every screen.

While designed for the field, people "in the office" use Marco for getting quick solutions to problems, where they used to use a calculator. Students studying surveying can also benefit from the program, and use it for class or possibly intern work. It is also possible that professional landscapers, architectual designers, and construction workers could use Marco for various applications in their fields.


What Units of Measure does Marco Use

        Back to the Table of Contents

The formulas that are built into Marco do not require a unit of measure to be used. The rule of thumb is that all lengths, coordinates, and values must be in the same unit. Therefore, if all information is entered in as feet, the answer will also be in feet.


What is MathLib?

        Back to the Table of Contents

In order to be very accurate, Marco uses MathLib for all of the complex math functions. MathLib provides IEEE-754 double precision math functions to Palm OS programs. MathLib is a shared library, which means that most calculators and other math-related programs will share its instructions instead of adding bulk to each program's size. This makes everything smaller in the long run.

If Marco was already installed on the handheld and if everything was working fine, MathLib does not need to be reinstalled. If you are installing Marco for the first time, MathLib might already be loaded on the device. I would suggest installing Marco only, and try to run it. If there is an error saying something like "Can't find MathLib", then just install MathLib. Once installed, MathLib will never need to be installed again, even if Marco or other programs are updated. Only if your memory is completely wiped out would it beed to be installed again.

If you need MathLib and another person who has it on their Palm is handy, you can use Marco to beam MathLib from one Palm to another. Tap on the menu button, then select Beam MathLib under the Marco menu.

You don't need to worry about damaging anything. If MathLib is not installed, Marco detects it and stops the program before any harm can be done. MathLib is available in a package with Marco from the download page. Additionally, you can download just the MathLib file from here (right-click and pick "Save As"), or you can get everything (including documentation and the source code) from this MathLib project on GitHub.

The reason that MathLib is used is for accuracy. Internally, Marco uses a 'double', which is a 32-bit floating point number. Palm OS doesn't have good math functions for doubles, so MathLib was created to fill the void. It is much more accurate than normal 'float' numbers. In my tests, it shows that doubles have an accuracy to 10 significant digits -- the first 10 numbers, not including the decimal point, starting from the left. These numbers are all displayed with 10 significant digits. Most people will not use all 10 digits, and Marco may not display all 10 digits (depending on how it is configured), but it is good to know that they are there.

  • 3.141592653
  • 32,167,398.92
  • 1024.123456

Additionally, Marco uses optimized math functions to minimize the amount of multiplications and divisions that are needed. With each multiplication or division, a tiny amount of precision is lost due to the way computers handle those arithmetic functions, and Marco strives to keep all numbers as accurate as possible.


Installing Marco

        Back to the Table of Contents

Just go to the download page and get the zip file with MathLib and documentation. Extract the archive on your computer and double click "marco.prc" to schedule it to be HotSync'd to the Palm. The next time you HotSync, your Palm will have Marco installed on it.

Alternately, Marco can be beamed to another person's Palm. See the beaming section in this manual for more information.


Starting the Program

        Back to the Table of Contents

Tap on the Applications button to bring up the list of programs on your Palm. Look for the "M" icon of Marco, and tap it.


Beaming Marco

        Back to the Table of Contents

Beaming Marco to another handheld lets people see if it will work for them. Also, beaming Marco to other registered users can allow them to upgrade to your version, saving them the hassle of connecting their Palm to a computer, downloading Marco, and installing it themselves.

To beam Marco, tap on the Applications button, and then on the Menu button. Select Beam under the App menu. Now select Marco and tap the Beam button. Make sure both Palms are within range, and the other person has "Beam Receive" (in the preferences) turned on.

MathLib can also be beamed to another Palm with the same method, or it can be beamed from within Marco. To beam MathLib within Marco, just run the program, tap on the menu button, select the Marco menu, and there is an option to Beam MathLib. This may be easier than searching through the beam menus with the application launcher.


General Layout of Screens

        Back to the Table of Contents

Marco tries to use a similar, familiar interface on all of the screens it has. It will start out on the Main Menu, where you can press a button to do a specific function. From all pages except the Main Menu, there is a "Main" button in the upper right-hand corner that will jump you back to the starting screen.

To enter information, tap on a button. So, if a program requires an X coordinate, it will have a button labeled with "Enter X" showing that a value is needed there. When pressed, it will bring up an appropriate input screen where an angle, value, or other information can be entered. For more information about the prompting that Marco performs, see Entering Information in this manual.

Information, once entered, can not be overwritten by tapping the button again. This is because once informaton has been entered or calculated, it can change many other values internally. Pressing the Clear button in the lower left corner will erase what you were working on and will allow you to start over. In some instances, single values can be cleared. There will be an X button immediately to the left of the value that can be cleared. Tapping the X will erase just that one number and will keep the rest.

Sometimes, buttons will be hidden from view so that information is not entered in the wrong spot at the wrong time. Don't worry -- they will come back at the appropriate times and be filled in with calculated data automatically.

If there are multiple screens that a particular program uses, there will be a bar in the lower right corner with abbreviations of all the screens. Tapping on one of them will go to that page.

Marco can use multiple point files. A single point file is a collection of points, typically for a single project. It helps keep points with the same name, but different projects, separate. The current point file is displayed in the upper-right hand corner of the Main Menu. To switch to another point file, tap on the name of the current point file. A list of all available point databases on the Palm will be displayed. Select one from the list, or pick the Manage Databases option to handle creating, deleting, renaming, and beaming of point files.


Entering Information

        Back to the Table of Contents

When you need to enter information into Marco, there will be an appropriate form that will pop up and ask for a value. The forms change with what type of data is being entered. Also, there is an optional keypad on the screen (set up in the preferences section) that can assist when entering numbers. Additionally, the style that angles are entered in (degrees, radians, DMS, gradians) is set in the preferences.

  Asking for a Value Asking for an Angle
With Keypad
(Angles set to Degrees)
Without Keypad
(Angles set to DMS)

When the form is up, tapping on the buttons on the keypad will enter numbers, and the standard Palm grafitti method of inputting data works as well.


Context-Specific Help

        Back to the Table of Contents

By tapping on the menu button, and then picking Help under the Marco menu, it will show information about the current screen or form. That way, if you get stuck or you don't know what a particular value is, an explanation is always easily available and is built-in to every copy of Marco.


Horizontal Curves

        Back to the Table of Contents

Horizontal curves are used when making a left or a right turn on a road, and could also be applied to borders in landscaping, making a curved sidewalk, or dozens of other applications. The program is divided into four screens. The "Data" screen is where the information describing the curve is entered. "Diag" is a diagram illustrating the lengths and locations of points that are involved in the curve. "Loc" contains information about the location of the curve. "Table" will show a series of points along the curve with their cord length and angle of deflection.


Vertical Curves

        Back to the Table of Contents

Vertical curves are necessary when changing inclines due to going over a hill, down into a valley, or from a flat area to a different elevation. Like Horizontal Curves, this has four screens as well. The "Data" screen shows the variables that need to be defined in order to create a curve. "Diag" shows an illustration of two vertical curves, which lables the points and lengths that are needed. "Query" finds specific elevations or stations on or outside the curve. "Table" lists the elevations of a series of points that are on the curve.


Center Line for Curves

        Back to the Table of Contents

Center Line for Curves will locate a series of X and Y coordinates that are along a line or offset from a line. This allows the creation of lanes on a road, sidewalks, and ditch lines. Because the curve and the location of the cuve must be defined, there are several variables required. They are unable to be squeezed on just one screen, and have been broken up onto four different forms.

If everything is known about a curve and the first data screen can be filled in completely, the rest of the curve will be properly defined automatically. If not, enter known values on the first three data screens and the unknown ones will be calculated. as soon as enough information is entered.

The fourth data page is special and sets up the information required for the "Table" screen. If you plan on only using the "Query" screen, it does not need to be filled in.

The "Diag" tab shows diagram of a sample center line and where all of the lengths, points, and angles are located. "Query" allows the user to find the location of an offset at a specific station, and calculates the station and offset of an entered coordinate pair. "Table" lists a series of points that are a given offset away from the center line. By tapping on the "L" and "R" buttons, the offset will be to the left or right of the curve. By tapping on a point, the selected point's coordinates can be saved to the current point file.


Intersection

        Back to the Table of Contents

Intersection acts like three programs in one. It can find the intersection of two lines, two circles, or a line and a circle. Start by selecting what the first object is by tapping the Line or Circle buttons. In the image above, the first object is a line. Then, define the location of that object. When done, tap on the Object 2 button and select if it is a Line or a Circle. In the example above, the second object is a circle. After defining the location of the object, tap on Result to see where the two entities intersect and the distances from any coordinates that were entered.


Proportion

        Back to the Table of Contents

This program calculates a proportional increase or decrease. It is used when expanding a road to accomodate another lane, a turn lane, or to shrink a road right before a bridge. The "Data" form defines the starting and ending values along with the starting and ending stationing. It also sets the increment for the Table screen. "Table" shows a list of stations and the proportional value at each location.


Inverse

        Back to the Table of Contents

Inverse can take two points and calculate the azimuth and distance between them. It can also determine a second point's coordinates when given a starting point, an azimuth, and a distance. Pressing the "Traverse" button will put the second point's coordinates in as the starting point, so another point can be calculated.


Center Line for Lines

        Back to the Table of Contents

To find a series of points that are a given offset from a line, or to find information about how far a particular point is away from a line, use Center Line for Lines. MnDOT uses this for marking lanes, shoulders, and sidewalks that are a given distance away from the center of the road. Enter information on the two "Data" screens. The "Starting Point" form asks for where the line starts and further information needed for the "Table" page. "Direction" records where the line travels to. Once the line is defined, use the "Query" screen to find the station and offset of any point, or find the coordinates for a given station and offset. "Table" will generate a list of coordinates at specific stations. The "L" and "R" buttons change the offset to be left and right, accordingly.


Grading PI

        Back to the Table of Contents

Finding the elevations and widths of the lanes, shoulder, and embankment of a road involves many calculations. This section of Marco makes that process easier. The "Grad" screen contains all of the information about the grading for the road. "Final" is the finished road for the shoulder and lanes. The embankment's measurements are covered with the "Edge" form. To help locate reference points, a cut-away side view of a road is on the "Diag" page.


Area of a Polygon

        Back to the Table of Contents

Squares, triangles, and anything else with a border made of straight line segments can have their areas calculated. Press "Add" to add a point, or "Pick" to select a saved point from a point list. When done defining the border, the "Calc" button will display the area of the object, the perimeter around the outside, and the centroid. "Del" will erase the selected point from this screen and "Clear" will start the process over.


Triangles

        Back to the Table of Contents

Triangles can be calculated by entering any side and two other values (sides or angles). This unique tool has two different ways of displaying the same information. By going into Preferences, it is possible to change between the tabular view (on the left) and the spatial view (on the right).


Angle Converter

        Back to the Table of Contents

This simple utility converts angles from one type to another. To enter an angle, just tap on the buttons in the middle. The "+" and "-" buttons allow you to add and subtract an angle from the one currently displayed. Angles are always positive, and are from 0 to just under 360°.


Quadratic Formula Solver

        Back to the Table of Contents

A quick calculator that will find the X intercepts for a given quadriatic equation.


Edit Points

        Back to the Table of Contents

This interface allows easy manipulation of saved points. It will list all of the points in the currently open file. By selecting one and pressing "View," the X and Y coordinates, the elevation, and the station, will be displayed. Points may not have all of those values, so it leaves blank anything that wasn't entered. If the "Edit" button is pressed, those values can be altered. "Delete" removes a point from the list permanently. It is not possible to undelete a point, so be careful.

On the Edit screen, the Description field does not have an "X" button to clear it. To rename a point, just tap on the Description button and it will allow a new name to be entered.


Preferences

        Back to the Table of Contents

Many attributes about how Marco operates are configurable. The Preferences section is where configuration options are accessed. "Units of Measure" configures how angles are entered and displayed, and how coordinates are used. With "X, Y" coordinates, the X is always prompted for first. Likewise, "Northing, Easting" will always ask for the Northing before the Easting.

"Numbers and Precision" defines how many digits beyond the decimal point should be shown in varying circumstances. The amount of precision for each type of angle measurement is configured separately, and the various numbers also have the same options. In order to save space, any trailing zeros can be removed from numbers in tables, in the buttons, and in other assorted places by checking the appropriate box.

On the "Entering Information" page, you can turn off confirmation of deletions in the Edit Points screens, and will turn on and off the number pad that is used when Entering Information. The "Tabular" and "Spatial" buttons toggle beteween the different layouts for the Triangles form.

When changing the settings, make sure to hit "Save" when done, or "Cancel" to go back without saving the new settings.


Manage Databases

        Back to the Table of Contents

Marco can use multiple point databases to keep individual points separated into groups. To switch to another database, go to the main page and tap on the name of the currently open point file in the upper right hand corner. (Marco creates the default point file called "Marco Points" initially.) This will bring up a list of available point files on your Palm. Select another one to use that alternate point file.

If "Manage Databases" is picked, Marco will display a special screen where point files can be created, deleted, and renamed. If a point file is deleted, it can not be restored, so be careful.


Registration Information

        Back to the Table of Contents

Marco used to be shareware, but now it is not supported. I have opened up the registration process to immediately generate you a working code.

Follow these steps to register Marco for your handheld:

  1. Start Marco.
  2. Tap on the menu button and select "About Marco" to determine the version of Marco on your handheld.
  3. Write down the version of Marco. This is VERY important. Keep this information in a safe place.
  4. Press "Ok" to go back to the main menu of Marco.
  5. Tap on Preferences, and then press Register Me.
  6. Look for something that says RegCode. It should look something like this: 82:C1:DF:7D:7A:81:70:21:7E:B5:BD
  7. Write down your RegCode in the same place where you wrote down the version of Marco you are registering.
  8. Enter your code here:
    You unlock code:
  9. Once you get an unlock code (typically a number with five digits), go back to the registration screen by running Marco, tapping on Preferences, and then picking Register Me. Press the button to enter the unlock code.
  10. After entering the code and pressing Ok, Marco will say that it is going to jump back to the applications screen. That's fine. It doesn't hurt anything. Just re-run Marco.
  11. To check if it is registered, go back to the preferences screen. The Register Me button should no longer be there. If it still is there, the unlock code that was entered is not a valid code.

If you have any problems, try reading the FAQ for answers.


Upgrades

        Back to the Table of Contents

When registering Marco, you will get a limited number of bugfixes and enhancements for free. To help keep track of what versions you can and can not use, a "magic number" is encoded into the RegCode and embedded into Marco. That lets me allow people to upgrade Marco to the newest version when updates are made.

When new features are added, the magic number gets made just a little bit bigger. The magic number is not changed if there is just a bugfix or minor enhancement. When the magic number is too big, your registration code will no longer work and you will need to register a newer copy of Marco.

To see what versions of Marco you can use, just look on the table below. If you use a version of Marco that is outside of your range, the software will become unregistered. You will need to install a different version and enter your old code or install the latest version of Marco and just re-register it.

Registered
Version
Maximum
Version
The reason for the change
3.0AnyMultiple point databases, restructured strings
2.6AnyGrading PI, area of polygon, quadriatic solver
2.5AnyAngle converter, reworked lots of code, bearing
2.2 - 2.4AnySave point
1.9 - 2.1AnyKeyboard, center line for curves formulas
1.6 - 1.83.0Center line for curves
1.52.6Center line for lines
1.0 - 1.42.5Initial registration system

Calculators

        Back to the Table of Contents

Marco was designed to not have a built-in calculator. For the reasoning behind that, please see the FAQ. If you don't like the built-in calculator, there are different ones that may work better. If desired, a different calculator can be mapped to the calculator button on the Palm, taking the place of the built-in calculator.

There are two different types of calculators when it comes to how they process numbers. Different buttons are pressed when performing a calculation, like 2 * 3. With infix, you press 2 X 3 Enter and you would get your answer. With RPN, you would press 2 Enter 3 X.

With regard to how the calculators run on the handheld, there are also two different styles. Popup calculators will appear "over" the currently running program so that you don't lose your information. Usually they start with a unique "stroke" of the grafitti pen and are considered "hacks" (add-ons and extensions to the system). The other kind are just normal programs, like the calculator already on the Palm. You'll switch to the calculator and then back to Marco. It can not appear as a window over another program and you will lose anything you entered into Marco except saved points.

Many of the calculators use MathLib for trig functions. If Marco runs, then MathLib is installed on your Palm, and then all of these calculators should also work.

Calculator Applications

These calculators run as separate programs and do not "pop up" over Marco. However, they usually have added functionality and are often much more powerful than the other style. You would install these like any other program -- download, extract, and then install the .prc file.

Bez Calculator
Scientific calculator program. Great if base conversions are not needed and Calcul-8! has buttons that are just too small. [Infix, Freeware, Open Source]
C4
Advanced color calculator. Different versions are available. C4Me is freeware, but the others are shareware. [Infix, Shareware/Freeware]
Calcul-8!
Nice calculator with unit conversion, scientific functions, and base conversions. [Infix, Freeware]
FreeForm
A simple and clean interface for a small calculator. It supports parenthesis up to a depth of 25, and 10 memories. For frequent calculations, scripts can be written that support loops and conditional execution. [Infix, Freeware]
Kalk
Very nice RPN calculator -- one of the better ones available. Has a fancy version with color buttons and a lite version for people with a limited amount of free memory. [RPN, Freeware, Open Source]

Calculator Hacks

These "hacks" (or system extensions) require a hack manager such as X-Master, HackMaster, or similar. I suggest X-Master because it is free and has more features than what are usually needed. You download, extract, and install the calculators. Then, you set them up by running X-Master (or your alternate hack manager) and configuring the calculator.

With the advent of Palm OS 5 and later, hacks are no longer supported, but some people have converted their software to work with the new system provided. For the calculators listed below, there will be an annotation of "Hack" if it works with Palm OS 4 and earlier, and "OS5" if it works with Palm OS 5 and later.

snapCalc
Pops up a calculator window over whatever application is running. The results of the calculations can be copied back to the current program. The size of the calculator can be a small moveable one or a large layout that nearly takes up the entire screen. [Infix, Freeware, Hack, OS5]
PopUp Calculator and RPN PopUp Calculator
Alternate pop-up calculator that supports three different calculator form sizes and trig functions. [Infix or RPN, Shareware, Hack]

Frequently Asked Questions (FAQ)

        Back to the Table of Contents

This is a list of common questions asked about Marco itself or about topics that relate to Marco. If your question is not answered here, contact the author for a quick solution.

Points

I edited a point and it no longer appears in the list of points. What happened to it?

Marco sorts point names alphabetically because that is the only method that Palm OS supplies. Unfortunately, this means that a list of 1, 2, 10, and 11 would be sorted as 1, 10, 11, 2. A screen capture, to the right, shows this odd behavior. It sorts the first letter, then the second letter, then the third. It doesn't sort the number as an actual number.

If this method of sorting is hard to get used to, just add zeros at the beginning so that all of the numbers are of the same length. The above set of numbers with zeros at the beginning would sort to 01, 02, 10, 11. The point conversion utility on the web site can import points and add zeros at the beginning of point numbers so that they sort properly.

If this problem is extremely severe, request that I work on a "natural sorting" method. It would likely be significantly slower, but would give the desired results.

Calculations

How accurate is Marco?

Marco uses MathLib for number calculations. See the MathLib section for detailed information.

Why can't I go to the calculator and back to Marco without losing everything I entered?

If you leave Marco and come back, all of the data entered will be cleared away. I do this to save memory, make upgrades easier, and to avoid several programming hassles. I agree that it is annoying when you need to look up information in your calculator, and I strongly suggest using a popup calculator to solve the problem. Popup calculators can appear "on top" of any running program on a Palm, and will let you calculate numbers quickly.

See the section on calculators for a list of recommended calculators.

Is there an alternate calculator that I can use instead of the built-in one?

Yes. There are several, one of which is sure to fit your needs. See the section on calculators for a list of recommended calculators.

Why doesn't Marco have a built-in calculator?

Having a calculator added to Marco was seriously debated many times. It was decided to not be added to the program for several reasons:

  • It would make Marco bigger (it is quite large enough).
  • If it is an RPN calculator, infix people would be annoyed. If it was an infix calculator, RPN people would be annoyed. If it was both, the program would be much bigger.
  • More potential for bugs in the system.
  • It wouldn't integrate easily with the calculator button.
  • There are several great calculators out there already.

Miscellaneous

Which handheld should I buy to use Marco?

The only requirement for a handheld is that it runs Palm OS 3.0 or newer. It might run with Palm OS 2.0, but that hasn't been tested. Marco has been tested to run on several versions of Palm Pilots, Handspring units, and even a Palm OS based cell phone. If you are buying a new device, make sure it runs "Palm OS" -- it will not run on Palm-sized computers running Windows CE or other operating systems.

If you are going to buy a device and want to know which one I recommend, here are my suggestions:

  • Brand: One is as good as another. I'd suggest Handspring, but they just merged back with Palm, so there isn't really any difference there.
  • Memory: 2 megs of memory is enough for hundreds of thousands of points for Marco, a few custom applications, tons of addresses, several memos, and a large todo list. If you plan on using the Palm a lot, or if you want to have space to spare, I would suggest 8 or 16 megs.
  • Color/Black & White: Color screens are very pretty, and they show up nice in dark areas. Black & white screens draw much less power, so the handheld can run longer without recharging or replacing the batteries. If this is for work, get black and white. If it is for play, home use, or for testing out programs, color is nice.
  • Hi-res/Standard Resolution: The newer high-res screens are nice and make reading less fatiguing. I would suggest a high-res screen if possible. It works well with many games, document readers, and other sorts of programs. Overall, it will smooth out fonts to make them more appealing and rounds buttons a bit nicer.
  • Price: If it is going to be used out in the field, don't get a very expensive one. Dust can quickly scratch up the screen, accidents happen, and Palms can get dropped. Of course, get whatever you think is needed and would be used.
  • Accessories: A case. Get a good case. A nice, sturdy padded case with velcro and a zipper around the Palm is a good idea. A metal case that is able to withstand abuse is a good idea. I can not suggest this enough -- get a good case for the Palm. It will get dropped.

Contacting the Author

        Back to the Table of Contents

Marco is now "end of life" software, which means I no longer will support it. Because it is no longer supported, I have opened up the registration page and it will generate you a working code automatically.

If you were asking about a problem, make sure to check the FAQ (Frequently Asked Questions). Also, if a particular feature has you stumped, try checking the manual and see if the answer is there.

Rubber bands will last longer if they are kept in a refrigerator. Tyler Akins! <>
Contact Me - Legal Info