halcon-doc-specialist

name	halcon-doc-specialist
description	The absolute expert guidance for bilingual (English/German) HALCON documentation. Covers the entire spectrum of .def file slots, parameter metadata, advanced parallelization slots, German localization, and LaTeX/ASCII formatting rules.

Ultimate HALCON Documentation Specialist Skill

This skill ensures that all HALCON documentation meets MVTec's professional, bilingual, and localized standards. It is the definitive authority on the technical syntax of operator databases (.def files) and procedure documentation (.hdvp).

When to use this skill

• Use this when writing or refining documentation for C-extension operators in .def files.
• Use this when documenting HALCON procedures (.hdvp) or HDevelop scripts.
• Use this to ensure correct German localization, technical terminology, and special character usage.
• Use this to implement advanced operator features like automatic parallelization documentation.

How to use it

1. Fundamental Mandates

• Bilingual: Every operator and procedure MUST be documented in English (en_US) and German (de_DE).
• Encoding: .def files containing non-ASCII characters MUST be UTF-8 encoded.
• Special Characters: ALWAYS use proper German characters (ä, ö, ü, ß). NEVER use ASCII fallbacks.
• Version Awareness: Documentation requirements can evolve. Use search_halcon_knowledge with halcon_version="X.Y" to verify if specific slots or parallelization methods were required or supported in older HALCON versions.

2. Ultimate Operator Database (.def) Specification

Entries must follow a strict sequence. Every slot ends with a semicolon (;).

Mandatory & Extended Operator Slots:

1. Header: extern_op_name <- InternCProc [InObj:OutObj:InCtrl:OutCtrl];
2. short.english / short.german: Concise summary.
3. warning.english / warning.german: Bold warning at the top (optional).
4. module: Recommended value is foundation for extensions. Must appear before abstract.
5. abstract.english / abstract.german: The primary functional description.
6. attention.english / attention.german: Specific usage notes (optional).
7. result_state.english / result_state.german: Document return values and custom error codes (e.g., 33xxx).
8. parallelization: (Optional but recommended)
   • process_exclusively: true, false, none.
   • process_mutual: true, false.
   • process_locally: true, false.
   • method: split_tuple, split_channel, split_domain.
9. complexity: Description of time/space requirements.
10. example.trias: HDevelop code snippet demonstrating usage.
11. see_also: References to related operators.

Parameter Slot Requirements:

Every parameter block starts with parameter Name: type; (where type is input_object, output_control, etc.) and includes:

• description.english / .german: Mandatory individual documentation.
• sem_type: Semantic meaning (e.g., image, number, filename, string).
• type_list: Allowed data types (e.g., byte, int2 or integer, real).
• multivalue: false (one value), true (tuple), or optional (both).
• default_type: Mandatory for controls.
• default_value: Recommended for inputs.
• values / value_list: Recommended values for selection.
• value_min / value_max: For numeric range validation.
• costs_weight: Mandatory if parallelization method is not none.
• postprocessing: Mandatory for output controls if parallelized (e.g., tuple_concat, tuple_add).

3. LaTeX/ASCII Hybrid Formatting

To support online help and PDF generation, follow these syntax rules:

• Quotation: `code_string' vs prose_emphasis'' ``.
• References: \OpRef{op_name}, \ParRef{param_name}, \ValRef{value}.
• Special Tags:
  • @a: Start ASCII-only section (Online Help). If followed by newline, acts like <PRE>.
  • @l: Start LaTeX-only section (PDF Manual).
  • @e: End special section.
• Formatting: \emph{}, \texttt{}, \textbf{}, \textit{}. (No nesting allowed).
• Tables: \begin{Table}[style]{format} ... \end{Table}. Columns use &, rows end with \\.

Knowledge Areas

• Technical Writing: Objective, professional, technical tone.
• Localization: Specialized German machine vision terminology.
• Parallelization Contract: Documenting how HALCON should split data for AOP.
• Compiler Compliance: Ensuring .def files pass hcomp without errors.