OpenEuphoria

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

-- 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.