OpenEuphoria

eudoc creole - Source Documentation Tools

Two tools, written in Euphoria---eudoc.ex and creole.ex---make writing and managing documentation easier. They are used to produce HTML and PDF documentation for the OpenEuphoria project.

There is a lot of flexibility in how documentation can be written. Documentation is written using the creole markup language which provides many features such as: titles and sections, lists, tables, callout notes, cross-links, and font effects.

eudoc.ex lets you:

• Write documentation in a plain text file.
• Write documentation within source-code.
• Combine documentation written in scattered files into one text file.

creole.ex converts creole formatted text to:

• Produce HTML documentation.
• Produce LaTeX documentation.
• Produce PDF documentation using third-party software.
• Provides formatting, indexing and cross links.

Creole in general is a text markup language popular as a simple way to format wiki content. The OpenEuphoria wiki and forum will accept creole formatted text. It is an equally simple and convenient way of formatting Euphoria documentation.

Documentation Software

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

1. eudoc: http://scm.openeuphoria.org/hg/eudoc
2. creole: http://scm.openeuphoria.org/hg/creole

Creole.ex can produce LaTeX formatted documentation, which in turn requires:

• On Windows try MiKTex found at: http://miktex.org/
• On Unix try installing LaTeX using your package manager.

Creole.ex by default produces HTML formatted documentation, which can be viewed directly in any web browser. Third-party software can convert this HTML into a PDF document. Two open-source choices for Windows or Unix are:

• htmldoc found at http://www.htmldoc.org/ and http://htmldoc-binaries.org/
• wkhtmltopdf found at http://code.google.com/p/wkhtmltopdf

The htmldoc program has a convenient GUI but produces plain PDF. The wkhtmltopdf program is a command-line program that can use a style.css file to customize the look of the PF.

Look at the Euphoria source-code distribution as an example of how documentation may be written:

• Euphoria: http://scm.openeuphoria.org/hg/euphoria
• For example, this section is produced from the file euphoria/docs/eudoc.txt.

Additional information may be found at:

• More on using eudoc
• More on using Creole markup

Hint

After downloading the source-code for eudoc and creole the most convenient way to use them may be to compile them with euc. The executables can then be copied to your working directory, or even to /euphoria/bin.

Creole Formatting

The simplest form of documentation is plain text file that accompanies your project. A example of formatted text using common elements:

---

== Section -- Creole Demo 
 
//italic// **bold** ##fixed## __underline__ 
 
* 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> 
 
Learn more about creole from the www.wikicreole.org website. 

---

Copy the previous text into a file called test.txt and execute eudoc:

eudoc test.txt -o foo.txt 

You must explicitly specify the output file as -o foo.txt (the actual name is not critical.) (In this example the input and output files look almost identical because this is only a simplistic example.)

The output of the eudoc program is the used by the creole program:

creole foo.txt 

The default file produced is test_txt.html which when viewed in a web browser will look like:

---

Section -- Creole Demo

italic bold fixed underline

• 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 

---

Executing creole as:

creole foo.txt -f LaTeX 

produces a LaTeX file, which when processed by the LaTeX program produces a PDF file. Alternatively a PDF could be produced by:

wkhtmltopdf test_txt.html mypdf.pdf 

Creole is a text markup language used in wikis, such as the Euphoria Wiki, and for documenting source-code. Learn more about creole from the www.wikicreole.org website. From there you can download a cheatsheet www.wikicreole.org/wiki/CheatSheet which will help when learning Creole.

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

Documentation tags

Documentation can be written within Euphoria source-code using the regular - - comment markers starting in the first column. Documentation must be written as a block of comments starting with a special tag and ending with a blank line. The eudoc program can then extract the text in these comment blocks for use by the creole program.

Documentation is embedded in source-code using the Euphoria line comment. There are two kinds of starting tags:

--****         <== start of general documentation tag 
 
--**           <== start of special source documentation tag  
                -- extract the signature of the subroutine that 
                -- immediately follows this comment block                  

Hint

The eudoc program primarily extracts text from source-code. Creole formatting is not required; thus eudoc could be used to produce simple plain text documentation if you wish.

General Documentation

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

--**** 
-- general text, thus tagged, will be extracted by eudoc 
-- write your documentation here... 
-- 
 
-- blank line is a terminator, this line is not included 

Produces:

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

Source Documentation

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

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 Euphoria source-code will appreciate how these steps were used to create the documentation you are reading now.

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.

######## 
:%%output=eu_intro 
:= Euphoria Programming Language v4.0 
:@[toc|] 
:<<LEVELTOC level=1 depth=4>> 
 
../docs/welcome.txt 
../docs/whatsnew4_0.txt 
../docs/licensing.txt 
 
# General Routines 
../include/std/cmdline.e 
../include/std/console.e 
../include/std/datetime.e 

A portion of the manual.af file used to produce the Euphoria documentation. Lines starting with # are just comment lines. Lines starting with : are used by the creole program. In this sample := is marks a chapter title, <<LEVELTOC... inserts a table of contents for that chapter.

The remaining lines are filenames that are read by eudoc and used to assemble the final documentation file. Plain text files and Euphoria source-code may be used as starting documents. The filenames will include directory information relative to the location of the assembly file.