==============================================================================
                      Dos Navigator Open Source Project
            Based on Dos Navigator (C) 1991-1999 RIT Research Labs
==============================================================================

    Last revision date: Wednesday November 28 2001

                              Table of Contents

 1. General issues
 2. Creating patches
 3. Programming style
 4. Applying patches
 5. [CHANGED] New DN versions distribution
 6. [CHANGED] Project coordinators

                              1. General issues

    Dos Navigator Open Source Project is dedicated for  development of the po-
 pular  file shell  Dos Navigator (DN) through  collective efforts  of an open
 group of programers.
    Programmers participating in the project do not carry out material profit,
 but everyone is metnioned in the authors list of every consequential version.
 The project  participants should  be aware that the source  text they  create
 will be distributed  publicly and is subject for free usage and  modification
 while preserving the author's copyrights.
    Third party  companies and programmer  groups can create  products derived
 from Dos Navigator Open Source while maintaining the following conditions:
     1. Keeping all the project participants' and coordinators' names in the
        About box and authors.txt file included with all new versions
     2. Keeping dnosp.txt and authors.txt files in the distribution package
     3. Including in the About box and in the text documentation the line
        "Based on Dos Navigator Open Source"
    Not meeting these conditions is considered a violation of project partici-
 pants' copyrights.
    The collective of programmers is open,  and no kind of registration is re-
 quired to enter or exit the project.
    The project coordinator accumulates the changes made by the project parti-
 cipants,  compiles new versions of DN,  tests the new features for collective
 functioning and periodically releases new versions.
    All the changes the project participants make they send to the coordinator
 on the source  text level. The means of  communication to the coordinator are
 listed at the bottom of this document.
    The coordinator is elected. In case of impossibility or the lack of desire
 from the  effective coordinator to continue  his job,  expressed either  in a
 public message or in failing to  communicate to project participants for more
 than a month,  failing to release  new DN version  for more than a month,  or
 failing to communicate for more than  two weeks without an explicit temporary
 transfer  of the  coordinatorship to another project participant,  or also in
 case if most of the project participants publicly express that they are unsa-
 tisfied by the coordinator's work since he or she was last elected, the coor-
 dinator is re-elected. Anybody who publicly expresses so can participate as a
 candidate, and  the coordinator is elected  by a simple majority  of votes by
 the RU.SHELL.DN subscribers.
    The discussion of project details and the collaborative communication bet-
 ween the programmers that is of  interest to a significant number of subscri-
 bers is  carried out in the RU.SHELL.DN  Fidonet echo area.  This document is
 posted to  RU.SHELL.DN every month  or immediately when it  is modified.  The
 modifications are marked with [NEW] and [CHANGED] in the table of contents.
    Those who  have the technical  ability are recommended  to post copies  of
 this document  to the apropriate Fidonet areas  (shells, programming) as well
 as to other computer networks.
    Localization is welcome.  Localization for a national language can be done
 by creating a new set of language resources (and not by derival of a separate
 DN version). If you have decided to start DN localization for a specific lan-
 guage, please communicate to the coordinator (see bottom of this document for
 coordinates).
    Translation of this document to other languages is welcome.

                             2. Creating patches

    The preferred form of submitting source code modifications is a patch. The
 patch method is widely utilized in a number of large projects. For an example
 see the Linux  operating system  kernel,  whose source  text is  available at
 ftp://www.kernel.ru.org/pub/Linux/kernel/.
    A patch is the text resulting from the comparison of two text files or di-
 rectories with files.  Patches are  saved in such form that  permits applying
 a patch to one of those files (or directories) making it same with the other.
    In our project a patch is a result of comparison between two DN source co-
 de directories,  first being the current (base) version of  DN and the second
 being the same version with some kind of modification made.
    The diff utility  is used to create patches.  It was ported from UNIX and,
 as available now, works in Win32 console mode and in 32-bit DOS protected mo-
 de - DPMI (DOS/4GW).  Please make sure  that you have the  diff port  version
 PORT.2 or higher, since the previous port could behave incorrectly. Full des-
 cription of diff as well as its source code is available from the project co-
 ordinator.
    To compare two directories, the following command should be used:
        diff -urN base_version_dir modified_version_dir >file.patch
    It is considered that two subdirectories of the current directory are com-
 pared. The description of the -u, -r and -N options (which can be combined in
 a single option) can be found in the built-in help text:
        diff --help |more
    All the options are case sensitive (this is the UNIX standard).
    It is recommended to name patch files as shown:
        dn-base_version-application_subject.patch
    For example:
        dn-1-51-phonebook-export.patch
    Modification can span multiple  files, include new (added)  files and text
 files other than pas files (resource definition files, etc).
    It is not recommended to combine in one patch different modifications that
 are not related to each other.
    Please note  the patch  description template,  which is  recommended to be
 used to write patch description files.  The name format recommended for these
 files is:
        dn-base_version-application_subject.info
    Please refrain  from using space  characters as well  as more than one dot
 character in the names of patch file itself and its description file, as the-
 se can cause problems under certain operating systems.
    Both files should be packed together with an archiver supporting long file
 names (WinZip is recommended - http://www.winzip.com/),  and the archive sho-
 uld be given a short  name to avoid  various mailing problems.  Such archives
 are  rather compact,  making it possible  to send  them UU-encoded in netmail
 messages.
    It is recommended to start names for this  archives with the last  two di-
 gits of  the base version number.  For example,  01dsvcen.zip is a reasonable
 name for an archive containing a patch based on DN 1.51.01 sources.
    Those project participants who do not have the technical ability to create
 archives in accordance to the  recommendations stated above can create archi-
 ves in the way they find it possible and convenient, but in this case the ar-
 chives should be sent to the coordinator as private mail.

                             3. Programming style

    Due to a rather large number of programmers  participating in the project,
 it is desirable to follow the recommendations stated below to make collabora-
 tion easier.
    The project is international  at the present time,  so all comments in the
 source text should be written in English.
    When a modification of language  resources is necessary,  change resources
 only for the language you know,  and include a note in the  patch description
 file stating for what languages  the modification  was made.  The coordinator
 will make  the modifications for the other languages himself or by communica-
 ting to the native speakers of those languages.
    All the messages, text,  dialogs and other elements  of the user interface
 should be  localizable.  This means that  these items should be  based on the
 language resource contents.  An exclusion can be made only for a special kind
 of fatal error  messages and some other occasions when  it is technically im-
 possible to access the language resources.
    If several lines are changed or added, these lines should be marked with a
 comment with the programmer's name or nickname, for example, { X-Man }.  When
 a large group of  lines is added (like a whole function),  its top and bottom
 should be marked with such comments, each spanning a whole separate line.
    When adding a constant to a group of numeric constants (like cmXXXX),  the
 first unoccupied value is  recommended to be used for the new constant rather
 than shifting values for a range of other constants.
    If a feature is introduced  in a patch,  and this feature is rather stand-
 alone in the sence that it can be easily removed without impairing other fun-
 ctionality, this feature should be made optional at  compile time by surroun-
 ding the  new code with  conditional compilation  directives and  including a
 conditional define directive for the new feature in stdefine.inc file.
    When adding features that are  based on some DOS virtual  machine features
 or services under a particular operating system, a service availability check
 or an  operating system check should be  performed before actually using such
 services or features.  For the operating system check the opSys variable sho-
 uld be analyzed. The opSys variable is defined in the Advance unit along with
 a set of numeric constants  representing different operating systems.  Values
 of the constants can be bitwisely combined, meaning that the environment pro-
 vides functionality  of more  than one operating system (possible  under some
 emulators).  Feel free to add new constants  to that set and apropriately ex-
 panding the functionality of the CheckOS procedure.
    Please do not  include history.txt, authors.txt and  the About box updates
 in your patches. These changes are made by the project coordinator.

                             4. Applying patches

    The patch utility is complementary to diff and is used to apply patches.
    To apply a patch, the following command should be used:
        patch -p1 <file.patch
        (assuming you have the ported patch tool version PORT.2 or higher)
    It is considered that the current directory is the directory with the cur-
 rent DN version (the directory name is not significant).
    The vesion of source code subject to patch application does not have to be
 identical to the base version.  Practically this means that the patch utility
 has some amount of tolerance to the source code changes and different patches
 can be applied to  the same sources independently.  But since accumulation of
 sources text changes can lead to exhausting the patch utility tolerance,  all
 patches should be created basing on the latest source version available.
    The patch utility automatically detects the situation when the patch being
 applied has already been applied to the source code. In this case, the utili-
 ty works in reversed mode, removing the patch without affecting the others.

                       5. New DN versions distribution

    New DN versions are distributed by  the project coordinator. The NAVIGATOR
 fileecho serves for this purpose.  The new versions are also available at the
 following Internet addresses:
        http://www.nsk.su/~dnosp/
        http://dn.traktir.ru/
    Each new version is released as four packages:
        DN<version>S.RAR - source code (mainly for the project participants)
        DN<version>B.RAR - binary distribution for DOS  real-mode  environment
                           (for the end user)
        DN<version>D.RAR - binary distribution for DOS protected-mode environ-
                           ment - DPMI (for the end user)
        DN<version>P.RAR - a set of extra files for the end user
    The fourth  packet contains  screensavers, xlat tables,  Windows icons and
 examples of text configuration files. This package is not released with every
 version but only when an update is necessary.
    All four packets include the  authors list (authors.txt) and the  revision
 history (history.txt) as well as  this document (dnosp.txt).  The source code
 package also has the  patch description template  (template.txt) inside.  The
 revision history  for the  period of  RIT Labs  developing and  support of DN
 along with  the RIT Labs  copyright information is placed in  a separate file
 (ritlabs.txt).
    When needed, other packages may be released as well,  such as localization
 sets for national languages.
    With each new version, two more files are released:
        PATCH<minor version>.RAR - patch collection since last release
        <old minor version>TO<new minor version>.RAR - cumulative update patch
    Beta versions may be released when necessary.  A beta version is a supple-
 mentary  release intended  solely for beta-testing pruposes,  not for general
 usage.  A person who is going  to do beta-testing is  encouraged to  mail the
 project coordinator and give information about which version would be tested,
 and in  what hardware and  software environment (regardless of whether  he or
 she did beta-testing of prior versions).
    While in  beta-state,  new beta-versions  are released each  time when two
 weeks elapse since the last beta-version was released and not less than twen-
 ty new patches were installed, or when four weeks elapse.

                           6. Project coordinators

    First coordinator:
        Alexey Feldgendler
        Phone number in Novosibirsk: +7-3832-776581
        2:5000/111.27@fidonet AKA 911:911/0@codernet
        xman@beep.ru (for mail and files up to 2 megabytes)
    Second coordinator:
        Mike Lykov
        2:5057/44@fidonet
        nelescon@samaramail.ru
        http://dnosp.id.ru/ (the real name is http://www.hippo.ru/~nelescon/)
    Third coordinator:
        check out our www pages and RU.SHELL.DN Fidonet echo area

==============================================================================
