@example tag

This tag inserts a piece of code from source code file in the document. The code may be put in a frame with colored syntax depending on output format.

It is possible to select some code file parts by adding anchor comments in the source file ( /* anchor name */ on a single line) and specifying an anchor name pattern. All lines following a matching anchor line will be retained and other lines will be ignored. A /* ... */ comment or /* ... name */ comment in ignored file part will insert an ellipsis line.

Flags available for the @code tag can be used. Moreover, the P flag can be used to insert a code comment with path to the example file in inline code block. This behavior may be enforced for all examples with C/C++ syntax by using the show_examples_path option.

Syntax [link]

@example <path to source file>[:<label>] [<flags>] [{<scope>}] <end of line>

Examples [link]

Consider the following C source file:

/*
  Long license header
*/

                                          /* anchor global */

#include <stdio.h>

FILE *file;

int main()
{
                                          /* anchor open */
  file = fopen("foo,h", "rw");
  if (file == NULL)
    return 1;

                                          /* anchor write */
  fputs("test", file);
  /* ... */
                                          /* anchor close */

  fclose(file);
                                          /* anchor global */
  return 0;
}

To insert the whole file with line numbers:

@example path/to/file.c N

If you want to skip the header:

@example path/to/file.c:global|open|write|close

If you just want to show how to open and close a file:

@example path/to/file.c:open|close

This will result in the following code being inserted:

  file = fopen("foo,h", "rw");
  if (file == NULL)
    return 1;


  [ ... ]


  fclose(file);