HelpNDoc's script debugging is typically done by emitting messages at generation time and (when needed) stopping execution intentionally at a precise point.

This page documents the four compiler-style directives you can use to output diagnostic messages:

{$HINT "This is a hint"}
{$WARNING "This is a warning"}
{$ERROR "This is an error"}
{$FATAL "This is a fatal error"}

…and the two location objects you can use to pinpoint where a problem originates at generation time:

• CurrentSourceCodeLocation (properties: Line, File, Name)
• CallerSourceCodeLocation (properties: Line, File, Name)

Together, these let you:

• confirm whether a code path executed,
• identify which script file/procedure produced a message,
• locate the exact line that triggered it,
• and optionally stop generation when a condition is incorrect.

Message directives

All four directives emit a message that appears in HelpNDoc's generation logs/output. They differ by severity and by whether they should be used to flag non-blocking diagnostics versus stop the process.

{$HINT "message"}

What it does
Emits an informational diagnostic message (a hint). This is best used for lightweight tracing.

Benefits

• Lowest "noise" severity: useful for temporary instrumentation.
• Great for confirming execution flow ("did this branch run?").
• Good for printing values while iterating on logic.

How to use it to debug

• Add hints at the start/end of functions.
• Add hints inside conditional branches to see which path was taken.
• Use it to print computed values that influence output.

Example:

{$HINT "Entered BuildTopicNavigation"}

{$WARNING "message"}

What it does
Emits a warning message. This signals a potential problem, but typically does not justify stopping generation.

Benefits

• More visible than hints: good for issues you want to notice and fix soon.
• Ideal for "unexpected but survivable" conditions (missing optional data, fallback behavior, unusual values).

How to use it to debug

• Warn when data is missing but you can proceed.
• Warn when you take a fallback path you didn't expect to be common.

Example:

{$WARNING "Topic has no short description; using title instead"}

{$ERROR "message"}

What it does
Emits an error message. Use this when something is wrong enough that output may be incorrect, or a required condition is not met.

Benefits

• Makes failures obvious in logs.
• Encourages fixing the underlying problem rather than ignoring it.
• Useful for enforcing assumptions during script development.

How to use it to debug

• Error when an invariant is broken (e.g., required template variable empty).
• Error when a critical object can't be found or parsed.
• Combine with location info to point precisely to the failing line.

Example:

{$ERROR "Required variable 'ProductVersion' is empty"}

{$FATAL "message"}

What it does
Emits a fatal message indicating an unrecoverable condition. Use this when continuing would be pointless or dangerous (corrupt output, invalid state).

Benefits

• Stops you from producing broken documentation silently.
• Forces immediate attention to the root cause.
• Best for "hard assertions" during development.

How to use it to debug

• Put a fatal directive in code paths that must never happen.
• Use fatal errors as "stop here" markers when you need to freeze execution at a specific spot to inspect the last log messages.

Example:

{$FATAL "Unexpected state: NavigationRoot is nil"}

Practical rule of thumb:
HINT = trace, WARNING = suspicious but continue, ERROR = wrong and likely harmful, FATAL = cannot continue.

Run-Time Source Code Location Objects

HelpNDoc provides two run-time objects that describe where the script currently is (or where it was called from). These are especially useful when the same helper function is called from many places and you need to find which call site triggered a problem.

CurrentSourceCodeLocation

Represents the script location currently executing.

Properties:

• CurrentSourceCodeLocation.Line — line number in the current source file
• CurrentSourceCodeLocation.File — source file path/name
• CurrentSourceCodeLocation.Name — the current routine/module name

Benefits:

• Pinpoints where you are when a run-time condition occurs
• Helps when debugging loops/branches: you can log the exact place before/after suspicious code

Example (log current location):

print('--- Current location ---');
print('File: ' + CurrentSourceCodeLocation.File);
print('Name: ' + CurrentSourceCodeLocation.Name);
print('Line: ' + IntToStr(CurrentSourceCodeLocation.Line));

CallerSourceCodeLocation

Represents the script location of the caller that invoked the current routine.

Properties:

• CallerSourceCodeLocation.Line — line number where the call was made
• CallerSourceCodeLocation.File — caller source file
• CallerSourceCodeLocation.Name — caller routine/module name

Benefits:

• Answers: "Who called this function?"
• Extremely helpful in shared utility libraries used by many templates/pages
• Lets you detect and report misuse from specific call sites

Example (log caller location):

print('--- Caller location ---');
print('File: ' + CallerSourceCodeLocation.File);
print('Name: ' + CallerSourceCodeLocation.Name);
print('Line: ' + IntToStr(CallerSourceCodeLocation.Line));

Practical Debugging Patterns

Pattern 1: Breadcrumb logging around suspicious code

Add prints before and after a block to see whether it is entered, and where execution stops.

print('Entering block at ' + CurrentSourceCodeLocation.File + ':' + IntToStr(CurrentSourceCodeLocation.Line));
// suspicious logic here
print('Leaving block at ' + CurrentSourceCodeLocation.File + ':' + IntToStr(CurrentSourceCodeLocation.Line));

Pattern 2: Reporting invalid input with call-site context

When a helper function receives unexpected data, log both current + caller locations so you know:

• where the error was detected (current)
• where the bad call originated (caller)

if SomeValue = '' then
begin
  print('ERROR: SomeValue is empty.');
  print('Detected at: ' + CurrentSourceCodeLocation.File + ':' + IntToStr(CurrentSourceCodeLocation.Line));
  print('Called from : ' + CallerSourceCodeLocation.File + ':' + IntToStr(CallerSourceCodeLocation.Line));
  exit;
end;

Choosing Between $ Directives and Run-Time Logging

Use {$HINT} / {$WARNING} when:

• You want compile-time reminders and diagnostics
• The issue is about template structure/configuration
• You don't need run-time data to explain the problem

Use {$ERROR} / {$FATAL} when:

• Output should not be generated unless a rule is satisfied
• You want a clean, immediate failure with a clear message
• The condition can be determined at compile time

Use print + location properties when:

• The issue depends on run-time execution
• You need to know which branch/loop/call site triggered something
• You need file/line/name context

Summary

• {$HINT} and {$WARNING} help you diagnose without stopping compilation.
• {$ERROR} and {$FATAL} let you stop generation early with a clear message.
• CurrentSourceCodeLocation and CallerSourceCodeLocation are run-time only tools for pinpointing where code is executing and where it was called from.