.. ***************************** Module Header ******************************* .. .. Module Name: makefile.txt .. .. Source file for the INF file providing help for makefile .. Requires HyperText/2 package to compile .. .. Unlike the nepmd.inf, the makefile.inf is compiled to the bin subdirectory .. and checked in to make it always available right after checking out. .. .. So when updating this file, commit also the changed INF file! .. .. Copyright (c) Netlabs EPM Distribution Project 2002 .. .. $Id$ .. .. =========================================================================== .. .. This file is part of the Netlabs 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 "COPYING" file of the .. Netlabs 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. .. .. *************************************************************************** .hi 234 .include titleeng.inc .set TITLE=*[=DOCTITLE]* .set STDLIST=compact break=fit tsize=20 .ti [=DOCTITLE] .. ============================================================================= .1 Making of [=DOCTITLE] .. ============================================================================= .an IDPNL_OVERVIEW . .at font='20.Tms Rmn' fc=darkgray italic bold .bitmap bmp\nllogo.bmp center .ce present the Making of .at font='24.Tms Rmn' fc=red bold italic .ce The [=DOCTITLE] .at [=TOPICS] .su 1 .. ----------------------------------------------------------------------------- .2 Requirements .. ----------------------------------------------------------------------------- .an IDPNL_REQUIREMENTS . The following is required for making [=TITLE]: .su V30 [=NOTE] .ul compact .at hi - Any makefile processing will check for all required packages to be available and abort if anything is missing on your system! .at .. ............................................................................. .3 Long filename support .. ............................................................................. .an IDPNL_REQUIREMENTS_LONGFILENAME . This project requires long filename support (e.g. HPFS and JFS). .. ............................................................................. .3 WarpIN .. ............................................................................. .an IDPNL_REQUIREMENTS_WARPIN . The *WarpIN* Installer is used to create the installation package. As a minimum version 0.9.19 is required. [=NOTE] .ul - You can download *WarpIN* from - [http://warpin.netlabs.org/?show=download WarpIN home page (warpin.netlabs.org)] - Makefile processing will extend the environment automatically to access the *WarpIN* executables, so it is not required to make them accessible via the PATH or LIBPATH statements. .. ............................................................................. .3 C Compiler .. ............................................................................. .an IDPNL_REQUIREMENTS_COMPILER . As compiler the following are supported .ul compact - *IBM VAC 3.08* (much better debugger). - *IBM C Set/2* (debugger seems not to cope with the debug version...) [=NOTE] .ul compact - The compiler used is automatically recognized by the makefile. .. ............................................................................. .3 Toolkit for OS/2 Warp .. ............................................................................. .an IDPNL_REQUIREMENTS_TOOLKIT . As toolkit, one of the following is required: .ul compact - *OS/2 Warp 3 Developer's Toolkit* - *OS/2 Warp 4 Developer's Toolkit* - *OS/2 Warp 4.5 Developer's Toolkit* [=NOTE] .ul - Some 5.xx versions of *RC.EXE* are quite buggy and cause problems. Therefore you have to replace the *RC.EXE*, that comes with Toolkit 4.5x. Older versions are usually OK to compile NEPMD. . - The most recommended *RC.EXE* version is 5.00.007. It can be found here: - [http://www.os2bbs.com/os2news/rcos2-5.00.007.zip] . - As an alternative, you can use the Toolkit 4 version of *RC.EXE*, as recommended by the Warpzilla project: - [ftp://ftp.software.ibm.com/ps/products/warpzilla/os2tk40rc.zip] . - Or rename bin\rc16.exe to rc.exe. That one works without the message file, but is the 16 bit version. The version, that comes with Warp 4.x and with eCSMT is also a 16 bit version and should work as well. .. ............................................................................. .3 EPM Macro Compiler .. ............................................................................. .an IDPNL_REQUIREMENTS_ETPM . The *EPM Macro Compiler* is required to compile the *RECOMP* macro. [=NOTE] .ul compact - You can download the program file *etpm.exe* as part of the *EPM base application* package zip file (no other files of this package are required) - [http://hobbes.nmsu.edu/h-search.php?key=epmapp The Hobbes File Archive] . (search "epmapp" at hobbes.nmsu.edu) . - *etpm.exe* must be accessible by the PATH statement. .. ............................................................................. .3 PKUNZIP2 .. ............................................................................. .an IDPNL_REQUIREMENTS_PKUNZIP2 . *PKUNZIP2* is required in order to unpack certain parts of the EPMBBS packages, as it supports the shrink method, this is not supported by some versions of *Info-Zip* before UNZIP 5.52 of 2005. As *pkunzip2.exe* comes as part of *MPTS*, it is available on OS/2 Warp Systems with Network or Internet Access Kit installed. .. ............................................................................. .3 UNZIP.EXE of Info-Zip .. ............................................................................. .an IDPNL_REQUIREMENTS_UNZIP2 . *UNZIP* is required in order to unpack certain parts of the EPMBBS packages, as it supports the "deflated" method used for some text files, this is not supported by [.IDPNL_REQUIREMENTS_PKUNZIP2]. [=NOTE] .ul - You can download *unzip* from - [http://hobbes.nmsu.edu/h-search.php?key=unz+x2.exe The Hobbes File Archive] . (search "unz x2.exe" at hobbes.nmsu.edu) - *unzip.exe* must be accessible by the PATH statement. .. ............................................................................. .3 WGET .. ............................................................................. .an IDPNL_REQUIREMENTS_WGET . *wget* is used to download the original zip files, if not present (currently tested with wget v1.7). [=NOTE] .ul - You can download *wget* from - [http://hobbes.nmsu.edu/h-search.php?key=wget The Hobbes File Archive] . (search "wget" at hobbes.nmsu.edu) - *wget.exe* must be accessible by the PATH statement. - When sitting behind a firewall, create/modify a wget resource file in order to use an FTP proxy. Insert or add the following entries to the file %home%\.wgetrc and replace the bold printed values as required: .fo off ftp__proxy=http://*proxyname*:*proxyport* proxy__user=*proxy__userid* proxy__passwd=*proxy__password* .fo on .. ............................................................................. .3 HyperText/2 .. ............................................................................. .an IDPNL_REQUIREMENTS_HTEXT . For compilation of the online help the preprocessor *HyperText/2* is used. . . Version 2.0 or later is required. [=NOTE] .ul - You can download *HyperText/2* from - [http://hobbes.nmsu.edu/h-search.php?key=htext The Hobbes File Archive] . (search "htext" at hobbes.nmsu.edu) - Install according to the information in htext.inf. .ul compact - *htext.cmd* must be accessible by the PATH statement. - The bitmap files ***.bmp* must be placed either - into the same directory where *htext.cmd* is located - into a subdirectory *htext* or *bmp* within the directory where *htext.cmd* is located - into a directory specified by either of the environment variables - *INCLUDE* - *HTINCLUDE* .. ............................................................................. .3 REXX2EXE .. ............................................................................. .an IDPNL_REQUIREMENTS_REXX2EXE . For converting a REXX script to an executable the *REXX2EXE* compiler us used. [=NOTE] .ul - You can download *REXX2EXE* from - [http://hobbes.nmsu.edu/h-search.php?key=rexx2exe The Hobbes File Archive] . (search "rexx2exe" at hobbes.nmsu.edu) - *rexx2exe.exe* must be accessible by the PATH statement. .. ............................................................................. .3 FASTDEP .. ............................................................................. .an IDPNL_REQUIREMENTS_FASTDEP . For creating dependency files the FastDep utility is used. [=NOTE] .ul - You can download *FastDep* from the *XWorkplace* project being hosted on the *Netlabs CVS Archive Server*. Get the *XWPHelpers* project files with a CVS client. A binary is contained in the *xwphelpers* directory. - As an alternative, download a snapshot from - [ftp://ftp.netlabs.org/pub/snapshots/xwphelpers Netlabs ftp server] . (go to ftp://ftp.netlabs.org/pub/snapshots/xwphelpers) - *fastdep.exe* must be accessible by the PATH statement. .. ............................................................................. .3 GREP .. ............................................................................. .an IDPNL_REQUIREMENTS_GREP . For checking unpacked EPM files the *grep* utility is used. [=NOTE] .ul - The *grep* utility is only required if you run *src\wis\makefile* with pseudo target *check*. It is not mandatory in order to create the package itself. - You can download *Grep v2.0* from - [http://hobbes.nmsu.edu/h-search.php?key=grep20 The Hobbes File Archive] . (search "grep20" at hobbes.nmsu.edu) .el . This version has the advantage that it does not require the *EMX* runtime. - Any other version of *Gnu grep* should work as well, if a recent version of *EMX* runtime is installed. (BTW: since v2.5 recursive search is possible.) - The IBM version, contained in the CSTEPM package, doesn't work. - *grep.exe* must be accessible by the PATH statement. .. ............................................................................. .3 LXLITE .. ............................................................................. .an IDPNL_REQUIREMENTS_LXLITE . For packing the executables of the [=TITLE], the *lxlite* utility is used. [=NOTE] .ul - The *lxlite* utility is only required if you build the release version of the [=TITLE] executables, which is the default. In order to build the debug versions instead, either .ul compact - specify *DEBUG=1* as parameter to *nmake* or - set the environment variable *DEBUG=1* before calling *nmake*. - You can download *lxlite* from - [http://hobbes.nmsu.edu/h-search.php?key=lxlt The Hobbes File Archive] . (search "lxlt" at hobbes.nmsu.edu) - *lxlite.exe*, together with its *lxlite.cfg* must be accessible by the PATH statement. .. ............................................................................. .3 TOUCH .. ............................................................................. .an IDPNL_REQUIREMENTS_TOUCH . For aligning the timestamps of the compiled files before they were packed into the WarpIN package the *touch* utility out of the *GNU file utilities* is used. [=NOTE] .ul - The *touch* utility is only required if you adjust the timestamps. In order to do that, either .ul compact - specify *TOUCH=1* as parameter to *nmake* or - set the environment variable *TOUCH=1* before calling *nmake*. - You can download the *GNU file utilities* from - [http://hobbes.nmsu.edu/h-search.php?key=GNU+file+utilities The Hobbes File Archive] . (search "GNU file utilities" at hobbes.nmsu.edu) .el (this packages requires the EMX runtime DLLs being installed) - or use a more complete and more recent *GNU core utilities* package from - [http://hobbes.nmsu.edu/h-search.php?key=coreutils The Hobbes File Archive] . (search "coreutils" at hobbes.nmsu.edu) .el together with the required Libc runtime DLL (libc**.dll). Libc DLLs can be found as installable WPI packages at the - [ftp://ftp.netlabs.org/pub/gcc netlabs.org FTP-Server] . (e.g. ftp://ftp.netlabs.org/pub/gcc/libc-0__6__3-csd3.wpi) - *touch.exe* must be accessible by the PATH statement. .. ----------------------------------------------------------------------------- .2 Development tree overview .. ----------------------------------------------------------------------------- .an IDPNL_DEVTREE . The following directories currently exist in the SVN development tree: . (The *SVN* maintenance directories are not included here.) .pl compact break=none tsize=18 .fo off ³ ÃÄbin helpers and documentation for compilation ³ ÀÄsrc .lm 3 ³ ÃÄdoc several additional docs ³ ÃÄannounce ³ ÃÄtestfiles ³ ÀÄwse2002 ³ ÃÄgui GUI and other files for compilation ³ ÃÄcommon ³ ÃÄepmcall EPM loader ³ ÃÄetk E Toolkit header files ³ ÃÄnepmdlib NEPMD library ³ ³ ÀÄmacros E macros as interface for the library (not shipped in the release) ³ ÃÄrecomp Recomp utility ³ ³ ÀÄtestcase ³ ÀÄtest ³ ÃÄheader GNU headers for all used filetypes ³ ÃÄipf HyperText/2 sources for the NEPMD INF files ³ ÀÄbmp bitmaps for INF files ³ ÃÄ[=DISTDIR] base directory for sources simply copied to compile\[=DISTDIR] ³ ÃÄbar toolbars ³ ÃÄbin binary and executable files ³ ÃÄbmp toolbar bitmaps ³ ÃÄdll dlls ³ ÃÄex LST files used by toolbar macros and RecompileNew ³ ÃÄinstall installation related files ³ ³ ÀÄico NEPMD related icons for installation ³ ÃÄmacros E macros ³ ÃÄmode definition files for keyword highlighting ³ ³ ÃÄ ³ ³ ÀÄ ³ ÀÄndx keyword help files ³ ÃÄnls base directory for all NLS files ³ ÃÄnetlabs ³ ³ ÀÄbin Text Message File ³ ÃÄrecomp NLS files for Recomp ³ ÀÄwis NLS files for building the WarpIN package ³ ÃÄold unused files - for comparison only ³ ÃÄrexx installation files being executed after unpacking ³ (these files are converted to EXE files to avoiding ³ the annoying VIO window being popupped otherwise) ÃÄstatus outdated project status list ³ ÀÄdb ³ ÀÄwis WarpIN package creation files .lm .. .fo on The following #temporary# directory trees are created when building the *WarpIN* package: .fo off ³ ÃÄcompile holds temporary files being the same for debug or ³ ³ release version ³ ÃÄbase ³ ³ ÀÄ[=DISTDIR] directory tree to be packed into the WarpIN package ³ ÃÄepmcall ³ ³ ÀÄ[=DISTDIR] directory tree to be packed into the WarpIN package ³ ÀÄrecomp ³ ÀÄ[=DISTDIR] directory tree to be packed into the WarpIN package ³ ÀÄ the name of this directory is either *debug* or .lm 3 ³ *release* (among others it holds the resulting ³ WarpIN package file) ÃÄbase ³ ÀÄ[=DISTDIR] directory tree to be packed into the WarpIN package ÃÄepmcall ³ ÀÄ[=DISTDIR] directory tree to be packed into the WarpIN package ÀÄrecomp .lm 5 ÀÄ[=DISTDIR] directory tree to be packed into the WarpIN package .lm .fo on [=NOTE] .ul compact - The temporary directory trees, except *zip* and *epm.packages*, can be completely cleaned up (deleted) with executing *nmake clean* in the working root directory. Other directories used during a build are determined by the environment variables *%ZIPSRCDIR%* and *%UNZIPPEDDIR%*: .fo off *%ZIPSRCDIR%* holds downloaded EPMBBS ZIP files. The default for *%ZIPSRCDIR%* is \zip. *%UNZIPPEDDIR%* holds unpacked EPMBBS files before they were added to the WarpIN package. The default for *%UNZIPPEDDIR%* is \epm.packages .fo on .. ----------------------------------------------------------------------------- .2 Configuring the make process .. ----------------------------------------------------------------------------- .an IDPNL_CONFIGMAKE . [=TOPICS] .su V30 .. ............................................................................. .3 Setting up the build environment .. ............................................................................. .an IDPNL_CONFIGMAKE_SETENV . The easiest way to configure a build environment is to use a CMD file whilch contains the appropriate commands. The easiest way to create such a command file is to have it created for you. This can be done by: .ol compact - Execute: SET USED__COMPILER=abc. (This is an "incorrect" value which will trigger the automatic CMD file creation process in step 2.) - Run \bin\setenv.cmd. - You will be asked if you want to create this CMD file. - If you indicate you want the CMD file, you will be prompted for a variety of settings. At the end a file named *mysetenv.cmd* will be created for you in the base directory of the project. Once you have a CMD file with the appropriate settings just run it before trying to build NEPMD. [=NOTE] .ul compact - If you want to build your own CMD file or if you are just curious about the settings, .ol compact - Use the process above to create *mysetenv.cmd* - Read *mysetenv.cmd*. It is fairly well documented internally. - If you want to change the settings in *mysetenv.cmd* you can edit it directly or can just repeat the procedure above for creating *mysetenv.cmd*. - *DO NOT EDIT* any of the files in the \bin directory. .. ............................................................................. .3 General settings in configure.in .. ............................................................................. .an IDPNL_CONFIGMAKE_CONFIGUREIN . The *src\wis\makefile* requires several values, some of which have to be configured before executing *nmake* to build the complete package. [=NOTE] .ul compact - If you use [.IDPNL_CONFIGMAKE_SETENV *mysetenv.cmd*], then all of the following values will be set for you. So you will not need to edit the configure.in file. ...................................... Values which may be configured by anyone or can be predefined via an environment variable. .pl break=none tsize=3 . .pl bold - BASEURL = specifies the location where the original ZIP files of the EPMBBS package (epm603b.zip and epm603bupd.zip) can be downloaded. The default .. is ftp://hobbes.nmsu.edu/pub/os2/apps/editors/epm. is http://hobbes.nmsu.edu/download/pub/os2/apps/editors/epm. . - ZIPSRCDIR = specifies a local directory where the zip files from *BASEURL* will be saved. If the zip files are already present in this directory, then a download from *BASEURL* will not be necessary. . - UNZIPPEDDIR = specifies a local directory where the unpacked zip files will be placed. The default is *epm.packages* under your project base directory. . .el [=NOTE] .ul compact - You can predefine *BASEURL*, *ZIPSRCDIR* and *UNZIPPEDDIR* with environment variables. These environment variable settings override any settings in configure.in. - The parent directories of *ZIPSRCDIR* and *UNZIPPEDDIR* must exist. - *ZIPSRCDIR* and *UNZIPPEDDIR* will be created during a build if they do not already exist. - Do not use *UNZIPPEDDIR* for other files. Any files in that directory are deleted before unpacking the EPMBBS package files. .. .. Values to be configured by release maintainer only .................................................... . .pl bold - STEM = specifies the id of the project, used within some filenames. - VERSION = specifies the current version, used in the name of the WPI package file. - ID__VERSION__NEPMD = specifies the current version and revision as to be used within the *WarpIN* script. . . [=NOTE] .ul compact - Keep in sync with the major and minor version used in *VERSION*! - This value has to be specified in the *WarpIN* package ID style: \\ .el - ID__VERSION__REQ__WARPIN = specifies the version and revision of *WarpIN* that the resulting WPI package should be restricted to as a minimum for installation. . . [=NOTE] .ul compact - This value has to be specified in the *WarpIn* package ID style: \\ .el . .. ----------------------------------------------------------------------------- .2 Makefile pseudo targets .. ----------------------------------------------------------------------------- .an IDPNL_TARGETS . [=TOPICS] .su V30 .. ............................................................................. .3 Main makefile .. ............................................................................. .an IDPNL_TARGETS_MAIN . This section describes the makefile pseudo targets that are available for the main makefile within the project base directory (root of the development tree). [=NOTE] .ul compact - Ensure your environment is properly set for a build. See [.IDPNL_CONFIGMAKE_SETENV] for more information. - Targets marked with (**) require a working internet connection if the EPM zip files are not available within the directory specified by the *ZIPSRCDIR* environment settings. The following pseudo targets are available: .pl bold compact break=none tsize=20 - nmake all = Build all modules and thus the complete package. (**) . . This is achieved by calling all makefiles below the *src* subdirectory, of which the subdirectories are listed in the macro *MODULELIST*. . . This results in the *WarpIN* WPI package file created either in the *debug* or *release* directory, depending on the value of the *DEBUG* environment variable. (**) . - nmake inst = Like *nmake all*, but also starts the installation of WPI file. (**) . - nmake remove = Quickly deinstalls all packages installed from the [=TITLE] without using the *WarpIN* GUI. This is intended for testing purposes only! . [=NOTE] .ul compact - The revision numbers from the *WarpIN* script are ignored, but the vendor name, package name and component name must match exactly. - All files and WPS objects are removed. - No *INI* entries or *CONFIG.SYS* entries are removed. - No dependencies are checked! . - nmake gui = Build GUI components only. - nmake rungui = Build and run selected GUI components. . - nmake inf = Build all INF files of the whole project. - nmake show = Build NEPMD INF only and show it. . - nmake clean = Remove the *compile* and binary (both *debug* and *release*) directories. . - nmake [[help]] = Show this INF file (the INF is compiled first if it is outdated). This calls the makefile within the *src\ipf* directory with the target *showhelp*. . - nmake NLS [[NLS=xxx]] = . (Re)set NLS language identifier to default or the specified [.IDPNL_APPENDIX_LANGIDS three letter language identifier]. To make things easier, the makefile allows also to set the language identifier by just specifying the symbol *NLS=xxx* without any target. . [=NOTE] .ul compact - This is only intended for testing purposes, as normally the language information for [=TITLE] is set by running the installation package of it. .. ............................................................................. .3 src\ipf\makefile .. ............................................................................. .an IDPNL_TARGETS_IPF . The following makefile pseudo targets are available for the makefile within the *src\ipf* subdirectory: .pl bold compact break=none tsize=20 - nmake [[all]] = Build both the makefile INF and the project documentation INFs, but show none. . - nmake showhelp = Build and show this INF file (if outdated, this compiles the INF before). This is used by the [.IDPNL_TARGETS_MAIN main makefile] in order to bring up help if called with no target specified. - nmake neusr = Build and show the user guide INF. - nmake neprg = Build and show the programming guide INF. - nmake nefld = Build and show the folder HLP. . - nmake helpinf = Build this makefile in the *bin* subdirectory! - nmake neusrinf = Build the user guide INF in the *compile\netlabs\book* directory. - nmake neusrinf = Build the programming guide INF in the *compile\netlabs\book* directory. - nmake nefldhlp = Build the folder HLP file in the *compile\netlabs\help* directory. . - nmake clean = Remove the files created by this makefile. See the macro *FILESTOCLEAN* for a complete list. . [=NOTE] .ul compact - Directories are not removed by this pseudo target. For a complete cleanup, call *nmake clean* within the project working directory (root of the development tree). .. ............................................................................. .3 src\rexx\makefile .. ............................................................................. .an IDPNL_TARGETS_REXX . The following makefile pseudo targets are available for the makefile within the *src\rexx* subdirectory: .pl bold compact break=none tsize=20 - nmake [[all]] = Create POSTWPI.EXE in the *compile\netlabs\install* directory. . - nmake clean = Remove the file created by this makefile. See the macro *FILESTOCLEAN* for a complete list. . [=NOTE] .ul compact - Directories are not removed by this pseudo target. For a complete cleanup, call *nmake clean* within the project working directory (root of the development tree). .. ............................................................................. .3 src\netlabs\makefile .. ............................................................................. .an IDPNL_TARGETS_NETLABS . The following makefile pseudo targets are available for the makefile within the *src\netlabs* subdirectory: .pl bold compact break=none tsize=20 - nmake [[all]] = Copy all modified files below the *src\netlabs* directory to the *compile\netlabs* directory. . - nmake checksrc = Check only if some files have been modified. If not, the flag file *compile\srccopy.txt* is created, otherwise it is deleted. - nmake srccopy = Copy modified files anyway. . - nmake clean = Remove the flag file created by this makefile. See the macro *FILESTOCLEAN* for a complete list. . [=NOTE] .ul compact - Directories are not removed by this pseudo target. For a complete cleanup, call *nmake clean* within the project working directory (root of the development tree). .. ............................................................................. .3 src\wis\makefile .. ............................................................................. .an IDPNL_TARGETS_WIS . .at fc=red This makefile cannot be called directly. .at Instead it can only be processed by calling the main makefile by executing .sl compact - *nmake all* in the project base directory. This ensures that all other makefiles from within the *src* directory are called first which in turn ensures that all required files are available for building the WPI package. For testing purposes this makefile can called directly by specifying the symbol *CALLED=1*. The pseudo targets provided by *[=.IDPNL_TARGETS_WIS]* are described below. [=NOTE] .ul compact - Targets marked with (**) require a working internet connection for to download the EPM packages, if they are not available within the directory specified by the macro *ZIPSRCDIR* in the file *configure.in*. .at .pl bold compact break=none tsize=20 - nmake [[all]] = Downloads and unpacks files from Hobbes and builds complete Warpin package. This results in the *WarpIN* WPI package file created either in the *debug* or *release* directory, depending on the value of the *DEBUG* environment variable. (**) . - nmake inst = Like *nmake all*, but also starts Warpin to install the WPI file. (**) . - nmake remove = Quickly deinstalls all packages installed from the [=TITLE] without using the *WarpIN* GUI. This is intended for testing purposes only! See pseudo target *remove* of the [.IDPNL_TARGETS_MAIN] for further details. . - nmake prepare = Only downloads EPMBBS zip files from Hobbes and unpacks. (**) . - nmake check = Check prepared files for .ul compact - SYSxxxx errors during unpack - zero byte files, making WIC trap (fixed in newer WarpIN versions) - pkunzip2 does not unpack properly sometimes (zero byte files). .el - nmake clean = Remove the flag file created by this makefile. See the macro *FILESTOCLEAN* for a complete list. . [=NOTE] .ul compact - Directories are not removed by this pseudo target. For a complete cleanup, call *nmake clean* within the project working directory (root of the development tree). .include guide.inc .. ----------------------------------------------------------------------------- .2 Appendix: INI entries overview .. ----------------------------------------------------------------------------- .an IDPNL_APPENDIX_INIENTRIES . [=TOPICS] .su V30 .. ............................................................................. .3 OS2.INI .. ............................................................................. .an IDPNL_APPENDIX_INIENTRIES_OS2INI . The following entries are written to *OS2.INI*: .pl bold compact tsize=15 break=none .. ------------------------------------------- - Application: = NEPMD - Key: = Language ..= ...pl compact bold break=none tsize=10 - Description = language information used by several programs - Originator = installation of [=TITLE] - Value = a [.IDPNL_APPENDIX_LANGIDS three letter language identification] - Type = alpha string (should be zero terminated) ...el . .. ------------------------------------------- - Application: = NEPMD - Key: = RootDir ..= ...pl compact bold break=none tsize=10 - Description = main installation directory used by several programs - Originator = installation of [=TITLE] - Value = a directory specification - Type = alpha string (should be zero terminated) ...el . .. ------------------------------------------- - Application: = recomp - Key: = CONFIGDATA ..= ...pl compact bold break=none tsize=10 - Description = configuration data - Originator = *RECOMP* utility - Value = internal - Type = binary ...el .. ----------------------------------------------------------------------------- .2 Appendix: Language identifiers overview .. ----------------------------------------------------------------------------- .an IDPNL_APPENDIX_LANGIDS . The following language identifiers are currently used within the project: .lm 5 .pl bold compact break=none tsize=7 - eng = english - deu = deutsch (german) .. ----------------------------------------------------------------------------- .2 Appendix: Documentation comments for E functions .. ----------------------------------------------------------------------------- .an IDPNL_APPENDIX_DOCCOMMENTS . [=TOPICS] .su V30 .. ............................................................................. .3 Doc comments in general .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_GENERAL . All E functions provided by the [=TITLE] should be documented in the E functions reference of the INF file for the release package. In order to have this task accomplished, the following is required: .pl bold tsize=3 - the information to be put into the panels of the INF file = this information has to be provided by the developer of the function within the .e source file within so-called documentation comments - the generation of the panels into an appendix of the INF file = this is done by the script *escansrc.cmd*, which is called by the makefile generating all of the online help files. Having said this, once a developer has added the documentation comments to the respective source file [.IDPNL_APPENDIX_DOCCOMMENTS_FORMAT in correct format], the information about the function is automatically inlcuded in the functions reference. .. ............................................................................. .3 Format of doc comments .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_FORMAT . The following rules apply to documentation comments: .ul - All documentation comments have to be embedded into comments for the E language, so that the *EPM macro compiler* does not see them. - For each function a set of documentation comments have to be defined, some others are optional. If required documentation comments are missing, the script reading them will display warnings when generating the reference information, but will not stop. - A documentation comment consists of the following: .ul compact - one line specifying the name of the function. This line must have the following information in one word (without spaces included!): - two *@* characters - the name of the function - one *@* character - the type name of the comment (like [.IDPNL_APPENDIX_DOCCOMMENTS_SYNTAX], [.IDPNL_APPENDIX_DOCCOMMENTS_PARM], .etc.) .el . For special comment types like [.IDPNL_APPENDIX_DOCCOMMENTS_CATEGORY] and [.IDPNL_APPENDIX_DOCCOMMENTS_PARM] another *@* character and an additional parameter (here either the category name or the name of the parameter) must be appended. Please see the descriptions about the comment types in this section for details. .el - All following lines up to the next documentation comment used as text for the INF file panel. .at fc=red This text must conform to the [.IDPNL_REQUIREMENTS_HTEXT] syntax, as this preprocessor is used for generation the online help. .at fc=black - Especially important is to take care for the characters ** __ ## [[ ]], as they are escape characters for *HyperText/2*. They to switch bold, underline and italic print of characters on and off and they create hyperlinks. In order to use those characters within the documentaion comments just repeat the character, as each escape character escapes itself. - Also make sure that no line begins with a dot, because that may be interpreted as a HyperText command. - To print text in non-formatted style, you may want to use the .FORMAT command of HyperText/2, switching formatting off and later on again. .at - The documentation comment is closed with the [.IDPNL_APPENDIX_DOCCOMMENTS_ENDMARKER], which is a line made up of two *@* characters. - Multiple comments may be spread over a source file and can include information about several functions, as long as each documentation comment is followed either by the next one or an [.IDPNL_APPENDIX_DOCCOMMENTS_ENDMARKER]. .. ............................................................................. .3 Linking to sections created by doc comments .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_LINKAGE . It may be very useful to link between panels created by documentation comments. When doing this, keep in mind that the text included in these panels must be compatible to the [.IDPNL_REQUIREMENTS_HTEXT] syntax, so that a link is easily created by the following syntax: .fo off This is a link to a panel: [[. linktext as much as you want]] .fo on . where *anchorname* is the name of the anchor being set for a panel by the *.ANCHOR* command that has been generated by [.IDPNL_APPENDIX_DOCCOMMENTS_GENERAL escansrc.cmd]. The above example would look like this (here with a dead link though): This is a link to a panel: [.IDPNL_APPENDIX_DOCCOMMENTS_LINKAGE linktext as much as you want] The anchor names being used for the generated part of the online help consist of the following: .ul compact - the basename *IDPNL__EFUNC__* - the function name in uppercase characters - the type name of the comment (like [.IDPNL_APPENDIX_DOCCOMMENTS_SYNTAX], [.IDPNL_APPENDIX_DOCCOMMENTS_PARM], .etc.) preceded by an underscore - if it is a link to a dedicated parameter section, an additional underscore plus the name of the parameter in uppercase characters The following examples show you how to write a link in [.IDPNL_REQUIREMENTS_HTEXT] syntax, but without specifying a link text (so these examples would display the title of the linked panel instead, which would mostly not be useful in this case). Just include the link text between the anchorname (separated by a space character) and the closing square bracket: .pl tsize=3 - [[.IDPNL__EFUNC__NEPMDWRITESTRINGEA]] = links main panel of function NepmdWriteStringEa - [[.IDPNL__EFUNC__NEPMDQUERYFULLNAME__SYNTAX]] = links syntax panel of function NepmdQueryFullname - [[.IDPNL__EFUNC__NEPMDDELETESTRINGEA__PARM]] = links parameter overview panel of function NepmdDeleteStringEa - [[.IDPNL__EFUNC__NEPMDERRORMSGBOX__PARM__BOXMESSAGE]] = links panel for parameter BoxMessage of function NepmdErrorMsgBox - [[.IDPNL__EFUNC__NEPMDGETINSTVALUE__RETURNS]] = links results panel of function NepmdGetInstValue - [[.IDPNL__EFUNC__NEPMDINFO__REMARKS]] = links remarks panel of the function NepmdInfo - [[.IDPNL__EFUNC__NEPMDGETNEXTFILE__EXAMPLE]] = links example panel of the function NepmdGetNextFile [=NOTE] .ul compact - Don't forget the point when inserting the anchorname in square brackets, otherwise the name is not recognized as an anchorname. - Note: you cannot link to a panel created by the documentation comments [.IDPNL_APPENDIX_DOCCOMMENTS_PROTOTYPE] and [.IDPNL_APPENDIX_DOCCOMMENTS_CATEGORY], as these do not create a panel, but are used only to further specify information about a function to be added to other panels. .. ............................................................................. .3 PROTOTYPE .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_PROTOTYPE . The prototype comment specifies the prototype being inserted in non-formatted font into the syntax panel for a given function. [=NOTE] .ul compact - The text of this comment should not be longer than one or at least as few lines, as possible. - Make sure that the names of the parameters match the names specified in the [.IDPNL_APPENDIX_DOCCOMMENTS_PARM] comments for this function, so that links can be created! *Example:* .fo off /** @@MyFunction@PROTOTYPE ResultValue = MyFunction( Parm1, Parm2, Parm3); @@ **/ .fo on .. ............................................................................. .3 SYNTAX .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_SYNTAX . The syntax comment specifies the text to be displayed in the *Syntax* panel for the specified function. Please don't take the text in the below example too serious, your explanation for a function should be much more sensible. If you have very important remarks to state, you may want to insert these also here, but for remarks longer than one sentence you should use the optional [.IDPNL_APPENDIX_DOCCOMMENTS_REMARKS] comment and link to that from the text here in the *[=.IDPNL_APPENDIX_DOCCOMMENTS_SYNTAX]* comment. *Example:* .fo off /** @@MyFunction@SYNTAX This function intends to return valuable information and requires three parameters. @@ **/ .fo on .. ............................................................................. .3 CATEGORY .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_CATEGORY . The category comment specifies the category that the specified function should be included. [=NOTE] .ul compact - this comment does not specify text, but instead requires the category name appended to the comment name! - The main source file for the online help must include a .SET command to define the title for a category, where the name of the setting must be *CATEGORY__*#categoryname# The following example specifies the function *MyFunction()* being a member of the category *SPECIAL*. *Example:* .fo off /** @@MyFunction@CATEGORY@SPECIAL @@ **/ .fo on The title for this category must be defined in the main source file like .fo off .SET CATEGORY__SPECIAL=This is my very special category .fo on .. ............................................................................. .3 PARM .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_PARM . The parameter comment specifies the information about a parameter passed to the specified function. Therefore this comment must be included for each parameter of the function. [=NOTE] .ul compact - this comment requires the parameter name appended to the comment name! - make sure that it matches identically the parameters in the [.IDPNL_APPENDIX_DOCCOMMENTS_PROTOTYPE] comment, so that a link from the prototype to the parameter section is automatically created *Example:* .fo off /** @@MyFunction@PARM@Parm1 This is parameter 1 for this function and passes an important value. @@MyFunction@PARM@Parm2 This is parameter 1 for this function and passes an even more important value. @@MyFunction@PARM@Parm3 This is parameter 3 for this function and passes an optional value. @@ **/ .fo on .. ............................................................................. .3 RETURNS .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_RETURNS . The comment for the return value is intended for information about the return value. *Example:* .fo off /** @@MyFunction@RETURNS The function MyFunction() returns an OS/2 error code. @@ **/ .fo on .. ............................................................................. .3 REMARKS .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_REMARKS . The remarks comment is optional and is intended for very special information about the function. *Example:* .fo off /** @@MyFunction@REMARKS For using the function MyFunction() some very specific details are important to know: ... @@ **/ .fo on .. ............................................................................. .3 EXAMPLE .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_EXAMPLE . The examples comment is optional and is intended for to give a sample snippet for usage of the specified function. [=NOTE] .ul compact - take care for the *HyperText/2* [.IDPNL_APPENDIX_DOCCOMMENTS_FORMAT escape characters] and other formatting issues. *Example:* .fo off /** @@MyFunction@EXAMPLE Here is an example for calling the function: .fo off ResultValue = MyFunction( Parm1, Parm2, Parm3); .fo on ... @@ **/ .fo on .. ............................................................................. .3 Documentation comment end marker .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_ENDMARKER . In order to let the source scanner script know that no more documentation comments follow after the last one, just add a line with one word of two *@* characters at the end of the last documentation comment. *Example:* .fo off /** @@MyFunction@RETURNS This is the last documentation comment and has to be followed by a documentation comment end marker of two @ characters, see following line: @@ **/ .fo on