Skip to content

Using ngdb

Introduction

The library is designed to provide a method of opening and reading Norton Guide database files. The code here provides no methods for rendering the content; there is no converter, no reader application, etc; the library is designed to be the core of such tools.

Information

One such tool, which as of the time of writing is a work in progress, is ng2web -- a template-driven tool that converts Norton Guide databases into HTML.

The main class is NortonGuide. When called, with the path to a Norton Guide file, it will open up the guide, load up all the key information, and provide an interface for loading up the short and long entries, loading up the menus, providing access to see-also items, etc.

At this point it probably goes without saying that ngdb is likely only really useful to anyone who knows what a Norton Guide is and cares about the content. As such, at least for the moment, this documentation will (with apologies) assume some knowledge of what a Norton Guide is and its main structure.

Opening a guide

As mentioned above, a guide can be opened using the NortonGuide class. For example:

>>> from ngdb import NortonGuide
>>> guide = NortonGuide("tests/guides/oslib.ng")

Having loaded the guide you have access to the key information about it:

>>> guide.title
'OSLIB v1.06'
>>> guide.credits
('³ OSLIB v1.06', '³ OSLIB Is Free Software with NO WARRANTY!', '³', '³ This library was compiled by Dave Pearson.', '³ davep@hagbard.demon.co.uk')
>>> guide.made_with
'Norton Guide'
>>> guide.menu_count
1
>>> guide.menus
(<Menu: OSLIB>,)
>>> guide.menus[0]
<Menu: OSLIB>
>>> guide.menus[0].title
'OSLIB'
>>> guide.menus[0].prompts
('Functions', 'FAQs', 'Revision History', 'Credits', 'About')

The NortonGuide class can also be used with Python's with statement, making it easy to quickly open a file and work with it. Here's an example of a small tool that will open a guide and prints its title:

from ngdb import NortonGuide

if __name__ == "__main__":
    with NortonGuide("tests/guides/oslib.ng") as guide:
        print(guide.title)

Three methods exist for navigating a guide: goto_first, goto and skip. As you may imagine, goto_first goes to the first entry in a guide, goto goes to an entry at a specific byte offset in the guide, and skip skips the current entry.

Tip

It should be noted here that an open guide has the concept of a location pointer. As you do things with the guide, the location will change.

When skipping through a Norton Guide, if you try and skip off the end of the file, an NGEOF exception will be thrown.

Here's a simple example of all of this in action:

from ngdb import NGEOF, NortonGuide

if __name__ == "__main__":
    with NortonGuide("tests/guides/oslib.ng") as guide:
        guide.goto_first()
        while True:
            print("Found an entry")
            try:
                guide.skip()
            except NGEOF:
                print("Hit the end of the guide!")
                break

While that example is fine for illustrating the NGEOF exception, really it would make more sense to use the eof property:

from ngdb import NortonGuide

if __name__ == "__main__":
    with NortonGuide("tests/guides/oslib.ng") as guide:
        guide.goto_first()
        while not guide.eof:
            print("Found an entry")
            guide.skip()

Reading entries

The most important content of a Norton Guide is its entries. These come in two varieties, short entries and long entries. An entry is loaded using load and the correct type of entry will be returned.

Here is an example of walking through a guide and printing out the types of entries found:

from ngdb import Long, NortonGuide, Short

if __name__ == "__main__":
    with NortonGuide("tests/guides/oslib.ng") as guide:
        guide.goto_first()
        while not guide.eof:
            entry = guide.load()
            if isinstance(entry, Short):
                print("Short")
            elif isinstance(entry, Long):
                print("Long")
            else:
                print("This can't be possible")
            guide.skip()

Next steps

There's a lot more here that needs documenting, and over time I aim to expand this guide. For now though, if you are familiar with Norton Guide files and what they contain, the above should be enough to get you going with the library.

The next step would be to read the lower-level API documentation for the code, especially looking at the full documentation for the following:

  • NortonGuide: for navigating the guide itself.
  • Entry: for common entry properties and methods.
  • Short: for short entry properties and methods.
  • Long: for long entry properties and methods.
  • BaseParser: for the base class for entry content parsers; this is what you'll inherit from if you want to write your own parser/converter to go from a guide's content to some other format.
  • PlainText: an example parser that converts an entry's text into plain text.
  • MarkupText: an example parser that acts as the base class for parsers/converters that are markup-based; this would be a good place to inherit from if you want to make a Norton Guide to HTML converter.
  • RichText: an example implementation of MarkupText that converts the content of an entry to Rich's markup.