How to Present Your API Conversion

Click here if you have followed the specifications in this document and are ready to submit your conversion pack
Formulated September 1999 by

Phil Shrimpton
Marcel van Brakel
Rudy Velthuis

Last updated 28 January 2000

This document

  • explains how to package a conversion project for submission to the Project JEDI API Library
  • identifies the levels of compliance with Project JEDI and Borland standards
  • identifies the statuses that apply to work-in-progress and completed work
  • describes the contents of the ancillary documentation files that may be included in the pack
  • summarizes the "open source" licensing conditions for Project JEDI work
Contents 1. API Pack (.Zip) Format and Organization
2. Certification Levels
3. Status Levels
4. Contents of an Interface Unit
5. Contents of Info.txt
6. Contents of Readme.txt
7. Contents of a Help File
8. Licensing Summary
1. API PACK (.ZIP) FORMAT AND ORGANIZATION
Contents
(a) Naming of Files

The Team Captain (or, in the case of a new submission, the donor) should submit all files in a single .zip file. This must be a standard pkzip/winzip file generated with maximum compression. The name of this file must be <API_NAME>.zip where API_NAME is the name of the corresponding API, possibly abbreviated. It should be as short as is practicable and follow the "camel case" convention (see below). Do not include spaces in the filename.

If the pack contains a group of APIs but does not translate the whole of an SDK (as often occurs with the Microsoft platform APIs), choose a name that makes the group recognizable. For further guidelines, refer to the next section.

Wherever possible, the names of interface units should be identical to the corresponding header files and in camel case, which is mixed case with no spaces or underline characters and with uppercase letters marking the first letter of each word.

For example:

msiquery.h becomes MsiQuery.pas

If possible, restrict the length of unit names to 8 characters.

Example:

The Microsoft Installer API (generally referred to as MSI)

Name of zip file: Msi.zip
Unit names:
     msi.h -> Msi.pas
     msiquery.h -> MsiQuery.pas
     msidefs.h -> MsiDefs.pas

If a name clash would occur by following these rules, the unit name should be altered as little as possible. For example, htmlhelp.h becomes HtmlHlp.pas because there is a function named HtmlHelp in the unit so it cannot be named HtmlHelp.pas.

b) Organization of a Submitted Pack

The zip file should be organized as follows:

The root folder should have the same name as the zip file and should contain only the following files:

Info.txt and Readme.txt Please read the detailed notes regarding the content of these files. These are to be plain text or, if formatting is required, use .rtf (rich text) format only. Use of word-processor formats (such as Word or Word Perfect) will cause the pack to be rejected until this requirement is met.

Please do not submit a zip file containing the absolute path structure copied from your hard disk.

All other files should be organized in sub-folders, as described here. Please conform to the supplied naming standard for sub-folders.

Folder Purpose
Pas Contains the interface unit(s)
Par Contains the intermediate .par file(s)
Bin Compiled units
Demos Contains demo projects. Use a separate subfolder for each demo
Docs Additional documentation (e.g. a tutorial on using the API)
Help Compiled WinHelp help file(s) as well as all sources needed to (re)build it (rtf, hpp etc).
Do not include empty folders, e.g. if there are no demo projects then do not include an empty Demo folder.

Related files and/or projects should be placed in a subfolder of the Demos folder, for instance, a unit with utility functions or a (set of) component(s). However it is preferred that these be made available as separate packs, rather than be included in the API pack.

2. CERTIFICATION LEVELS
Contents
There will be a delay between receipt of a pack and its appearance in the ftp download area (ftp://delphi-jedi.org) whilst the certification level of the work is being assessed. When contacting the Technical Coordinator for an upload password, you should indicate the certification level for which you wish to apply. Upon assessment, if the work does not meet the level you requested, you may be contacted to decide whether to submit it at a downgraded level or to complete the requirements and resubmit.

At any time, you (or another volunteer) may apply to do the work to upgrade a pack.

Level Certification Description
(0) Unknown

Status ungraded

The API has not been graded yet. This will be the certification level for all projects that are work in progress, or do not meet the required specifications for Level 1 or 2.


(1) Partial

Status partial

The interface unit(s) form a subset of the complete API. That is, either - one or more interface units are missing or - one or more units are incomplete. The main translation units (*.pas) will include the MPL header.


(2) Untested

Status untested

Level 1 "Partial" BUT interface unit(s) is (are) a complete translation of all header files from a single API. No testing has been done.


(3) Complete

Status complete

As Level 2 "Untested" BUT everything has been tested AND there is a 1-to-1 correspondence between units and header files or a text file is present in the Readme.txt file describing the mapping (see section 6/5 below). Packs containing completed translations whose code or file names are not compliant with Borland standards will rest at this level.


(4) Borland Compliant

Borland Compliant

Borland B

Level 3 "Complete" AND the interface units comply with the specifications described in the documents "Pascal Header Translation Specification" and "Styleguide" which are available at the Borland Techvoyage website. All .par files are present. All *.h macros have been translated (if required). All original comments from *.h have be preserved. No Dynamic Linking and/or conditional defines are present in the main translation units.


(5) JEDI Certified

Jedi Certified
Jedi J

Level 4 "Borland Compliant", with the addition of the Readme.txt document. The pack complies with the rules laid out in 'Organization of a Submitted Pack' (above).


(6) JEDI Plus

Jedi Certified
Jedi Plus

Level 5 "JEDI Compliant" PLUS at least one Demo project and possibly a tutorial and help file. It may also include units that implement Dynamic linking and/or IFDEFs in a separate subdirectory.



3. STATUS LEVELS
Contents
Level Status Description
(1) Forming A team is forming for this API and/or the conversion work is started. No source code is available yet.
(2) Active The conversion and creation of other files are in progress. A download is available but it is incomplete and/or not tested yet
(3) Testing Some or all parts are available for testing, sample writing and Help writing
(4) Finished The conversion is finished and a certified package (of whatever level) is available for download. No more work will be spent on this version of the API.


4. CONTENTS OF AN INTERFACE UNIT
Contents

An interface unit (.pas) contains only code directly translated from an API header file. No other code, such as utility subroutines, is present. However, any routine written in order to implement the functionality of a C macro must be included in the unit (see note 4d) below).

(a) Header Section

All units start with the following header:

{******************************************************************}
{                                                                  }
{ Borland Delphi Runtime Library                                   }
{ <API> interface unit                                             }
{                                                                  }
{ Portions created by Microsoft are                                }
{ Copyright (C) 1995-1999 Microsoft Corporation.                   }
{ All Rights Reserved.                                             }
{                                                                  }
{ The original file is: urlmon.h, released 11 Nov 1997.            }
{ The original Pascal code is: UrlMon.pas, released 15 Jun 1999.   }
{ The initial developer of the Pascal code is Rudolph Velthuis     }
{ (rvelthuis@gmx.de).                                              }
{                                                                  }
{ Portions created by Rudolph Velthuis are                         }
{ Copyright (C) 1999 Rudolph Velthuis.                             }
{                                                                  }
{ Contributor(s): Marcel van Brakel                                }
{ Christopher D. Coppola                                           }
{                                                                  }
{ Obtained through:                                                }
{                                                                  }
{ Joint Endeavour of Delphi Innovators (Project JEDI)              }
{                                                                  }
{ You may retrieve the latest version of this file at the Project  }
{ JEDI home page, located at http://delphi-jedi.org                }
{                                                                  }
{ The contents of this file are used with permission, subject to   }
{ the Mozilla Public License Version 1.1 (the "License"); you may  }
{ not use this file except in compliance with the License. You may }
{ obtain a copy of the License at                                  }
{ http://www.mozilla.org/MPL/MPL-1.1.html                          }
{                                                                  }
{ Software distributed under the License is distributed on an      }
{ "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or   }
{ implied. See the License for the specific language governing     }
{ rights and limitations under the License.                        }
{                                                                  }
{******************************************************************} 

Download template

(b) Linking Options

The default (no defines) should always be the latest version of an API combined with static linking and should assume the latest version of Delphi.

If the author of the interface unit wants to provide dynamic linking against the API this should be done through the use of conditional defines ($IFDEF compiler directives). The unit should implement either static linking alone OR both static and dynamic linking and provide a switch through a compiler directive.

If dynamic linking is present then all function variables should be initialized to nil (automatically done by Delphi), the unit should have exactly the same name as it would have if static linking was used, and the following functions should be provided:

function Load<API_NAME>: Boolean; //returns True if API successfully loaded
procedure UnLoad<API_NAME>; 
function <API_NAME>Loaded: Boolean; //returns if the API is loaded
The API should be automatically unloaded in the finalization section, but must be tested to ensure that it does not misbehave if it is explicitly unloaded sooner by using UnLoad<API_NAME>. When the API is unloaded all function variables should be reset to nil (helps with debugging). There could be an optional differentiation between explicit and implicit loading, i.e. Load<API_NAME> could be called automatically on startup (initialization) depending on another conditional.

For examples, see HtmlHlp.pat.

c) Documentation Within the Source Code

All original documentation from the header file should be copied to the translation.

Keep further source code comments to a minimum and restrict them to matters concerning programming and the translation. Do not include implementation or user documentation in the source code. Please refer to the notes below about Readme.txt.

Do not document "KNOWN ISSUES" in the source units. Please refer to the notes below about Readme.txt.

d) Translation of C Macros

Because C/C++ macros are not translatable, it is necessary to create Delphi functions based on the macro's description in the SDK documentation. In this sense, the converter is writing a new method in order to achieve the functionality of untranslatable C code. Please include a short explanation of any such solutions. Do not physically separate this "new" function from the translated code from the same header.



5. CONTENTS OF INFO.TXT
Contents

Info.txt is used for recording all information about the API that is available. All dates should be in the format dd MMM yyy. Please do not use dd/mm/yy(yy), mm/dd/yy(yy) or yy(yy)/mm/dd because of the confusion this causes to international readers.

[API] 
Name=<name of the API; e.g. HtmlHelp>
Version=<version of the API; e.g. 1.21>
Date=<release date of the API; e.g. 12 May 1999>
Originated=<source of the API; ex: HtmlHelp Workshop 1.21>
URL=<Homepage of API; exmdsn.microsoft.com/workshop>
Description=<short description of the API; e.g. Interface for the Microsoft Html Help API> 

[CONVERSION] NOTE: THERE CAN BE MORE THAN ONE FILE - Duplicate this section for each file.
FileName=<name of file>
FileDate=<creation date of file dd MMM yyyy>
Status=[READY|WORK-IN-PROGRESS|READY-FOR-TESTING]
Version=<version of file>
LastModify=<date of last modification dd MMM yyyy>
OriginalFile=<name of original header file>
[Platform]
Win31=[YES|NO|UNKNOWN]
Win95=[YES|NO|UNKNOWN]
Win98=[YES|NO|UNKNOWN]
Win2000=[YES|NO|UNKNOWN]
WinNT3=[YES|NO|UNKNOWN]
WinNT4=[YES|NO|UNKNOWN]

[Requirements]
Req1=<e.g. Requires IE3 or higher>
Req2=<e.g. Requires hhctrl.ocx>

[Captain]
Name=<name of team captain>
Email=<email address of captain>

[Converters]
Converter1=<name;email;homepage>
Converter2=<name;email;homepage>

[Testers]
Tester1=<name;email;homepage>
Tester2=<name;email;homepage> 
Download template


6. CONTENTS OF README.TXT
Contents

1. KNOWN ISSUES Section
Use this section to document any issues that gave rise to a peculiarity in a translation, workarounds to solve problems detected in testing, discrepancies in behaviour between compiler versions, etc. Any issues that affect the way the function is used in an application should also be duplicated into the Help text.

2. IMPLEMENTATION Section
Implementation details should (ideally) be made into a Help file so that it can be compiled with other Delphi help. If a pack is submitted without a Help file, the author should include in the Readme.txt as much information as the programmers and testers can provide, including code snippets, both to assist users to implement the code and to assist help writers who may be subsequently assigned to help-writing.

3. TESTER REPORTS section
If Tester reports are available, include them in README.TXT under the heading TESTER REPORTS. This section should include references to any code demos that the testers have supplied.

4. ASSOCIATED WORK Section
Use this section to refer to any wrappers, components, utility units or spin-off projects associated with this conversion. If possible, include the names of the packs in which these items may be found.

5. FILE MAPPING Section (if required)
Use this section to show the mapping of API header files to pas units, where a header file has been split across more than one pas unit.

Since the unit already has a header which describes which header file the code originates from, you need only provide a header file to pas units mapping. It should be a table describing which units are created for a particular header file.

For example, if DirectX.h is split up into DirectMusic.pas and DirectPlay.pas, it should look something like this:


header file interface units
----------- ---------------
directx.h   DirectMusic.pas
            DirectPlay.pas

        
It is not necessary to provide mappings at the level of individual functions or constants, although you are free to supply this if you wish.

6. DEFINES Section

All conditional defines should be properly explained here and repeated in the Help file.

7. BUG LIST and FIXES

The Readme.txt is not restricted to only these sections. The author may include any information considered relevant to the conversion.



7. CONTENTS OF A HELP FILE
Contents

Whilst Team Captains are not obliged to write help files for conversions, they are encouraged to arrange for help files to be written and to provide as much supporting information and example material as possible. Project JEDI has a large number of members who have expressed interest in joining projects to assist with this. It is suggested that testers and help file writers work together on developing the content, typically including the following sections:
  • Introduction describing the purpose of the API. KNOWN ISSUES may be duplicated here from the Readme.txt. List all of the functions exposed by the conversion with a brief description of the purpose of each. List all known dependencies.
  • Document each exposed function individually, including an explanation of all parameters and any dependencies upon other functions. If a macro was translated, include an overview of its description from the SDK.
  • Wherever possible, link to an example snippet of each function as it would be used in a Delphi method call.
  • Where conditional defines have been used, they should be explained.
  • It has been suggested that, where good help files and documentation exist in the SDK, they could be "translated" to use Delphi examples.
Click here >if you have followed the specifications in this document and are ready to submit your conversion pack


8. LICENSING SUMMARY
Contents

Click here for a summary of the Mozilla Public License 1.1 as it applies to Project JEDI code

© Project JEDI 1999

This site and the pages contained within are Copyright 1997-2006, Project JEDI. For questions and comments regarding this site please contact webmaster-AT-delphi-jedi.org
Jedi NOW!

Find software, books and training materials at our sponsor's site, www.href.com