.. ***************************** Module Header ******************************* .. .. Module Name: neprgeng.txt .. .. Source file for the programmers guide INF file of the NEPMD. .. Requires HyperText/2 package to compile. .. .. Copyright (c) Netlabs EPM Distribution Project 2002 .. .. $Id$ .. .. =========================================================================== .. .. This file is part of the netlabs.org EPM Distribution package and is free .. software. You can redistribute it and/or modify it under the terms of the .. GNU General Public License as published by the Free Software Foundation, .. in version 2 as it comes in the "netlabs\help\COPYING" file of the .. netlabs.org EPM Distribution. This library is distributed in the hope that .. it will be useful, but WITHOUT ANY WARRANTY; without even the implied .. warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .. GNU General Public License for more details. .. .. *************************************************************************** .include titleeng.inc .ti [=PRGTITLE] .hi 234 .SET CATEGORY_CONFIG=Configuration related functions .SET CATEGORY_DIVERSE=Diverse .SET CATEGORY_EAS=Extended Attribute functions .SET CATEGORY_EPMWINDOW=EPM Window related functions .SET CATEGORY_FILE=File related functions .SET CATEGORY_CHECKSUM=Checksum related functions .SET CATEGORY_INSTALL=Installation related functions .SET CATEGORY_INTERACT=User Interaction related functions .SET CATEGORY_MODE=EPM mode related functions .SET CATEGORY_NLS=National Language Support related functions .SET CATEGORY_PROCESS=Process related functions .SET CATEGORY_SYSTEM=System related functions .. ############################################################################# .1 [=PRGTITLE] .. ############################################################################# .an IDPNL_MAIN .at font='20.Tms Rmn' fc=darkgray italic bold .bitmap nllogo.bmp center .ce present the .at font='24.Tms Rmn' fc=red bold italic .ce [=DOCTITLE] .at [=TOPICS] .su 1 .. ============================================================================= .2 Extended Configuration Repository of the [=DOCTITLE] .. ============================================================================= .an IDPNL_REGISTRY . [=TOPICS] .su V30 .. ----------------------------------------------------------------------------- .3 Hierarchical namespace .. ----------------------------------------------------------------------------- .an IDPNL_REGISTRY_NAMESPACE . The [=TITLE] provides an extended configuration repository, which overcomes the limitation of *OS/2* or *eComStation* initialization files, these support only a two-dimensional namespace. Instead, very similar to a registry, the configuration repository supports a hierarchical namespace: The values are stored under pathnames instead of under key values per application, where key values are stored within containers, and where containers can contain subcontainers. This resembles very much to storing a file in a filesystem, where directories can contain subdirectories. In order to ease the usage of the repository, and in opposite to a normal registry API, the API to access the configuration repository of the [=TITLE] implicitely creates and deletes the containers implicitely, when keys are created and deleted. .. ----------------------------------------------------------------------------- .3 Explicit open/close of the repository .. ----------------------------------------------------------------------------- .an IDPNL_REGISTRY_EXPLICITOPEN . When performing multiple actions against the configuration repository of the [=TITLE], it is highly recommended to explicitely open and close the repository before and after the access. In such a case this approach saves a lot of time compared to the [.IDPNL_REGISTRY_IMPLICITOPEN], where each modification (re)opens and closes the repository, wasting much time by huge disk I/O overhead. For *[=.IDPNL_REGISTRY_EXPLICITOPEN]* the following steps must be accomplished in the following order: .ol - call [.IDPNL_EFUNC_NEPMDOPENCONFIG] to open the repository - call either .ul compact - [.IDPNL_EFUNC_NEPMDQUERYCONFIGVALUE] - [.IDPNL_EFUNC_NEPMDWRITECONFIGVALUE] - [.IDPNL_EFUNC_NEPMDDELETECONFIGVALUE] .el . to maintain the configuration values, where the handle from the call to [.IDPNL_EFUNC_NEPMDOPENCONFIG] is passed to these functions - call [.IDPNL_EFUNC_NEPMDCLOSECONFIG] to close the repository .. ----------------------------------------------------------------------------- .3 Implicit open/close of the repository .. ----------------------------------------------------------------------------- .an IDPNL_REGISTRY_IMPLICITOPEN . This approach is recommended only when a single operation against the configuration repository of the [=TITLE] needs to be performed. This saves you some code compared to the [.IDPNL_REGISTRY_EXPLICITOPEN], as you can ommit the call to [.IDPNL_EFUNC_NEPMDOPENCONFIG] and [.IDPNL_EFUNC_NEPMDCLOSECONFIG] before and after performing a call to .ul compact - [.IDPNL_EFUNC_NEPMDQUERYCONFIGVALUE] - [.IDPNL_EFUNC_NEPMDWRITECONFIGVALUE] - [.IDPNL_EFUNC_NEPMDDELETECONFIGVALUE] In this case you pass either a *zero* or an *empty string* as the handle to these functions - this will let them open and close the repository implicitely. As soon as you perform more than one action in a row, the [.IDPNL_REGISTRY_EXPLICITOPEN] is recommended instead to avoid unneccessary (re)open and close operations, which would waste much time by huge disk I/O overhead. .. ----------------------------------------------------------------------------- .3 Default keys used by the [=DOCTITLE] .. ----------------------------------------------------------------------------- .an IDPNL_REGISTRY_KEYLIST . The [=TITLE] comes with some following defaults for registry keys. The textfile shown here is used when the [=TITLE] initializes for the very first time, making the defaults available to the runtime. .at fc=red [=NOTE] .at .ul compact - This file may *not be modified* under any circumstances. Any changes may lead to unpredictable results! .fo off .textinclude ..\netlabs\bin\defaults.cfg .fo on .. ============================================================================= .2 EPM keyword highlighting support .. ============================================================================= .an IDPNL_HILITE . [=TOPICS] .su V30 .. ----------------------------------------------------------------------------- .3 Standard E toolkit keyword highlighting files .. ----------------------------------------------------------------------------- .an IDPNL_HILITE_FILES . This section descibes the format of the files that *EPM* uses to support keyword highliting. This method is used with the *EPM* of the [.IDPNL_EPMBBS EPMBBS distribution] and the *EPM* shipped with *OS/2 Warp*. As this old scheme has certain disadvantages, the [=TITLE] implements a new method to define keywords to be highlighted, and under the cover creates the hilite definition files described here. For downwards compatibility, the old scheme can still be used, provided that for a given file no *EPM mode* is defined. The keyword highlighting files are searched along the *EPMPATH* and are named *epmkwds.***. Moreover, the files must be #known# by the code in *EPM.EX*, since the names are hardcoded in the macro source file *load.e*. .. ----------------------------------------------------------------------------- .3 Format of the EPM keyword highlighting file .. ----------------------------------------------------------------------------- .an IDPNL_HILITE_FORMAT . The following rules apply to the format of the keyword highlighting files of the *EPM*: [=TOPICS] .su 1 H50 .. ............................................................................. .4 Special comment character .. ............................................................................. .an IDPNL_HILITE_COMMENTCHAR . The first character of the first line is the "special" character. If it appears at the beginning of a line after, it is either followed by a space and marks then a comment, or by any other character and is then a section name. *Example:* .fo off @ this fist line defines the 'at' character as being @ the comment char @ @ Below follows the first section: @ @KEYWORDS .fo on .. ............................................................................. .4 Section DELIM .. ............................................................................. .an IDPNL_HILITE_DELIM . The format in this section is: .fo off "start string" "bg color" "fg color" "end string" "escape character" "column" .fo on The definitions in this section are mostly used to define keyword highlighting for comments and quoted literal definitions. The following rules apply to definitions within this section: .ul compact - What's between the 'start' and 'end' delimiters is set to the 'color' color. - If no 'end' is specified, the whole line after any 'start' string is colored. - If an 'Escape' character appears just before a 'end' string, it won't be considered an end delimiter. - If an 'Escape' character appears just before a 'start' string, it won't be considered a start delimiter. - An 'Escape' character can be escaped by another 'Escape' character - If the column field is present, a start delimiter will be valid only if it starts on this column - If the end delimiter is not on the same line as the start, no color changes will be done. - The special character can be used as a placeholder, eg if you want a column but no escape character *Examples:* The following entries specify that all literals enclosed in single or double quotes are displayed in green on default backgound, where the backslash is the escape character (line in the C language syntax): .fo off @DELIM @ @ Start Color Color End Escape @ string bg fg string character " -1 2 " \ ' -1 2 ' \ .fo on The following entries specify that all C and C++ style comments are displayed in blue on default backgound. Note that C style comments are not higlighted when they are spanning mutliple lines, since the keyword hilghlighting of *EPM* does not support this: .fo off @DELIM @ @ Start Color Color End Escape @ string bg fg string character /** -1 1 **/ // -1 1 .fo on .. ............................................................................. .4 Section DELIMI .. ............................................................................. .an IDPNL_HILITE_DELIMI . This section contains identical definitions to the [.IDPNL_HILITE_DELIM section DELIM], but they are treated case insensitive. [=NOTE] .ul compact - Specifiying an escape character seems not to work properly in this section *DELIMI*. Define entries requiring an escape character in the secion [.IDPNL_HILITE_DELIM DELIM] instead! .. ............................................................................. .4 Section KEYWORDS .. ............................................................................. .an IDPNL_HILITE_KEYWORDS . The format in this section is: .fo off "start string" "bg color" "fg color" .fo on The definitions in this section define keywords to be highlighted. They must include only characters specified in the [.IDPNL_HILITE_CHARSET CHARSET] section, case sensitive. *Example:* The following entries specify some keywords to be displayed in magenta on default backgound. For that the keywords must match in case. .fo off @KEYWORDS @ ---- C pre-processor keywords ##define -1 5 ##elif -1 5 ##else -1 5 ##endif -1 5 ##include -1 5 ##if -1 5 ##ifdef -1 5 ##ifndef -1 5 ##pragma -1 5 ##undef -1 5 .fo on .. ............................................................................. .4 Section INSENSITIVE .. ............................................................................. .an IDPNL_HILITE_INSENSITIVE . This section contains identical definitions to the [.IDPNL_HILITE_KEYWORDS section KEYWORDS], but they are treated case insensitive. .. ............................................................................. .4 Section CHARSET .. ............................................................................. .an IDPNL_HILITE_CHARSET . The format in this section is: .fo off "string" .fo on The only definition in this section is a string containing all the characters that may be used in the keywords defined in the sections [.IDPNL_HILITE_KEYWORDS KEYWORDS] and [.IDPNL_HILITE_INSENSITIVE INSENSITIVE]. *Example:* The following entry specify all characters that may be used in keywords specified in the sections [.IDPNL_HILITE_KEYWORDS KEYWORDS] and [.IDPNL_HILITE_INSENSITIVE INSENSITIVE]: .fo off @CHARSET abcdefghijklmnopqrstuvwxyz__##ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 .fo on .. ............................................................................. .4 Section SPECIAL .. ............................................................................. .an IDPNL_HILITE_SPECIAL . The format in this section is: .fo off "name" "bg color" "fg color" .fo on The definitions in this section define keywords to be highlighted, just as definitions in the section [.IDPNL_HILITE_KEYWORDS KEYWORDS]. In contrast to the *KEYWORDS* section the keywords specified here can include any character. *Example:* The following entries specify special strings for the *C* language keyword highlighting to be displayed in light red on default backgound: .fo off @SPECIAL @ { -1 12 } -1 12 ; -1 12 , -1 12 ? -1 12 : -1 12 .fo on .. ............................................................................. .4 Section SPECIALI .. ............................................................................. .an IDPNL_HILITE_SPECIALI . This section contains identical definitions to the [.IDPNL_HILITE_SPECIAL section SPECIAL], but they are treated case insensitive. .. ............................................................................. .4 Section BREAKCHAR .. ............................................................................. .an IDPNL_HILITE_BREAKCHAR . The format in this section is: .fo off "character" "bg color" "fg color" .fo on The characters specified in the entries of this section are considered as a space when keywords in the sections [.IDPNL_HILITE_KEYWORDS KEYWORDS] or [.IDPNL_HILITE_INSENSITIVE INSENSITIVE] are looked for. If colors are specified, a break at the beginning of a keyword will have its own color, else it will have the same color as the keyword. *Example:* The following entries specify some break characters for the *Tex* language keyword highlighting to be displayed in the color of the keyword being used with, except for the last break character, this is always displayed in red on default backgound: .fo off @BREAK \ $ [ { -1 4 .fo on .. ............................................................................. .4 Section ENDCHAR .. ............................................................................. .an IDPNL_HILITE_ENDCHAR . The format in this section is: .fo off "character" "bg color" "fg color" .fo on The characters specified in the entries of this section are considered as a space when keywords in [.IDPNL_HILITE_KEYWORDS KEYWORDS] or [.IDPNL_HILITE_INSENSITIVE INSENSITIVE] are looked for. If colors are specified, an end char at the end of a keyword will have its own color, else it will have the same color as the keyword. An end character at the end of a keyword in [.IDPNL_HILITE_KEYWORDS KEYWORDS] or [.IDPNL_HILITE_INSENSITIVE INSENSITIVE] is hilited with its own color. *Example:* The following entry specifies an end character for the *Tex* language keyword highlighting to be displayed always displayed in red on default backgound: .fo off @ENDCHAR } -1 4 .fo on .. ............................................................................. .4 Color definitions .. ............................................................................. .an IDPNL_HILITE_COLORS . The background and foreground color values apply to the folowing scheme .pl compact bold break=none tsize=6 - -1 = transparent / default background or foreground color - 0 = black - 1 = blue - 2 = green - 3 = cyan - 4 = red - 5 = magenta - 6 = brown - 7 = palegrey - 8 = dark grey - 9 = light blue - 10 = light green - 11 = light cyan - 12 = light red - 13 = light magenta - 14 = yellow - 15 = white .. ============================================================================= .2 [=DOCTITLE] code changes .. ============================================================================= .an IDPNL_REWORKED . [=TOPICS] .su V30 .. ----------------------------------------------------------------------------- .3 Changes to the EPMBBS code .. ----------------------------------------------------------------------------- .an IDPNL_REWORKED_GENERAL . The first step before implementing new features in the *E* sourcecode of the *EPMBBS* version was to cleanup the code. This process has not been completed yet, but See the following sections for details. .. ----------------------------------------------------------------------------- .3 Remove obsolete code .. ----------------------------------------------------------------------------- .an IDPNL_REWORKED_COMPILEIF . The E code from *EPMBBS* is prepared to compile with every version of the *E Toolkit* macro compiler. Therefore the code contains many compiler directives like .fo off compile if EVERSION > 6 ... compile elseif EVERSION > 5 ... compile else ... compile endif .fo on Because of the historical growth, some sections are not readable anymore. Within the [=TITLE], all code has been removed that is not designed for EPM 6.03b. If you want to clean-up your own code, see the beginning of STDCONST.E for the meaning of the constants. .. ----------------------------------------------------------------------------- .3 Maintain small file sizes .. ----------------------------------------------------------------------------- .an IDPNL_REWORKED_SMALLFILES . Some *E* source files of the *EPMBBS* version have a quite unhandy size to find code therein. Especially the std**.e files are unsorted and not easy to read in. This is probably caused by the limits of ancient *E*/*EPM* versions. We decided to start creating smaller files, where the code concerning with similar themes is collected. See locate.e for an example. The file stdctrl.e could be reduced from 5600 to 4000 lines (yet to do). .. ----------------------------------------------------------------------------- .3 Replace configuration constants .. ----------------------------------------------------------------------------- .an IDPNL_REWORKED_CONSTANTS . For future versions of the [=TITLE] it is planned to replace all configuration constants with dynamic values, being stored within the *extended configuration repository* of the [=TITLE] (and making them configurable by a GUI later). This will hopefully make all recompilations of *EPM* obsolete. .. ============================================================================= .2 E Language functions of the [=DOCTITLE] .. ============================================================================= .an IDPNL_EFUNC . The following E language functions are provided by the [=TITLE]: .include ..\..\compile\functions.txt