Text in DEF files🔗
Important
DEF files with non-ASCII characters should be UTF-8 encoded.
Within a DEF file, the semicolon (;) is used to separate the single slots.
So, when using a semicolon within a text, it must be quoted with a backslash (\;).
DEF files are not only used to create interface code, but also allow the generation of PDF reference manuals, the HTML documentation, and the help files used to access operator knowledge via HALCON operators like get_operator_info.
For the online help and the HTML files an ASCII version of each text is needed, whereas the reference manuals are produced compiling a LaTeX file generated from the DEF files.
To avoid the necessity of writing two text blocks for one operator (ASCII and LaTeX), both versions are generated by using one text.
Therefore, the following conventions must be observed:
- Quotation marks
-
There are two kinds of quotation marks
- ‘string’
- This notation signals that the quoted text is a string as used within programming languages.
So
hcomptreats'string'as a string-parameter. - “Text”
- This notation must be used in all other cases, particularly when quoting a word or text segment because of its content.
So
hcomptreats``Text''as a quoted section of a text. Do not forget or permute the quotation marks (starting with``and ending with'').
- Underscores
- Underscores can be used directly for both the ASCII and the LaTeX output.
The HALCON compiler
hcompautomatically prefixes them with the necessary backslashes for the LaTeX output (\_). Please note that if you want to use an underscore in a LaTeX part to create a subscript, you must encase the subscript text in curly braces ({}) even if the subscript is only a single character. For example, to create the output “Sx” you must write$S_{x}$. If you leave out the braces, an underscore is printed, for example,$S_x$results in “S_x”. - Backslash
- All backslashes (
\) within the text are ignored while generating the ASCII version. So the LaTeX linefeed symbol (\\) can be used without any problems. To embed a literal backslash in the output, use\textbackslash{}in the DEF file. - Tilde
- To use the tilde (for example, as symbol for negation:
set_check(::'~clear':)), the following special notation must be used for the LaTeX-text:set_check(::'\~{}clear':). - Formulas
- Short formulas can be bracketed by dollar symbols ($) just as in LaTeX.
These symbols are ignored for the ASCII version of the text.
To set an index of one character (for example, Ab) LaTeX allows to simply write$A_b$. This is not possible here, because of the special underscore handling. Therefore, any index must be written exactly as any longer index within LaTeX:A_{b}. - HALCON
- The string HALCON is generated by
\Halcon. Note that in the PDF files derived from the generated LaTeX version of the DEF files, no space is generated after the string HALCON. Thus, if you do not want to start the next character/string without a blank, that is concatenated to the string HALCON, you should use\Halcon\instead. So “\Halcon XYZ” results in “HALCONXYZ” and “\Halcon\ XYZ” results in “HALCON XYZ”. With the ASCII version, all backslashes are ignored (see above). - Names of parameters and operators
- Any reference to extension package operators or their parameters must be written as
\OpRef{operator_name}, respectively as\ParRef{parameter_name}. These keywords and the brackets are ignored, when generating the ASCII version so that only operator_name or parameter_name remains in the ASCII file. In the HTML and PDF documents, hyperlinks are generated from these references. - Parameter values
- A specific value for a parameter should be written as
\ValRef{parameter_value}. For example, the parameter\ParRef{LightDark}of the operator\OpRef{dyn_threshold}can hold one of the values\ValRef{'light'},\ValRef{'dark'}, or\ValRef{'equal'}. The keywordValRefand the brackets are ignored, when generating the ASCII version so that only parameter_value remains in the ASCII file. - Paragraphs
-
If you want to divide a longer text into paragraphs to increase the readability, all you need to do is to insert an empty line between the paragraphs:
This corresponds to the standard LaTeX way of separating paragraphs; in the HTML documents, the paragraphs are enclosed with the tag
<P>. - Chapter references
- You can add a link to a certain chapter or section using
\ChapRef{chapter}or\ChapRef{chapter, section}, respectively. The chapter/section names must match the English names of an existing chapter definition, seechapter. - Formatted text
-
You can use the following LaTeX commands to format text both in the LaTeX and HTML version:
\emph{text}: results in text (HTML tag<EM>)\texttt{text}: results intext(HTML tag<TT>)\textbf{text}: results in text (HTML tag<B>)\textit{text}: results in text (HTML tag<I>)
Important
These commands cannot be nested.
- Links
-
The following special environment adds a hyperlink to the specified URL into the HTML version of the documentation. In the LaTeX version, the link text appears as plain text.
- Lists
-
You can use the following LaTeX environments to format text in lists both in the LaTeX and HTML version:
-
description lists:
-
lists with bullet points:
-
enumerated lists:
-
- Paragraph alignment
-
You can use the following special environment to specify the alignment of the included text. The parameter
formatmay be set toleft,center, orright. - Tables
-
You can use the following special environment to format text in tabular format both in the LaTeX and HTML version. This table environment is not to be confused with the standard LaTeX
tableortabularenvironment. Tables are centered by default. To change the alignment of a table, enclose it in theAlignmentenvironment (see above).Columns are separated by
&, and a new row is started with\\. Note that the last row of the table has no trailing\\.The
stylespecification (including the square brackets) is optional. The following values are available:layout: Simple table without any borders. This is the default if no table style is specified.grid: Each table cell has a border.table: The first row is formatted as the table header. The header and the bottom of the table are marked with horizontal lines.
The
formatspecification defines the number of columns, their alignment, and (optionally) their width. Each occurrence of one of the lettersl,r, orcdefines a left-aligned, right-aligned or centered column, respectively. The column specifier may be followed by a number which defines the relative width of the column in percent. Note that the alignment of a column is disregarded in the LaTeX version if the width is specified. In that case the text of the corresponding column is justified.For readability, the column specifications may be separated by commas. Extra spacing is ignored. Thus the following table specifications are equivalent:
- Other LaTeX commands
-
If you want to use additional LaTeX command within a text segment, two versions of this segment must be provided – one for ASCII (with
@asignaling the start of the ASCII section) and another as pure LaTeX text (with@lstarting the LaTeX version and@eending the special section). In particular, this technique is necessary for tables and larger formulas.
Example:This parenthesis can also be used for only one of the two text types:
In fact, the ASCII mode has two sub-modes: If
@ais immediately followed by a carriage return, the following lines are enclosed with the HTML tag<PRE>. Thus, they appear “as they come”, including all spaces and carriage returns. Otherwise, i.e., if@ais followed by any character (including a space!), carriage returns and spaces are not preserved in the HTML document.
Chapter descriptions🔗
Chapters and sections define the structuring of HALCON operators. Sometimes, it is desirable to add an introductory text to a certain chapter or section, for example, to explain some common concepts of the contained operators.
These chapter descriptions are defined at an arbitrary place in the DEF file outside of an operator description. They are linked to the corresponding chapter using a header that lists the English chapter name, and optionally the English section name:
The chapter/section names must match the English names of an existing chapter definition, see chapter.
The text of the chapter description is given within the slot abstract.
It follows the rules of the slot abstract used in the operator descriptions.
The syntax is explained in abstract.
Thus, a full chapter description looks like this:
chapter_ref Filter,Edges <- user_chapter
abstract.english
Text of the chapter description
...
;
abstract.german
...
;
...
Refer to Text in DEF files above for the special syntax of text.