EuGuide Documenting Euphoria

EuGuide Documenting Euphoria

EuGuide: Documenting Euphoria

I will describe a process useful for any general documentation project--that also has a few Euphoria specific advantages.

The documentation process used with Euphoria features:

• open-source software
• is the same in Windows and Linux
• allows for full creative control
• same ease of use for one page or multi-file documents
• produces choice of html or pdf final product

Two, written in Euphoria, programs, eudoc and creolehtml, will produce documentation in html format. You can see an example of their output as the Euphoria documentation found in the Euphoria Wiki. A third (open-source) program, htmldoc, may be used to convert documentation in html format to pdf format.

I will illustrate the process with a few examples.

External One Page

The first example is a one page document external to your source-code. Using any editor you write your documentation using the Creole markup language and save everything as a plain text file. The Creole markup language is the standard used to produce Wiki pages. It is easy to remember and gives you creative control of your documentation. You may specify headers, bullets, tables, formatting, ... , all without the bother of writing them out explicitly. The creolehtml program will then produce numbered headings, a table of contents, hyperlinks, ... , a complete webpage. Refer to the cheatsheet for details of the Creole markup.

Write a plain text file called hello.txt using any text edtitor. A sample would look like this:

Executing: eui creolehtml hello.txt, produces eu400_0002.htm and index.html. The documentation looks like this in a webbrowser:

Notice the automation of heading numbering, table of contents creation. Euphoria source-code syntax coloring is a special feature. If you add a style sheet, then you may alter the final result to your taste.