2.3.1.1. esd.pm

[<<<] [>>>]

esd.pm is a Perl script that has to be placed in some of the library directories under the subdirectory jamal, so that the jamal preprocessor, which is a Perl program itself will be able to find the PM file that corresponds to the Perl command use jamal::esd;

The esd package contains Perl implemented jamal macros that are useful to include some parts of the source files into a documentation. This way not all the source file gets into the texi file, but only the text that is delimited by special comment strings and tell the macro that the have to be included.

The jamal command esd::include accepts three arguments. The first argument is the program source file name that contains the documentation to be included. The second and the third arguments should be the strings that start and stop a section from the source file to be included. The arguments are space separated.

This way a source file can easily contain TEXI documentation fragments that are included into a source file. This, however may not be enough to automatically include verbatim code sections from the document. For example you want to include the function prototype into the documentation without maintaining extra prototype definition. In other words, whenever you alter the function prototype definition in the source file, you automatically want the documentation altered recompiling the jamal to texi.

To perform this the package esd delivers the macro jamal::command. This macro gets two arguments. The first argument should be an identifier string (containing no space) that identifies the code. The second argument has to be a Perl code fragment, which can be eva'ed. When a program source file is included the commands in the order of ABC sorted by the identifier strings are evaluated holding the actual line in $_.

This construct also allows the comments to be formatted with special proprietary formatting instead of TEXI formatting codes. The advantage of this is twofold. One is the simple technical reason that the comments in ScriptBasic were already there to be extracted by a different tool that used different formatting. The other advantage is that the source code comments do not require such complex formatting as available in TEXI and thus the formatting can be simpler, shorter, and therefore more readable in their plain format. This is essential because these comments are read frequently in their source format by the programmer.


[<<<] [>>>]