Copyright: helpC, (c) Copyright 1992,93 Loewy Ron.


NewsDB System Overview

The NewsDB system is a collection of tools that allow the user to create

complex hypertext databases from Internet Usenet articles.

How many times did you have a problem, remembering that someone discussed

it in the past in one of the Usenet news groups, and failed to find the

discussion, because you did not save the article, and if you did, you can

not find where you put it.

The NewsDB system was created to allow you to have access to

"Other People's Wisdom".

NewsDB features include :

        - Automatic Newsgroups references creation.

        - Automatic Author directories and references.

        - Article (Topic) references :

                - To other (previous) articles.

                - From other (later) articles.

        - Automatic Keywords creation.

        - Support for User specific groups.

        - Customized free text search to associate articles with groups.

        - Hot links between articles.

        - UNIX to PC translation program.

        - Multi Article file split.

        - Multiple hypertext targets.

Related Topics :

 Credits

 File List - List of files available with NewsDB

 Registering NewsDB

 System Requirements

 NewsDB Tools

 Warranty


System Requirements

In order to use the NewsDB system you need :

        - A PC capable of running DPMI programs.

        - News Articles.

        - The Help Development Kit, V9.5 or newer.

Also recommended :

        - As much memory as possible.

        - As much disk space as possible.

Optional :

        - Help Compilers/Linkers to specific targets.


File List - List of files available with NewsDB

The following files are supplied with the NewsDB package :

SPLIT.EXE       - Split multi-article files.

FL.EXE          - Filter : UNIX -> Dos text files.

DOFL.BAT        - A batch file that Filters all files with an empty extention,

                  in the current directory.

N2H.EXE         - The NewsDB News 2 HLPDK database managment program.

NEWSDB.DOC      - NewsDB Documentation file.

NEWSDB.HLP      - This File.

NEWSDB.HDF      - NewsDB Documentation in .HDF format, you can use this

                  file and HLPDK to create document and on-line help files

                  to additional targets. (e.g. OS/2 INF on-line help).

NEWSDB.REG      - NewsDB Registration file.

NEWSDB.EDU      - Special NewsDB Educational discount registration file.

PROGRAMS.TXT    - ISoft D&M shareware products description.

DPMI16BI.OVL    - Borland's DPMI Server.

RTM     .EXE    - Borland's Dos Extender Run Time Module.


Registering NewsDB

The NewsDB system is a shareware product, if you find this product valuable,

please register it.

By Registering you will receive the latest NewsDB and HLPDK Systems that

include protected mode help compilers and engines, and a N2H program that

will not create the "Created By an un-registered version of N2H" overview

screens.

NewsDB Registration allows you to use the NewsDB generated help files,

for your own private purposes. You are not allowed to distribute the

help databases created by NewsDB, without permission from ISoft D&M.

Other databases created with HLPDK, but not with the use of NewsDB, can be

distributed royalty free. (Please refer to the HLPDK documentation).

To order your registered copy of NewsDB + HLPDK please do one of the following:

 1.     Order from ISoft D&M:

 You can order directly from ISoft D&M. Please refer to the supplied

 NEWSDB.REG file. Edit it, print it and mail it (with a check) to:

        ISoft D&M,

        POBox 5517

        Coralville Iowa 52241, U.S.A

 University students and faculty members may qualify for special, reduced

 registration fees. Please refer to the supplied NEWSDB.EDU file.

 2.     Order from PsL:

 You can order from Public (software) Library with your MC, Visa, AmEx

 or Discover card by calling 800-242-4PsL (from overseas: 713-524-6394) or

 by FAX to 713-524-6398 or by CompuServe to 71355,470.

 These numbers are for ordering only. ISoft D&M can NOT be reached at those

 numbers. Please contact ISoft D&M directly for any other type of problem

 (technical or other), information or request.

Registerd HLPDK users, can upgrade to NewsDB + HLPDK for a reduced cost.

 Please refer to the supplied NEWSDB.REG file. Edit it, print it and mail it

 (with a check) to ISoft D&M.

Educational Discounts are available to students and Faculty members.

 Please refer to the supplied NEWSDB.EDU file, Edit it, print it and mail it

 (with a check) to ISoft D&M.

Upgrades, special rates and discounts are offered only by ISoft D&M direct

registration.


Contact

  Please contact :

  ISoft D&M,

  P.O.B 5517

  Coralville IA 52241,

  U.S.A

ISoft D&M e-mail address : CompuServe - 76350,333

  To contact the author directly :

  Contact :     Loewy Ron,

                9 Haneveem st.

                Herzeliya, 46465

                ISRAEL.

e-mail address : CompuServe - 100274,162

Related Topics :

Regsiteration

Overview


NewsDB Tools

NewsDB includes the following executables :

FL.EXE          - A simple filter that translate UNIX LF to CR/LF

                  needed by MS-DOS.

SPLIT.EXE       - A simple text file splitter. N2H.EXE needs each article to

                  be in a separate input file. If you mark where an article

                  starts, by inserting a special line before it, in the source

                  file, SPLIT will create multiple files, that can be processed

                  by N2H.

N2H.EXE         - This is where the fun is. N2H is the hypertext generator that

                  takes a collection of Usenet articles (or even plain text

                  documents), and creates the .HDF sources. N2H works like an

                  archive program, you can add files to the archive, and N2H

                  maintains database tables about the file. N2H can also

                  generate the .HDF source from the archive database.

The following executables are needed, but not included with the evaluation

package of NewsDB :

HLPDK executables : (Available for evaluation in HDK95A.ZIP and HDK95B.ZIP.

HELPC.EXE/HELPCX.EXE - The HLPDK Help Compiler.

HELPENG.EXE/HE.EXE/HELPENGX.EXE/HEX.EXE - Optional HLPDK help engines.

Optional target specific executables :

Please consult the HLPDK documentation, about the additional tools you might

need if you intend to use the News Database in an other target than the native

help engines provided with HLPDK.

Related Topics :

 FL Documentation

 SPLIT Documentation

 N2H Documentation

 Help Development Kit


FL - UNIX -> MS-DOS filter

The FL.EXE file provided with NewsDB is a small and simple filter for UNIX

text files. The FL syntax is :

FL inp-file out-file [/d]

Where inp-file is the UNIX file, that needs to be converted, out-file is the

name of the created MS-DOS text file, and if the optional /d switch is

specified, inp-file will be deleted after the conversion.

FL is not a smart convertor. There are better convertors around, that will

allow you to move text files to and from UNIX format.

If you you want to convert many files at once, use the supplied DOFL.BAT file

- that will convert all the files with no extention in the current directory,

to MS-DOS text files, with the extention .REC, and delete the original files.


SPLIT - break multi-article files to many one article files

The SPLIT program is a small utility that prepares text files that contain

many articles to many files, each of them with only one article.

The N2H program can only process articles that are in a file of their own.

You will have to edit the source multi-article file yourself, and add a line

that starts with the following string :

///////

before the first line of each article.

Be sure that you keep the Usenet article header, and that the header's first

line starts one line under the separator line, with NO blank lines in between.

The SPLIT utility syntax is :

SPLIT inp-file out-extension

Where inp-file is the name of the input source file, and out-extension is the

extension that will be used for the files created by SPLIT.

SPLIT will create files called : 1.out-extension, 2.out-extension ..

n.out-extension, where n is the number of files in the source file.

Please notice that out-extension is a 3 characters string, the longest.

It is important to notice, that the first line of the input files MUST

include the separator line.


HLPDK - The Help Development Kit

The Help Development Kit is the hypertext package that is needed in order

to compile and use the output of the NewsDB system.

HLPDK includes a help compiler that accepts sources in the .HDF

(HLPDK Help Definition Format), and creates help databases to the HLPDK

help engines, or sources to other help engine targets, such as Windows

WINHHELP, OS/2 IPF, DESQVIEW/X help system, Borland's TVHC and THELP,

Turbo Power's POPHELP, Microsoft's QuickHelp, and can even create text

documents and word processors documents. (This document was created using

HLPDK).

The HLPDK system includes 2 Royalty Free Help Engines, that can be

distributed free with help databases that were created by the help compiler.

HLPDK suports the following features :

Topics, Popups, Links, Keywords, Text format, Navigational

and structural facilities, Target code insertion, Multiple module files,

Automatic Pascal/C/C++ reference generation, Exception handling and more.

Programmers that want the help engine's sources, can purchase it and modify

it to their specific needs.

The HLPDK package is a shareware product, distributed by ISoft D&M.

As both HLPDK and NewsDB were authored bu Ron Loewy, You can be sure

that these 2 systems will be in sync with each other. (NewsDB was

written with HLPDK in mind, while HLPDK is enhanced, with NewsDB in mind).


N2H - News articles 2 HLPDK converter

The N2H program is the main program of the NewsDB system. This program handles

the task of reading Usenet articles, processing them, storing them in a

database archive, and generating the hypertext source in HLPDK syntax.

The N2H syntax is :

N2H command database {input-article-files} [options]

Where command is one of the commands supported by N2H, database is

the news database that this command operates on, the input-article-files are

a list of files with news articles in them, that are processed by N2H

according to the command (some commands do not operate on input files), and

options are optional parameters that can be supplied to the N2H program to

alter some of the functionality of the program.

It is important to notice that N2H assumes that there is only one article in

each input file, if there are more articles in the input file, N2H assumes

that they all belong to the first article found.

N2H can process files that contain textual information in plain ASCII format,

and that were not received from the Usenet system, however, some of the

automatic links that can be created by N2H will not be created for these

"articles". In order to collect the Usenet news in the article, to be used

for the hypertext generation, the input article files MUST NOT start with

empty lines, the first line of the article MUST be the first line of the

article header.

Related Topics :

 N2H Commands

 N2H Customization


N2H Commands and how to manage your hypertext news database

The N2H commands are used to create, manage and generate code from the

News article datbase.

The mandatory parameter to every command is the name of the News database that

this command operates on.

The following commands are avaialble :

Create - Create a new database, including all the customization templates

that are to be tailored by the user.

Add - Add articles/files to the hypertext database.

Build - Same as the Add command, but performs two passes on the data,

in order to build forward links, and not just backward links.

List - List the contents of the hypertext database.

Extract - Extract articles from the hypertext database.

Empty - Empty the hypertext database, brings the database to the

state of a database that was just created, but retains user specific

customization options in the database configuration file.

Move - Same as the Add command, but deletes the input files, after

they have been inserted to the database.

Generate - Generate the HLPDK .HDF source from the News database.


N2H Create Command - Create an empty database, with template

Syntax :

N2H C dbname

or

N2H CRE dbname

or

N2H CREATE dbname

Where dbname is the name of the hypertext database that will be created.

After N2H will finish creating the database tables, you are expected to

modify the dbname.INI file to customize the database generation options.

The dbname.INI file is a standard "Windows" like INI file, with several groups,

and entries in these groups.

By default, N2H creates an INI file that will collect the data according to the

newsgroups of the articles, with no user defined groups.

User defined groups are a very interesting feature that allows N2H to associate

an article with a user defined topic, by scanning the textual information

(not the header) of the file, and if a user defined word is found, the article

will be associated.

If you created a news database using the command

n2h c znews

The following ZNEWS.INI file will be created (up to minor changes) :

--------------------------------------------------------------------

[General]

DatName=znews

LastTopic=0

DBName=znews

LastDatPos=0

refName=znews_RF

lastNGword=1

wordMapCount=9

LastAuthor=32767

[WordGroupMap]

Map1=__word__, __group1__ __group2__

Map2=__word__, __group1__ __group2__

Map3=__word__, __group1__ __group2__

Map4=__word__, __group1__ __group2__

Map5=__word__, __group1__ __group2__

Map6=__word__, __group1__ __group2__

Map7=__word__, __group1__ __group2__

Map8=__word__, __group1__ __group2__

Map9=__word__, __group1__ __group2__

--------------------------------------------------------------------

As can be seen, there are 2 groups in the INI file. The first one - [General],

is used by N2H to keep database specific global parameters.

The parameters in this group should not be modified, EXCEPT for the following

parameters :

lastNGword - Set to 0 if you do not want N2H to add a keyword to an article,

that is the last part of the group name. By default, this keyword is added.

This can be very useful, because all the articles from COMP.LANG.PASCAL, for

example, will have the keyword PASCAL in them. There are cases in which this

options is not so good, all the COMP.ARCHIVES.MSDOS.D articles will have

the keyword D in them (It is not bad, it is just not what you would like to

search for ..).

wordMapCount - This parameter sets the number of word maps, in the WordGroupMap

that N2H will look for. The template provides by default a maximum of 9. It is

important to understand that if more than wordMapCount Map entries are defined

in the [WordGroupMap] INI file group, only the first wordMapCount maps will be

processed.

It is perfectly fine to set this parameter with a value that is larger than the

actual number of maps.

The [WordGroupMap] is the place where you associate user defined groups with

textual words that might appear in the article text. The syntax for each

word map is :

MapX=textual_word, group1 [another_group [another_group ..]]

Where X is a number between 1 to wordMapCount in the [General] INI group,

textual_word is the word that is expected in the article body, and the

groups (group1 and the optional another_groups] are the user defined groups,

that the article will be associated to, if the textual_word is found.

Example :

The following is the ZNEWS.INI file I use myself for the articles I keep:

-------------------------------------------------------------------------

[General]

DatName=znews

LastTopic=0

DBName=znews

LastDatPos=0

refName=znews_RF

lastNGword=1

wordMapCount=30

LastAuthor=32767

[WordGroupMap]

Map1=hypertext, hypertext

Map2=html, hypertext

Map3=winhelp, hypertext

Map4=thelp, hypertext

Map5=owl, windows_programming

Map6=mfc, windows_programming

Map7=pascal, pascal

Map8=C, C_and_C++

Map9=C++, C_and_C++

Map10=DLL, windows_programming

Map11=3d, 3d

map12=upload, ftp

map13=uploaded, ftp

map14=book, book

map15=books, book

map16=textbook, book

map17=cdrom, multimedia

map18=multimedia, multimedia

map19=cd-rom, multimedia

map20=borland, borland

map21=debug, debugger

map22=tdw, debugger

map23=debugger, debugger

map24=td, debugger

-------------------------------------------------------------------------

As can be seen, I have defined a maximum of 30 word maps, and I use 24 of them.

The user groups I defined are :

hypertext, windows_programming, pascal, C_AND_C_++, 3d, ftp, book, multimedia,

borland and debugger.

We can see that an article is associated with the windows_programming user

group if one of the following words is found in the body of the article :

owl, mfc, dll

If an article has more than one match, the article will be associated with ALL

of the user groups that were matched.


N2H Add Command - Add articles to database, with one way reference.

Syntax :

N2H A dbname article-files

or

N2H ADD dbname article-files

Where dbname is the name of the hypertext database that will be updated, and

article-files is a list of files that contain articles to be updated.

article-files can be specified using the standard DOS wild-cards.

N2H will add the files to the dbname.DAT file, with all the required link

information from the article to other articles that it references, and to

news, author and user groups it belongs to.

N2H will also create the keyword and group lists, during this command.

Please note that this command will not create Referenced By links between

the articles that are added to the databases, to articles that reference

them, and are added with this command. To do that you will want to use the

Build command, but the Build Command takes twice as long to process.

The Add Command works like an incremental compiler, so - if there are

refrences to an article, that appear in another article that was already

added to the database, these references will appear.

Example :

N2H A ZNEWS \NEWS\DAT\*.1*

Will add to the ZNEWS database all the files with an extention that starts

with the character 1, in the \news\dat directory of the current drive.

Related Topics :

N2H Build Command


N2H Build Command - Add articles to database, with 2 way references

Syntax :

N2H B dbname article-files

or

N2H BUI dbname article-files

or

N2H BUILD dbname article-files

Where dbname is the name of the news article database, article-files are the

names of the files that contain the articles that will be processed by N2H.

article-files can be any combination of valid dos names, including wild-cards.

N2H Will create the same database references as the Add command does, but if

Referenced By links exist between articles that are processed during this

execution of the command, these links will be specified.

The Build command performs 2x2 passes on the data, compared to only 2x1

passes performed by the Add command.

Example :

N2H A ZNEWS fileA fileB fileC fileD

will cause N2H to perform one pass in which it will handle each file (A-D),

and make 2 passes on each of them, in the first pass, some data about the

article is collected, and written to the database, and in the 2nd pass, N2H

will use that data, and data that already exists in the database to write the

textual source to ZNEWS.DAT, and update some other aspects of the database.

N2H B ZNEWS fileA fileB fileC fileD

will perform one pass on all the files (A-D), and will pass twice on each

file, update the database, but will NOT create the textual info in the

.DAT file, than ANOTHER pass on all the files will be performed, in this pass

each file will be examined twice, and at the end the textual info will be

written.

If fileD references fileB, in our example, at the end of the the Add command,

there will not be a link from fileB to fileD, while after the Build command,

there will be. (There will be a link from D to B in both cases).

The Build Command can replace the Add command, you can decide that you always

use the Build command, and not the Add command, and you will have all the

functionality of the Add command, and more. The only problem, is that the

processing time needed to the Build command is twice of the time needed for

the Add command.

Related Topics :

N2H Add Command


N2H Move Command - Same as Add, and delete original files.

Syntax :

N2H M dbname article-files

or

N2H MOV dbname article-files

or

N2H MOVE dbname article-files

This command has the same functionality of the Add command, but the

article-files are deleted at the end of the operation.

It is advised to keep the articles in the original format, because there

are cases in which N2H can not extract the articles from the database, to

the original format.

Related Topics :

N2H Add Command


N2H List Command - List articles in database

Syntax :

N2H L dbname [article-names]

or

N2H LST dbname [article-names]

or

N2H LIST dbname [article-names]

where dbname is the name of the database that will be processed, and

article-names are the optional names of the article original files that

are to be listed. Valid DOS names are excepted, wild-cards are allowed.

If no article-names are specified, all the files in the database will be

listed.

Related Topics :

N2H Commands


N2H Extract Command - extract an article from the database.

Syntax :

N2H E dbname article-files

or

N2H EXT dbname article-files

or

N2H EXTRACT dbname article-files

where dbname is the name of the database from which the files will be

extracted. article-files are the valid DOS names of the articles as they

were called when inserted to the database with the Add, Build or Move

commands. Wild-cards are allowed.

Notice that N2H will always extract to the current directory, even if the

original source of the article was in a different place.

Extract will fail to produce exactly the same article as the article that

was inserted to the database, if one of the following is true :

- The article was inserted with the /KH- switch, and the news header was not

  saved.

- The article had special characters in the original source, that were

  translated by N2H, to be compatible with HELPC - the HLPDK compiler.

Related Topics :

N2H Commands

N2H Switches


N2H Empty Command - Empty database, keep INI customization

Syntax :

N2H EMP dbname

or

N2H EMPTY dbname

where dbname is the name of the database to be emptied.

When this command is executed, N2H cleans the database files, the .DAT file,

and updates the pointers in the INI file.

User customized options in the INI file are not changed.

This command can be very useful, if you learn from the data that you can

enhance it by adding more used defined groups, or if you have been using

multiple Add/Move/Build commands, and thus not all Referenced By links

were created.

In such cases, the recommended procedure is to use the Empty command, update

the INI file for further customiztion (if necessary), and use the Build

command on the original files.

Related Topics:

N2H Create Command

N2H Build Command

N2H Commands


N2H Generate Command - Generate source .HDF from database

Syntax :

N2H G newsdb

or

N2H GEN newsdb

or

N2H GENERATE newsdb

where newsdb is the name of the news database, that will be processed to

create the newsdb.HDF file that can be used to compile with HLPDK.

Please notice that newsdb.HDF is not enough to create the hypertext

database, part of the data is created when you specify the Add, Build or

Move commands, in the newsdb.DAT file that is .INCLUDEd by newsdb.HDF.

If you plan to compile the .HDF file in the same directory it was created,

no problem exists. If you intend to compile in another directory, move the

newsdb.HDF and newsdb.DAT to the new directory, or just the newsdb.HDF, and

alter the path to the .DAT file in the .HDF file .INCLUDE statement.

Please consult the HLPDK documentation on the various switches and options

of the HELPC help compiler.

Example :

N2H G ZNEWS

will create ZNEWS.HDF that has a reference to ZNEWS.DAT in it.

HELPC /W31 /R- ZNEWS

will create the WINHELP sources (ZNEWS.RTF and ZNEWS.HPJ) from the ZNEWS.HDF

HLPDK source.

HCP ZNEWS

will create the WINHELP .HLP database, from the source created by HELPC.

Related Topics :

HLPDK

N2H Commands


N2H Switches

The N2H program allows several switches to be specified on the command line,

or in an option file. These switches alter the default behavior of the N2H

program.

The following Switches are provided :

/EP+ /EP-     - Echo Parse On/Off - Display article parse information.

/DW+ /DW-     - Display Warnings On/Off -  Display Warnings found during parse.

/G:group      - Add (Unconditionally) the group, to all articles being processed

                in a Build, Add and Move commands.

/K:keyword    - Add (Unconditionally) the keyword to all articles being

                processed in a Build, Add and Move Commands.

/NI+ /NI-     - Add Navigational information (Links) On/Off to the articles

                being processed in a Build, Add and Move commands.

/KH+ /KH-     - Keep article Header On/Off during article process in the

                Build, Add and Move commands. If /KH- is specified, the Extract

                command will not be able to re-create the article with the

                Usenet header information. If /KH+ is specified, the disk space

                needed to hold the hypertext database will be smaller.

/H:top_prefix - Set the prefix of the topics processed by the Build, Add and

                Move Commands to top_prefix. By default, the topic prefix is

                "ntp_". You will want to change that prefix only if you plan

                to integrate the output of the NewsDB program with another

                HLPDK database, and have name collisions.

Related Topics :

 N2H Documentation

 N2H Commands


Warranty

There is no warranty what so ever, The package is supplied as is, The distributor (ISoft D&M), or the author (Loewy Ron), are not, and will not be responsible for any damages, lost profits, or inconveniences caused by the use, or inability to use this package. The use of the program is at your own risk. By using (or attempting to use) the package you agree to this.

Related Topics :

Contact


Credits

The NewsDB Programs SPLIT, N2H and FL were written using Borland Pascal 7.0. A trademark of Borland International.

The N2H Program was written using The Paradox Engine, V3.01, A trademark of Borland International.

Large parts of the N2H Program were generated using my own dbGen CASE code generator.

HELPENG, HELPC were written using Turbo Pascal 6.0, and Borland Pascal 7.0, Paradox Engine 2.0, and Paradox Engine 3.0, 3.01. (Trademarks of Borland International).

Windows, Microsoft, HC and Quick Help are trademarks or copyrights of Microsoft Corp.

The HELPENG program was written using the WINTEXT UI library, (c) 1991,93 Loewy Ron.

THELP, HL and TVHC are Trademarks or copyrights Borland International.

POPHELP is a copyright of TurboPower Software.

DESQview/X is a trademark of Quarterdeck Office Systems.

OS/2 is a registered trademark of International Bussiness Machines.

Parts of the Help Engines were generated using Ron Loewy's WTGEN and dbGen CASE code generators.

Parts of the Help Compiler were generated using Ron Loewy's dbGen database code generator.

Reuben Halevi, and Yaniv Golan tested and suggested .. and it shows ..

Related Topics :

NewsDB Overview