OpenEuphoria: Euphoria v4.1

# OpenEuphoria Manual

## Euphoria v4.1

routine or constant name search

| Up |  |  | TOC | Index
<< 6 Mini-Guides | < 7.1 eutest Unit Testing | Up: 7 Included Tools | 7.3 Edx Demonstration Code Editor > | 8 API Reference >>

## 7.2 EuDOC Source Documentation Tool

Writing and managing documentation for your programs is made easier with the `eudoc` tool. `eudoc`, written entirely in Euphoria, converts text comments embedded in your program, as well as information about routines and identifiers, into documentation that can be saved in a variety of formats, including plain text and HTML.

Since Euphoria comments do not slow down the execution of programs, documentation written inside source-code introduces no speed penalty but is very convenient.

`eudoc` can also incorporate documentation written externally from your source-code.

You write your material using Creole style markup to format documention. This gives you creative control using elements like headers, fonts, cross-references, tables, etc. The `creole` program takes the output of `eudoc` and produces HTML-formatted documentation.

A third party program like `htmldoc` or `wkhtmltopdf` may then be used to convert HTML to PDF. `creole` will also output LaTeX files directly that can be used to create professional PDF files for online viewing or publishing.

### 7.2.1 Documentation Tags

Documentation is embedded in source-code using the Euphoria line ( -- ) comments. Two special tags, --**** and --** distinguish documentation from comments that will not be extracted.

### 7.2.2 Generic Documentation

"Generic" documentation starts with the ( --**** ) tag, continues with lines starting with -- in the first column, and ends with the next blank line. The tags and -- will not appear in the documentation.

    --****
    -- generic text, thus tagged, will be extracted by eudoc
    -- write your documentation here...
    --

    -- blank line is a terminator, this line is not included

Produces...

    generic text, thus tagged, will be extracted by eudoc
    write your documentation here...

### 7.2.3 Source Documentation

"Source" documentation starts with the ( --** ) tag. Locate them before a routine or identifier that you wish to be described in your documentation. The `eudoc` program will extract the "signature" of a routine and combines it with the comments that you write after this tag.

Starting with the source-code file `favorite.ex`:

    --**
    -- this is my favorite routine

    public procedure hello( sequence name )
       printf(1, "Hello %s!", {name} )
    end procedure

Executing `eui eudoc -o foo.txt favorite.ex` produces:

    %%disallow={camelcase}

    !!CONTEXT:favorite.ex

    @[hello|]
    ==== hello
    <eucode>
    include favorite.ex
    public procedure hello(sequence name)
    </eucode>

      This is my favorite routine.

Process with `eui creole foo.txt`:

    include favorite.ex
    public procedure hello(sequence name)

This is my favorite routine.

If you examine the source-code included with Euphoria you will realize how these steps were used to create the documentation you are reading now.

### 7.2.4 Assembly File

Large projects are managed using an assembly file, which is a list of files (source-code, and external) that will be incorporated into one output file. Look at `euphoria/docs/manual.af` for the file used to produce this documentation.

### 7.2.5 Creole Markup

Creole is a text markup language used in wikis, such as the Euphoria Wiki, and for documenting source-code.

- Common Creole tags are:

    = Title

    == Section

    //italic// **bold** ##fixed##

    * bullet
    * lists are
    * easy to produce

    ||  tables || are |
    | easy to produce |  //with bold headers// |

    <eucode>
    -- euphoria code is colorized
    for i=1 to 5 do
       ? i
    end for
    </eucode>

- The previous tags will produce html that looks like...

- - Title **
  - Section **

italic bold `fixed`

- bullet
- lists are
- easy to produce

tables | are
--- | ---
easy to produce | with bold headers

    -- euphoria code is colorized
    for i=1 to 5 do
       ? i
    end for

- More details can be found at the Euphoria Wiki under CreoleHelp.

### 7.2.6 Documentation Software

The programs required for creating documentation are hosted on our Mercurial SCM server at http://scm.openeuphoria.org.

eudoc: http://scm.openeuphoria.org/hg/eudoc

creole: http://scm.openeuphoria.org/hg/creole

More on using eudoc

More on using Creole markup

The program htmldoc is found at... http://www.htmldoc.org/ and http://htmldoc-binaries.org/.

For LaTeX on Windows, we suggest MiKTeX found at... http://miktex.org/ For those on Linux, you should be able to install via your package manager.

| Up |  |  | TOC | Index
<< 6 Mini-Guides | < 7.1 eutest Unit Testing | Up: 7 Included Tools | 7.3 Edx Demonstration Code Editor > | 8 API Reference >>