Mariner's Document Filler

1. What it is

A single HTML file. Double-click it and it opens in Edge or Chrome. There is nothing to install, no admin rights needed, and it runs with the network cable pulled — which matters when you are alongside at 0300 and the ship's satellite link is down.

It does two jobs:

Fills forms. You give it the blank form and your data workbook, tell it once which value goes where, and it produces the filled document. The next time that form comes round, you skip straight to the filling.

Writes text reports. Messages built from the same workbook with no blank form involved — AMVER sailing plans, noon reports, notices, protests.

Both work from the same data, so the vessel particulars you type once serve the FAL forms, the passage plan and the AMVER message alike.

2. Getting started in five minutes

1. Open the file. Double-click it. Four tabs appear: Data, Map, Fill, Reports, and a Guide.

2. Load your workbook. Press Load .xlsx and pick your data file. The Data tab lists every sheet it found and what it made of each one. Check those counts — if a sheet says 20 values and you expected 20 records, change it with the dropdown on that sheet's card.

3. Load a blank form. Press Load form and pick a PDF, Word, Excel or HTML file.

4. Say where things go. What you see next depends on the form:

5. A PDF with real form fields lists them. Press Match by name and it fills in most of them for you; correct anything it got wrong.
6. A flat or scanned PDF draws the page on screen and you click where each value belongs.

7. Word and Excel are covered further down.

8. Fill. Go to the Fill tab and press Fill form. The finished file lands in your Downloads folder.

9. Save the mapping. Press Save in the Mapping slot at the top. Keep that JSON file next to the blank form. Next time this form comes round, load the blank, load the mapping, press Fill — about fifteen seconds.

3. The data workbook

How a sheet is read

Every sheet is read one of four ways, and the Data tab tells you which:

Any of these can be overridden from the dropdown on that sheet's card. Check the counts after loading — a mis-read sheet is the single most common cause of a form filling wrongly.

Watch this one. A two-column sheet is always read as label/value. If you keep a stores list as just Item | Quantity, switch it to Read as record table or the tool will treat your items as field names.

Several workbooks at once

You can load as many workbooks as you like and their sheets pool together. A ship-particulars file, a noon file and a bunker file can fill one form between them. Each is listed on the Data tab with its own × to remove it, and a sheet name used twice gets its file name added so nothing is silently shadowed.

This is much better than linking workbooks together with formulas. An external formula works only while the source file stays put under the same name — and on a ship's PC, after somebody reorganises a folder, the value you keep getting is whatever Excel last cached. It looks entirely normal.

Formulas

Formulas give their result, not their text. =20*24 arrives as 480.

What is actually read is the value Excel saved the last time it calculated. So:

• A file Excel saved is always fine.
• A file written by a script that never calculated will read blank. Open it in Excel once and save it.
• A broken link to another workbook shows as #REF! or #N/A — the tool displays the error text and lists every offending cell on the Data tab, rather than letting it go quietly blank on a document you are about to sign.

How to type things

4. Filling forms

PDF with real form fields

The accurate route, and the easiest. Fields are listed with a searchable box beside each.

• Match by name proposes sources for as many as it can and reports what it could not place.
• Numbered fields such as Family_name_1 … Family_name_20 are recognised as a series. Point the series at one column and every line fills.
• The ↵ button beside a text field lets a long value wrap onto more than one line inside that field.
• Flatten (on by default) bakes the values into the page so they cannot be edited afterwards.

PDF that is flat or scanned

A scan is a photograph of paper — there is nothing to read and nothing to match. You place each value by hand once, and then the coordinates are saved forever.

• Click the page where a value belongs. A magenta chip appears.
• Drag it, or nudge with the arrow keys (hold Shift for larger steps).
• A ruled table takes one placement per column, not one per crew member. Place the first line, set how many lines the form has, then drag the row spacing slider until the ghosted rows sit on the printed rulings. Spacing is shown in points and the panel tells you where the last line will land.
• Column width stops a long name running into the next column. Type it in points or drag the handle on the right of the chip. Every repeated row inherits it.
• Row height plus Break a long value onto more lines lets a long name wrap inside the ruled row instead of shrinking. The panel tells you how many lines fit.
• Anything the tool had to shrink or shorten is named in the log.

A full crew list takes perhaps twenty minutes the first time. After that it is instant.

Word

Word is the one format where you edit the blank. Open it in Word and type a token where each value belongs, then save. The token is the mapping — there is nothing else to set up, and nothing useful for a mapping file to hold.

• {{Ship.Vessel Name}} — one value.
• Crew lists: fill in the first data row only, with tokens that have no number in them — {{Crew.Rank}}, not {{Crew[1].Rank}}. That row is a pattern and the table grows to one row per crew member on its own.
• Spacing, tabs and line breaks around a token are kept exactly as you typed them, and the value inherits the formatting of the run it sits in. If you want the value on the line below the label, put the token on the line below the label.
• Filling only part of a document: a .docx holds no page numbers — Word works those out when it lays the document out. What the file does contain is manual page breaks and section breaks, so a Word form is listed as the parts it is really divided into. Untick one and it is copied through untouched.

Your tokenised document is the template. Keep it; the output is saved as a separate — FILLED file, so the template is never overwritten.

Excel

Two ways, and the first is usually better:

Pointing at cells. The sheet is drawn in the tool, you click a cell and choose the value. The blank workbook is never modified — the cell addresses live in the mapping file, so a charterer's form stays pristine. Pick a crew column and it offers to continue down one row per record. Mapped cells show their resolved value so you can see the filled form before you fill it.

Tokens. Type {{tokens}} into the blank in Excel. Cell formatting is preserved exactly. Use numbered tokens — {{Crew[1].Surname}} — for forms with fixed numbered lines.

HTML

Port community systems often hand out a page you open in the browser, fill in and print.

• Real input boxes are listed like PDF fields.
• Tokens work in the page text too, and a table row with an un-numbered token repeats per record.
• Pages with tabs are handled in full. Tabs are only sections of one page being shown and hidden, so every box on every tab is filled at once. The exception is a page that fetches a tab from the server when you click it — that content is not in the file you saved. If a tab looks empty, save the page again with every tab opened first.

5. Tokens and formats

Writing a token

You rarely type these by hand. In any value box, start typing a column name and a list appears — arrow keys to move, Enter to take one. In the report editor, typing {{ brings the same list up at the cursor.

Once set, a token shows as a chip reading Vessel Name with its sheet beneath. Hover to see the token it stands for; click it to edit again.

Formats

Add a format after a vertical bar: {{Voyage.ETA | date:DD MMM YYYY}}

Date pattern letters: YYYY YY MMM MM DD HH mm. Anything else in the pattern is copied through, which is how DDHHmmZ MMM produces the trailing Z.

Formats chain

Separate them with more bars, applied left to right:

{{Route.Leg | split:1 | number | digits:3}}

With an ECDIS export where one cell holds 175.7° 0.23 NM, that returns 176.

Positions

Positions are accepted however your workbook holds them, and an already-correct value passes through untouched:

• 41.3917 — decimal degrees
• 41 23.5 N — degrees and minutes
• 41-23.5N — the hyphen is a separator, not a minus
• 4123N — already compact
• 412330N — degrees, minutes, seconds
• 60° 05.179 N 024° 21.112 E — both halves in one cell. pos:lat takes the left half, pos:lon the right. ECDIS exports usually look like this and need no rearranging.

A cell containing no number at all — XXX.X, Undefined, Shallow water — comes out empty with the number format, so ECDIS placeholders never reach a finished report.

pos:lat rounds to whole minutes because that is what the AMVER format is — up to half a minute, about 0.9 km. Use pos:latdm anywhere you want the tenth.

6. Lists that do not fit

The three formats behave differently, and the differences matter.

Word grows. A table row holding un-numbered tokens is cloned once per record. Twenty-two crew produce twenty-two rows and everything below moves down. Nothing to manage.

PDF cannot grow, so it continues onto more copies. Seven crew into a three-line form gives you three files — (1 of 3), (2 of 3), (3 of 3) — with crew 1–3, 4–6 and 7. Vessel particulars repeat on every copy. A fixed value such as a Nature of Identity column of "Passport" fills exactly as many lines as there are crew on that copy, so the last copy does not print Passport against nobody. Turn it off on the Fill tab to get the first copy only.

Excel overwrites. This is the one to watch. A list written down a sheet replaces whatever is under it — it cannot push rows down the way Word can. Twenty-two crew filling a block of ten will run straight through a totals row and a signature line, and the result looks perfectly normal.

Two protections:

1. Overwrite warnings. Any fill-down landing on a non-empty cell is named in the log: A6 already held "TOTAL CREW" and was overwritten.

2. Work area markers — better, because they prevent it. Put {{workarea}} above the block and {{workarea end}} below it. Only what lies between is touched, and both markers are removed from the finished file. If the list will not fit, it stops at the fence and says so: the work area ends at row 6, so 4 of 7 records will not fit.

Openers: {{workarea}}, {{workarea start}}, {{workarea enter}}, {{workarea begin}}, {{workarea open}}, {{#workarea}} Closers: {{workarea end}}, {{workarea exit}}, {{workarea close}}, {{/workarea}}

Markers work in Word too, fencing off the part of the document to be filled. In Excel the fence is row-based — it guards what is above and below, not a column of notes beside the block.

7. Match by name, and teaching it your wording

Match by name proposes sources for a whole form at once. It knows maritime vocabulary, not just text matching, so on an IMO FAL 5 crew list it gets:

6_Family_name_{n}                  →  Crew › Surname
7_Given_names_{n}                  →  Crew › Given Names
8_Rank_or_rating_{n}               →  Crew › Rank
13_Number_of_identity_document_{n} →  Crew › Passport

It strips clause numbers and Txt_ prefixes first, and for numbered series it votes on which sheet the form's list is really about, then biases every line toward that one sheet.

It leaves things blank rather than guessing. 12_Nature_of_identity_document asks what kind of document it is — the answer is the word "Passport", not a passport number. Nothing in your workbook means that, so it stays empty and is listed under No confident match for these. A wrong match is worse than no match: blank is visible, whereas a passport number sitting under "Nature of identity" looks filled and gets signed.

The Vocabulary sheet

When Match by name lists something your workbook does hold under a different name, teach it. Add a sheet called Vocabulary — one row per group of words that mean the same thing, your own column name first:

Lifeboat      Muster Station      Boat Number    Survival Craft
Vaccination   Yellow Fever Cert   Health Certificate

No header row. Rows with fewer than two words are ignored, so single-cell headings and notes are safe to include.

A known word inside a longer heading still counts, which covers the endless … no., … number and … code variants — Survival craft no. finds your Lifeboat column.

One rule when extending it: only group wordings that mean the same thing, not things that merely sit near each other on a form. Two rows sharing a word are fused into one group.

The loop is: press Match → read the leftovers → paste those words into Vocabulary beside the right column → reload → press again. You build the dictionary from the forms actually in front of you.

8. Mappings: set up once, use forever

For PDF, Excel-by-cells and HTML, everything you set up is stored in a small JSON file. It holds field names, cell addresses and coordinates — no ship or crew data at all, so it is safe to email or share.

A folder per form:

Rotterdam pre-arrival/
    pre-arrival.pdf                 the blank, never edited
    pre-arrival - mapping.json      the setup

The whole folder copies to a memory stick, or hands over to your relief. Nothing is stored inside the tool itself — deliberately, because a shared ship's PC and a handover are the normal case.

Word is the exception: the tokens live in the document, so the tokenised document is the mapping.

9. Text reports

The Reports tab builds messages from the workbook with no blank form involved. Thirty-five templates in six categories, every one editable.

Using them

Pick one; the output appears below the editor and updates as you type. Copy puts it on the clipboard, Save .txt writes a file. The character count is shown, which matters where a system has a length limit.

Repeating lines. A line holding an un-numbered table token repeats once per record — one line per bunker grade, one AMVER L line per waypoint.

Lines with no data drop out, so an unfilled field does not leave a stray F/ in the message. Turn that off with the checkbox if you want the skeleton.

Sections. Text between [[Weather]] and [[/Weather]] is a section with its own on/off button, so one noon template covers laden and ballast, at sea and in port. + Section adds your own.

Your own templates and categories

+ New template asks for a name and a category — type a category that does not exist and it is created. Rename also moves a template between categories. Delete removes a template, or a whole category when everything in it is yours.

Export writes every template to report-templates.json; Import merges one back, updating what it recognises and adding what it does not. That file is how a set of company wordings travels to the next ship, or to your relief. Reset all returns to the supplied set.

About the standard formats

AMVER message formats follow the examples published by the United States Coast Guard at amver.com. The pollution and dangerous-goods formats follow IMO Resolution A.851(20), which states that inappropriate sections should be omitted — so the template carries every line and you delete what does not apply.

Your ship's SOPEP holds the authoritative pollution report format and the coastal-state contact list. The template here is a drafting aid, not a replacement.

10. What it will not do

Worth reading before you rely on it.

It does not calculate anything. Distance run, average speed, consumption since last noon, cargo figures — all copied from your workbook, never worked out here. That is deliberate: a wrong number stays visible in a sheet you control rather than being produced by something you cannot inspect.

It does not verify anything. It copies what it is given. Drafts, soundings, ROB, expiry dates — nobody checks them but you.

The Master remains responsible for every figure and every signature. Check the output against the original before signing.

Non-English letters in PDFs. The fonts built into a PDF form cover a limited set of characters. With transliteration on, letters outside it become their passport spelling — the same letters that appear in the machine-readable zone, which is what officials expect on a crew list. Every substitution is written into the log. Word, Excel and HTML take any letter and are left alone.

Things it warns you about, all in the fill log: cells it overwrote, records that would not fit, values it had to shrink or shorten, formula errors in the workbook, sources it could not find.

11. Troubleshooting

12. Keeping it aboard

• One folder per form: the blank, and its mapping.
• One workbook per job, or several loaded together.
• Export your report templates when you have tailored them to your company.
• The whole lot copies to a memory stick and hands over to your relief.
• No install, no internet, no admin rights, nothing stored inside the tool.

Credits

Built on four open-source libraries, with thanks: pdf-lib (MIT), SheetJS (Apache-2.0), PizZip (MIT / GPL-3.0) and PDF.js (Apache-2.0).

AMVER is a service of the United States Coast Guard. Neither the USCG nor the IMO is affiliated with this tool.

www.marinershandapp.com