E2CR - an alternative to EuDoc for Open Euphoria embedded documentation

C A Newbould

The Open Euphoria (OE) Project proposes the use of the EuDoc procedure for including, as specific comment in a source module, embedded documentation, for subsequent extraction using suitable tools.

The author is not a fan of this approach, for a variety of reasons, but mainly because it is library-based and thus does not extend well into the documentation of other code modules.

This repository offers OE users an alternative methodology for managing documentary comment with all kinds of coding blocks.

As is the case with EuDoc, the E2CR alternative uses the creole markup to highlight, emphasise and incorporate syntax highlighting.

Annotating the source

The E2CR process scans the source code line by line.

Lines beginning with certain keywords are recognised and extracted. (Keywords can be determined by the user but default to a small set of //include//, //global//, //public// and //export//.) In the process of extraction these keywords are tagged so that they will eventually show as syntactically-highlighted code.

Any material the user wishes to add is placed in a block, signalled by an opening comment signal and closed by a matching close signal. The default signals are "--/" and "--/", respectively. Everything between these signals is added to the extraction, with any leading comment code (--) stripped off. Within this "documentation block" any valid creole code is recognised, including the "<eucode>..</eucode>" embedding feature.

On conclusion of the scan, the extracted content is filed, with the extracted lines retained in the original order.

Applications to fulfil E2CR

Two versions are provided: one via the command line and one via a GUI, based on the IUP Toolkit.

eu2cr.ex

To invoke this application, key, in a terminal window, one of:

eui e2cr --help

eui e2cr --version

for information, or:

eui e2cr

which can be followed by one or two parameters:

• the name of the file to be scanned
• (optionally) the name of a configuration file containing non-standard signal codes and keywords

or can be used, as is, in which case the application will prompt for the name of the file to be scanned.

The application carries out the scan, creates a creole file (extension .cr) and, hopefully, runs creole itself to create an html file, with the original file name, with extension, preceding the html extension. A message is issued to the terminal on a successful run. The two files are placed in the same directory as the source file, so it may be necessary to move the html one and, once satisfied with the result, delete the cr one.

eu2cr.exw

The GUI version requires that the appropriate IUP shared library is installed on the PC being used.

On calling:

eui e2cr.exw

or possibly

euiw e2cr

in MS Windows,

a dialog opens with two equal vertical partitions above two sets of buttons.

Clicking the "Open Source" button brings up the "open file" dialog; on selecting a file the contents are displayed in the left-hand edit zone of the application, in magenta, with the file name displayed above, in blue.

You can check the configuration, which displays a message-box with the details if the signals and keywords currently in operation; or you can read in an alternative configuration, of your own design - see below.

When you are satisfied that the source is the correct one, and you are happy with the contents (which are editable, but changes will not currently be saved to the source) and also that the configuration is the correct one, then selecting the "Extract documentation" button will result in the scanned source being shown in the right-habd edit zone, in red. This, too, is editable, although not, as yet, saveable. The "Create html file" button activates a call to the creole application and converts the right-hand extract into html, files it and, if successful, issues a message-box of confirmation.

Two other buttons give basic information about how to run the application and version information, respectively.

Configuration file

The format of this file is as follows: