# ngdb - A Python library for reading Norton Guide database files
[](https://badge.fury.io/py/ngdb)
## Introduction
Back in the mists of time, in the days of MS-DOS and Clipper programming,
[Norton Guide database files](https://en.wikipedia.org/wiki/Norton_Guides)
were a very popular form of hypertext help. Lots of information is still
kicking around inside such files.
This library is another in [a reasonably long line of tools I've written to
help keep that information available](http://www.davep.org/norton-guides/).
## Installing
`ngdb` is [available from pypi](https://pypi.org/project/ngdb/) and can be
installed with `pip` or similar Python package tools:
```shell
$ pip3 install -U ngdb
```
## Tools
`ngdb` also installs the following tools:
- `nginfo`
Simple tool that serves as an example of using the library: given a series
of files on the command line, it prints a simple list of the files showing
what type of NG file it is (Norton Guide or Expert Help), as well as its
title.
## Hacking
If you want to hack on the code yourself you'll find most of the routine
stuff you'd do when testing and the like in the `Makefile`. Type:
```sh
$ make help
```
to get a list of available targets.
## Using
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, etc. The library is designed to
be the core of such tools. One such tool, which as of the time of writing is
a work in progress, is [`ng2web`](https://github.com/davep/ng2web) -- a
template-driven tool that converts Norton Guide databases into HTML.
The main class in this library 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 this library 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 README 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:
```python
>>> from ngdb import NortonGuide
>>> guide = NortonGuide( "tests/guides/oslib.ng" )
```
Having loaded the guide you have access to the key information about it:
```python
>>> 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')
```
And so on. See the documentation produced by `make rtfm` for all the details
(eventually I aim to find a good way of generating and hosting full
documentation).
### Navigating a guide
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.
It should be noted here that an open guide has the content of a location
pointer. As you do things with the guide, the location will change.
When skipping, if you try and skip off the end of the file, a
`ngdb.types.NGEOF` will be thrown.
### Loading an entry
Load the current entry with the `load` method. Note that using this method
*doesn't* move the location pointer. When loading an entry you'll either get
a `Short` or a `Long` entry back. For example:
```python
>>> entry = guide.load()
>>> entry
<Short>
>>> entry.lines[ 0 ]
' OL_95AppTitle() Set/get the Windows 95 application title.'
```
Plenty of properties that you'd expect exist. For now please take a look at
`make rtfm` for all the details (again, more comprehensive documentation
will be written).
### A simple example
To illustrate a simple use of the library, here's tiny bit of example code
that loads a guide, walks through all the entries, and prints the first line
from each one:
```python
from ngdb import NortonGuide
guide = NortonGuide( "tests/guides/oslib.ng" )
while not guide.eof:
print( guide.load().lines[ 0 ] )
guide.skip()
```
## Taking it from here
As mentioned above, there's a lot more to the library and the documentation
absolutely needs expanding. For now a `make rtfm` within the repository will
make the core documentation available. What needs to be added is a proper
tutorial on how to use the library to build a useful too.
This will follow.
Meanwhile, do also keep an eye on
[`ng2web`](https://github.com/davep/ng2web) as an example use. It is the
"proper" test of this library.
[//]: # (README.md ends here)
Raw data
{
"_id": null,
"home_page": "https://github.com/davep/ngdb.py",
"name": "ngdb",
"maintainer": "Dave Pearson",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "davep@davep.org",
"keywords": "library, dbase, clipper, norton guide reader",
"author": "Dave Pearson",
"author_email": "davep@davep.org",
"download_url": "https://files.pythonhosted.org/packages/ae/f8/e6c3bb9ac5b456ef75180e5b504492c6dcb65080c96fb65c36fbdf5ef764/ngdb-0.6.2.tar.gz",
"platform": null,
"description": "# ngdb - A Python library for reading Norton Guide database files\n\n[](https://badge.fury.io/py/ngdb)\n\n## Introduction\n\nBack in the mists of time, in the days of MS-DOS and Clipper programming,\n[Norton Guide database files](https://en.wikipedia.org/wiki/Norton_Guides)\nwere a very popular form of hypertext help. Lots of information is still\nkicking around inside such files.\n\nThis library is another in [a reasonably long line of tools I've written to\nhelp keep that information available](http://www.davep.org/norton-guides/).\n\n## Installing\n\n`ngdb` is [available from pypi](https://pypi.org/project/ngdb/) and can be\ninstalled with `pip` or similar Python package tools:\n\n```shell\n$ pip3 install -U ngdb\n```\n\n## Tools\n\n`ngdb` also installs the following tools:\n\n- `nginfo` \nSimple tool that serves as an example of using the library: given a series\nof files on the command line, it prints a simple list of the files showing\nwhat type of NG file it is (Norton Guide or Expert Help), as well as its\ntitle.\n\n## Hacking\n\nIf you want to hack on the code yourself you'll find most of the routine\nstuff you'd do when testing and the like in the `Makefile`. Type:\n\n```sh\n$ make help\n```\n\nto get a list of available targets.\n\n## Using\n\nThe library is designed to provide a method of opening and reading Norton\nGuide database files. The code here provides no methods for rendering the\ncontent; there is no converter, no reader, etc. The library is designed to\nbe the core of such tools. One such tool, which as of the time of writing is\na work in progress, is [`ng2web`](https://github.com/davep/ng2web) -- a\ntemplate-driven tool that converts Norton Guide databases into HTML.\n\nThe main class in this library is `NortonGuide`. When called, with the path\nto a Norton Guide file, it will open up the guide, load up all the key\ninformation, and provide an interface for loading up the short and long\nentries, loading up the menus, providing access to see-also items, etc.\n\nAt this point it probably goes without saying that this library is likely\nonly really useful to anyone who knows what a Norton Guide is and cares\nabout the content. As such, at least for the moment, this README will (with\napologies) assume some knowledge of what a Norton Guide is and its main\nstructure.\n\n### Opening a guide\n\nAs mentioned above, a guide can be opened using the `NortonGuide` class. For\nexample:\n\n```python\n>>> from ngdb import NortonGuide\n>>> guide = NortonGuide( \"tests/guides/oslib.ng\" )\n```\n\nHaving loaded the guide you have access to the key information about it:\n\n```python\n>>> guide.title\n'OSLIB v1.06'\n>>> guide.credits\n('\u00b3 OSLIB v1.06', '\u00b3 OSLIB Is Free Software with NO WARRANTY!', '\u00b3', '\u00b3 This library was compiled by Dave Pearson.', '\u00b3 davep@hagbard.demon.co.uk')\n>>> guide.made_with\n'Norton Guide'\n>>> guide.menu_count\n1\n>>> guide.menus\n(<Menu: OSLIB>,)\n>>> guide.menus[ 0 ]\n<Menu: OSLIB>\n>>> guide.menus[ 0 ].title\n'OSLIB'\n>>> guide.menus[ 0 ].prompts\n('Functions', 'FAQs', 'Revision History', 'Credits', 'About')\n```\n\nAnd so on. See the documentation produced by `make rtfm` for all the details\n(eventually I aim to find a good way of generating and hosting full\ndocumentation).\n\n### Navigating a guide\n\nThree methods exist for navigating a guide: `goto_first`, `goto` and `skip`.\nAs you may imagine, `goto_first` goes to the first entry in a guide, `goto`\ngoes to an entry at a specific byte offset in the guide, and `skip` skips\nthe current entry.\n\nIt should be noted here that an open guide has the content of a location\npointer. As you do things with the guide, the location will change.\n\nWhen skipping, if you try and skip off the end of the file, a\n`ngdb.types.NGEOF` will be thrown.\n\n### Loading an entry\n\nLoad the current entry with the `load` method. Note that using this method\n*doesn't* move the location pointer. When loading an entry you'll either get\na `Short` or a `Long` entry back. For example:\n\n```python\n>>> entry = guide.load()\n>>> entry\n<Short>\n>>> entry.lines[ 0 ]\n' OL_95AppTitle() Set/get the Windows 95 application title.'\n```\n\nPlenty of properties that you'd expect exist. For now please take a look at\n`make rtfm` for all the details (again, more comprehensive documentation\nwill be written).\n\n### A simple example\n\nTo illustrate a simple use of the library, here's tiny bit of example code\nthat loads a guide, walks through all the entries, and prints the first line\nfrom each one:\n\n```python\nfrom ngdb import NortonGuide\n\nguide = NortonGuide( \"tests/guides/oslib.ng\" )\n\nwhile not guide.eof:\n print( guide.load().lines[ 0 ] )\n guide.skip()\n```\n\n## Taking it from here\n\nAs mentioned above, there's a lot more to the library and the documentation\nabsolutely needs expanding. For now a `make rtfm` within the repository will\nmake the core documentation available. What needs to be added is a proper\ntutorial on how to use the library to build a useful too.\n\nThis will follow.\n\nMeanwhile, do also keep an eye on\n[`ng2web`](https://github.com/davep/ng2web) as an example use. It is the\n\"proper\" test of this library.\n\n[//]: # (README.md ends here)\n",
"bugtrack_url": null,
"license": "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
"summary": "Norton Guide database reading library",
"version": "0.6.2",
"project_urls": {
"Discussions": "https://github.com/davep/ngdb/discussions",
"Documentation": "https://github.com/davep/ngdb/blob/main/README.md",
"Homepage": "https://github.com/davep/ngdb.py",
"Issues": "https://github.com/davep/ngdb/issues",
"Source": "https://github.com/davep/ngdb"
},
"split_keywords": [
"library",
" dbase",
" clipper",
" norton guide reader"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d2a7611784edffb3e8bb9c065a5330400571fa6bfc56bf3cb2096add4efb92fd",
"md5": "b50a09076f62fdbeabc3e2e23fb92cd0",
"sha256": "56dd4e2bd25a5f07d76ca686f12b8ab34cd87425b3f29b389377bc27eb1a495e"
},
"downloads": -1,
"filename": "ngdb-0.6.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b50a09076f62fdbeabc3e2e23fb92cd0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 27869,
"upload_time": "2024-04-02T07:16:06",
"upload_time_iso_8601": "2024-04-02T07:16:06.053963Z",
"url": "https://files.pythonhosted.org/packages/d2/a7/611784edffb3e8bb9c065a5330400571fa6bfc56bf3cb2096add4efb92fd/ngdb-0.6.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aef8e6c3bb9ac5b456ef75180e5b504492c6dcb65080c96fb65c36fbdf5ef764",
"md5": "32f921648e76c61591a43248a0bca7ba",
"sha256": "f1dcfe47be89e511ef355193ed9d71c28fea2399d03ae40955f25698a7e3e183"
},
"downloads": -1,
"filename": "ngdb-0.6.2.tar.gz",
"has_sig": false,
"md5_digest": "32f921648e76c61591a43248a0bca7ba",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24206,
"upload_time": "2024-04-02T07:16:07",
"upload_time_iso_8601": "2024-04-02T07:16:07.886987Z",
"url": "https://files.pythonhosted.org/packages/ae/f8/e6c3bb9ac5b456ef75180e5b504492c6dcb65080c96fb65c36fbdf5ef764/ngdb-0.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-02 07:16:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "davep",
"github_project": "ngdb.py",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "ngdb"
}
JSON
