|
||||||||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||||||
|
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 |
|
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 |
 |
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 |
|
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 |
|
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 |
 |
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 |
  |
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 |
 |
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
3. TESTER REPORTS section
4. ASSOCIATED WORK Section
5. FILE MAPPING Section (if required) 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:
|
| 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 |
|
||
|
|||
