# Introduction

Sooner or later, every Modula-2 programmer encounters four problems. These are: absence, incompleteness, unportability, and low quality of libraries. At the same time, C/C++ programmers usually have problems choosing from a huge set of free, public domain, shareware, and commercial libraries of various purpose, size, and quality which are in many cases portable or are available for a number of platforms. Moreover, the Application Programming Interfaces (APIs) of the most widely used software products (operating systems, database engines, etc.), are defined in terms of the C programming language.

In order to use this resources galore from Modula-2, a programmer needs, first, a Modula-2 compiler which supports C calling/naming conventions and a set of types corresponding to C types, and, second, definition modules corresponding to the C headers of the library/API. Finding a suitable compiler is not a very big deal, but manual conversion of C headers turns to a real nightmare when it comes to, say, the X Window API. That is why we created H2D.

H2D does the job automatically, i.e. translates C header files into Modula-2 definition modules. H2D is intended to be used with XDS version 2.10 or later and is included in the XDS distribution package. However, the generated definition modules may be used with any ISO-compliant Modula-2 compiler. The required modifications are minor and may be done using text editor macros or a simple REXX, sed, etc script.

The source language is a subset of ANSI C, which includes declarations and preprocessor directives, with some extensions (See Non-standard qualifiers and Chapter Project files). Destination language is ISO Modula-2 with some XDS language extensions. XDS allows to use the resulting definition modules with both Modula-2 and Oberon-2.

H2D generates definition modules suitable for either XDS-C, Native XDS, or both. In case of Native XDS, module template for function-like C macros may be generated (See Native code). In case of XDS-C, an extra header file containing C declarations of types introduced by H2D is generated (See Convertor to C).

- New in version 1.30
- Typographic conventions

## New in version 1.30

Major improvements in v1.30:

- Generalized `#variant directive`
- Custom mapping of C base types to Modula-2 types
- Non-standard directives extraction
- Options renamed to follow XDS compilers style
- Control file syntax now closely matches used by XDS compilers (see Chapters Configuring H2D and Project files)

## Typographic conventions

- Language descriptions
- Source code fragments

### Language descriptions

Where formal descriptions for language syntax constructions appear, an extended Backus-Naur Formalism (EBNF) is used.

These descriptions are set in a monospaced font.

    Text = Text [{Text}] | Text.

In EBNF, brackets `[` and `]` denote optionality of the enclosed expression, braces `{` and `}` denote repetition (possibly 0 times), and the line `|` denotes other possible valid descriptions.

Non-terminal symbols start with an upper case letter (e.g. `Statement`). Terminal symbols either start with a lower case letter (e.g. `ident`), or are written in all upper case letters (e.g. `BEGIN`), or are enclosed within quotation marks (e.g. `":="`).

### Source code fragments

When fragments of a source code are used for examples or appear within a text they are set in a monospaced font.

    /* example.h */

    typedef unsigned long int UINT;