| Name | amiman JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | Browse Amiga autodoc pages like man pages on your modern system |
| upload_time | 2024-05-27 17:08:33 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
amigaos
autodoc
man page
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# aman - Read Amiga autodocs like man pages
This little tool allows you to read your Amiga NDK's `autodoc` documentation
on your modern system with a Un*x `man page` like interface.
## Quick Start
Just give a function name you need information on and you get the
documentation page instantly:
❯ aman GetMsg
exec.library/GetMsg
NAME
GetMsg -- get next message from a message port
SYNOPSIS
message = GetMsg(port)
D0 A0
struct Message *GetMsg(struct MsgPort *);
FUNCTION
This function receives a message from a given message port. It
provides a fast, non-copying message receiving mechanism. The
received message is removed from the message port.
...
It will show documentation for exec's `GetMsg()` call.
By default your pager (set by `MANPAGER` or `PAGER` env variable) will be used
for browsing the documents. Use `--no-pager` option to write the output to
your console directly.
You could also search for references (aka SEE ALSO) of a function name:
> aman -s send
bsdsocket.library/-icmp-
bsdsocket.library/-ip-
bsdsocket.library/-udp-
bsdsocket.library/ObtainSocket
bsdsocket.library/ReleaseCopyOfSocket
bsdsocket.library/ReleaseSocket
bsdsocket.library/SetSocketSignals
bsdsocket.library/socket
bsdsocket.library/WaitSelect
## Installation
The `aman` tool can be installed with (note the different name):
pip install amiman
The only step missing is to tell `aman` where the Amiga NDK autodocs are
located:
export AMANPATH=/my/path/to/NDK/autodocs:/my/path/to/NDK/sana+roadshowtcp-ip/doc
or you create a config file in `$HOME/.aman/config.json`:
{
"aman_config": 1,
"man_paths" : [
"/my/path/to/NDK/autodocs",
"/my/path/to/NDK/sana+roadshowtcp-ip/doc"
]
}
## Reference Manual
### Terms
To better understand the options of `aman` a few terms need to be defined:
* A single *book* is contained in an *autodoc* file with extension `*.doc`.
A book starts with a table of contents (TOC) and is followed by *pages*.
* Each *page* in a *book* contains a description of a function or more
informational contents. A page contains a heading with a *topic* and a
*title* separated by a slash.
* *Topics* in a *book* structure the pages. Typically a *book* contains only
pages of a single topic. E.g. the `exec` book only contains pages with the
`exec.library` topic. In some books multiple topics are found.
* The *title* of a page gives the function name of a page describing a
function. A more generic title is used for informational content.
* A *page* is composed of a set of *sections*. The *section* structure on
each page in a book is typically the same but may differ between books.
Same named *sections* provide similar content, e.g. a *NAME* section
always gives the name of a function. Common sections are NAME, SYNOPSIS,
SEE ALSO.
### Command Line Options
#### Common Options
`aman` offers a large set of options that can adjust the operation of the
tool. Call `aman -h` to see all options.
options:
-h, --help show this help message and exit
-v, --verbose be more verbose
Use `-v` to see internal details on the operation of `aman`. Repeat `-v` to
increase the verboseness.
#### Mode Options
mode options:
-b, --list-books show available books and quit
-p LIST_PAGES, --list-pages LIST_PAGES
show available pages of a given book and quit
`aman` can operate in different modes: By default the search mode is active.
In search mode keywords are searched in the autodocs and the resulting pages
are shown.
The `-b` options lists all books found in the `aman_paths` and a list with the
book name and the contained topics is given. If the topic and the book have
the same name then the topic is omitted:
> aman -b
8svx_dtc 8svx.datatype
acbm_dtc acbm.datatype
amiga_lib amiga.lib
amigaguide amigaguide.library
amigaguide_dtc amigaguide, amigaguide.class
anim_dtc anim.datatype
animation_dtc anim.datatype, animation.datatype
arexx_cl
...
The `-p` option lists the pages of a book. Just give a name of a book and a
list with the topic/title of each page is given:
> aman -p cia
cia.resource/AbleICR
cia.resource/AddICRVector
cia.resource/RemICRVector
cia.resource/SetICR
#### Search Options
search options:
keywords keywords to search for
-i, --ignore-case ignore case in keyword match
-t, --topic search with 'topic/keyword'
-s, --see-also search in SEE ALSO section
-f FULL_SECTION, --full-section FULL_SECTION
full text search in given SECTION of page
-F, --full-page full text search in page
-B LIMIT_BOOKS, --limit-books LIMIT_BOOKS
only search in these books (list seperated by colon)
In search mode you need to give one or more `keywords`. Each keyword is
searched and the found pages are shown.
By default the search is case sensitive, i.e. the keyword must match exactly.
If you specify the `-i` option then matches are found ignoring the case.
The following different search modes are available:
* No option: the keyword has to match the *title* of a page, e.g. `AllocMem`
will find the AllocMem function.
* `-t` option: the keyword has to match the *topic/title* of a page, e.g.
`exec.library/AllocMem` is required to match the AllocMem function.
* `-s` option: the keyword has to match one entry in the *SEE ALSO* section
of a page. E.g. `aman -s send` will return all pages that refer to the
send function.
* `-f section` option: The keyword is searched in the given *section* on
each page of all books. This is a full text search and considerably slower
than the index based searches above.
* `-F` option: The keyword is searched in all pages of each book. This full
text search is a slow operation.
The `-B` option allows to limit the search on a set of books only. Just give a
colon-separated list of books. Use the `-b` option to find out the names of
books available.
### Output Options
output options:
-N, --no-pager disable pager
-P PAGER, --pager PAGER
pager command line
-a, --all-pages show multiple results as pages and no list
-r, --raw-page show raw page of autodoc otherwise reformat and colorize
--color use colorful output
--no-color disable colorful output
-j, --json output in json format
By default the pages are output via a pager program if a tty is detected as
output device. Otherwise the output is written directly to stdout.
If multiple pages are found then a list of the matches is shown by default. If
you want to see the pages instead then use the `-a` option.
A page is rendered from the interal representation in `aman`. If possible on a
terminal then also some color or display attributes are applied. If you give
the `-r` option then the original formatting is preserved. Coloring can be
adjusted with `--color` or `--no-color` if the auto detection does not work.
If a tty is found and the `-N` option is given then the output is also written
directly to stdout. The `-P` option allows you to specify the pager command to
display the pages. The command has to accept the page input via stdin.
The `-j` option allows you to output a page in the internal JSON structure
used to store pages. This output might be useful if you want to post-process
the pages.
### Config Options
config options:
-M MAN_PATH, --man-path MAN_PATH
Define the paths of the Amiga autodocs
-C CACHE_DIR, --cache-dir CACHE_DIR
directory for cache files
-c CONFIG_FILE, --config-file CONFIG_FILE
config file
--dump-config dump current config into file
-R, --rebuild-cache force recreation of index cache
These options allow you to configure `aman`. Most of these options don't need
adjustment on the command line (`-M` or `-C`). You better set them via
environment variables or in the config file (see below).
With `-c` you can choose another location for the config file. The default
is `$HOME/.aman/config.json`. The `--dump-config` command will create this
file for you if it does not exist yet. Adapt this template to your needs.
The `-R` option is only needed if the cache files are in an inconsistent state
and need to be rebuild. Note that only the indices in the cache are rebuild
that are needed for the current search. A better way to completely clean the
cache is to wipe the cache directory (default: `$HOME/.aman/cache/`).
### Configuration
`aman` can be configured in three different ways:
* from a config file (`$HOME/.aman/config.json`)
* via environment variables
* with command line options (see above)
An option defined in a later stage overwrites the previous setting.
#### Json Config File
You can write the options into a JSON config file located at
`$HOME/.aman/config.json`:
{
"aman_config": 1,
"man_paths": [ /path/to/autodocs, /more/paths/to/autodocs ],
"cache_dir": "/path/to/cache",
"pager": "/usr/bin/less -R --use-color -Ddg -Du+y"
}
The version tag `aman_config` is required otherwise the config file is not
accepted. The other options are similar to the command line options.
#### Environment Variables
The following variables in the environment are used to configure `aman`:
| Variable | Description |
| -------- | --------------- |
| `AMANPATH` | list of autodoc directories, separated by '`:`' |
| `AMANCACHE` | directory of cache files (default `~/.aman/cache`) |
| `MANPAGER` | set the default display program |
| `PAGER` | set the default display program (if no `MANPAGER`) is given |
Raw data
{
"_id": null,
"home_page": null,
"name": "amiman",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "AmigaOS, autodoc, man page",
"author": null,
"author_email": "Christian Vogelgsang <chris@vogelgsang.org>",
"download_url": null,
"platform": null,
"description": "# aman - Read Amiga autodocs like man pages\n\nThis little tool allows you to read your Amiga NDK's `autodoc` documentation\non your modern system with a Un*x `man page` like interface.\n\n## Quick Start\n\nJust give a function name you need information on and you get the\ndocumentation page instantly:\n\n \u276f aman GetMsg\n exec.library/GetMsg\n\n NAME\n GetMsg -- get next message from a message port\n\n SYNOPSIS\n message = GetMsg(port)\n D0 A0\n\n struct Message *GetMsg(struct MsgPort *);\n\n FUNCTION\n This function receives a message from a given message port. It\n provides a fast, non-copying message receiving mechanism. The\n received message is removed from the message port.\n ...\n \nIt will show documentation for exec's `GetMsg()` call. \n\nBy default your pager (set by `MANPAGER` or `PAGER` env variable) will be used\nfor browsing the documents. Use `--no-pager` option to write the output to\nyour console directly.\n\nYou could also search for references (aka SEE ALSO) of a function name:\n\n > aman -s send\n bsdsocket.library/-icmp-\n bsdsocket.library/-ip-\n bsdsocket.library/-udp-\n bsdsocket.library/ObtainSocket\n bsdsocket.library/ReleaseCopyOfSocket\n bsdsocket.library/ReleaseSocket\n bsdsocket.library/SetSocketSignals\n bsdsocket.library/socket\n bsdsocket.library/WaitSelect\n\n## Installation\n\nThe `aman` tool can be installed with (note the different name):\n\n pip install amiman\n\nThe only step missing is to tell `aman` where the Amiga NDK autodocs are\nlocated:\n\n export AMANPATH=/my/path/to/NDK/autodocs:/my/path/to/NDK/sana+roadshowtcp-ip/doc\n\nor you create a config file in `$HOME/.aman/config.json`:\n\n {\n \"aman_config\": 1,\n \"man_paths\" : [\n \"/my/path/to/NDK/autodocs\",\n \"/my/path/to/NDK/sana+roadshowtcp-ip/doc\"\n ]\n }\n \n## Reference Manual\n\n### Terms\n\nTo better understand the options of `aman` a few terms need to be defined:\n\n * A single *book* is contained in an *autodoc* file with extension `*.doc`.\n A book starts with a table of contents (TOC) and is followed by *pages*.\n * Each *page* in a *book* contains a description of a function or more\n informational contents. A page contains a heading with a *topic* and a\n *title* separated by a slash.\n * *Topics* in a *book* structure the pages. Typically a *book* contains only\n pages of a single topic. E.g. the `exec` book only contains pages with the\n `exec.library` topic. In some books multiple topics are found.\n * The *title* of a page gives the function name of a page describing a\n function. A more generic title is used for informational content.\n * A *page* is composed of a set of *sections*. The *section* structure on\n each page in a book is typically the same but may differ between books.\n Same named *sections* provide similar content, e.g. a *NAME* section\n always gives the name of a function. Common sections are NAME, SYNOPSIS,\n SEE ALSO.\n\n### Command Line Options\n\n#### Common Options\n\n`aman` offers a large set of options that can adjust the operation of the\ntool. Call `aman -h` to see all options.\n\n options:\n -h, --help show this help message and exit\n -v, --verbose be more verbose\n\nUse `-v` to see internal details on the operation of `aman`. Repeat `-v` to\nincrease the verboseness.\n\n#### Mode Options\n\n mode options:\n -b, --list-books show available books and quit\n -p LIST_PAGES, --list-pages LIST_PAGES\n show available pages of a given book and quit\n\n`aman` can operate in different modes: By default the search mode is active.\nIn search mode keywords are searched in the autodocs and the resulting pages\nare shown.\n\nThe `-b` options lists all books found in the `aman_paths` and a list with the\nbook name and the contained topics is given. If the topic and the book have\nthe same name then the topic is omitted:\n\n > aman -b\n 8svx_dtc 8svx.datatype\n acbm_dtc acbm.datatype\n amiga_lib amiga.lib\n amigaguide amigaguide.library\n amigaguide_dtc amigaguide, amigaguide.class\n anim_dtc anim.datatype\n animation_dtc anim.datatype, animation.datatype\n arexx_cl\n ...\n\nThe `-p` option lists the pages of a book. Just give a name of a book and a\nlist with the topic/title of each page is given:\n\n > aman -p cia\n cia.resource/AbleICR\n cia.resource/AddICRVector\n cia.resource/RemICRVector\n cia.resource/SetICR\n\n#### Search Options\n\n search options:\n keywords keywords to search for\n -i, --ignore-case ignore case in keyword match\n -t, --topic search with 'topic/keyword'\n -s, --see-also search in SEE ALSO section\n -f FULL_SECTION, --full-section FULL_SECTION\n full text search in given SECTION of page\n -F, --full-page full text search in page\n -B LIMIT_BOOKS, --limit-books LIMIT_BOOKS\n only search in these books (list seperated by colon)\n\nIn search mode you need to give one or more `keywords`. Each keyword is\nsearched and the found pages are shown.\n\nBy default the search is case sensitive, i.e. the keyword must match exactly.\nIf you specify the `-i` option then matches are found ignoring the case.\n\nThe following different search modes are available:\n\n * No option: the keyword has to match the *title* of a page, e.g. `AllocMem`\n will find the AllocMem function.\n * `-t` option: the keyword has to match the *topic/title* of a page, e.g.\n `exec.library/AllocMem` is required to match the AllocMem function.\n * `-s` option: the keyword has to match one entry in the *SEE ALSO* section\n of a page. E.g. `aman -s send` will return all pages that refer to the\n send function.\n * `-f section` option: The keyword is searched in the given *section* on\n each page of all books. This is a full text search and considerably slower\n than the index based searches above.\n * `-F` option: The keyword is searched in all pages of each book. This full\n text search is a slow operation.\n\nThe `-B` option allows to limit the search on a set of books only. Just give a\ncolon-separated list of books. Use the `-b` option to find out the names of\nbooks available.\n\n### Output Options\n\n output options:\n -N, --no-pager disable pager\n -P PAGER, --pager PAGER\n pager command line\n -a, --all-pages show multiple results as pages and no list\n -r, --raw-page show raw page of autodoc otherwise reformat and colorize\n --color use colorful output\n --no-color disable colorful output\n -j, --json output in json format\n\nBy default the pages are output via a pager program if a tty is detected as\noutput device. Otherwise the output is written directly to stdout.\n\nIf multiple pages are found then a list of the matches is shown by default. If\nyou want to see the pages instead then use the `-a` option.\n\nA page is rendered from the interal representation in `aman`. If possible on a\nterminal then also some color or display attributes are applied. If you give\nthe `-r` option then the original formatting is preserved. Coloring can be\nadjusted with `--color` or `--no-color` if the auto detection does not work.\n\nIf a tty is found and the `-N` option is given then the output is also written\ndirectly to stdout. The `-P` option allows you to specify the pager command to\ndisplay the pages. The command has to accept the page input via stdin.\n\nThe `-j` option allows you to output a page in the internal JSON structure\nused to store pages. This output might be useful if you want to post-process\nthe pages.\n\n### Config Options\n\n config options:\n -M MAN_PATH, --man-path MAN_PATH\n Define the paths of the Amiga autodocs\n -C CACHE_DIR, --cache-dir CACHE_DIR\n directory for cache files\n -c CONFIG_FILE, --config-file CONFIG_FILE\n config file\n --dump-config dump current config into file\n -R, --rebuild-cache force recreation of index cache\n\nThese options allow you to configure `aman`. Most of these options don't need\nadjustment on the command line (`-M` or `-C`). You better set them via\nenvironment variables or in the config file (see below).\n\nWith `-c` you can choose another location for the config file. The default\nis `$HOME/.aman/config.json`. The `--dump-config` command will create this\nfile for you if it does not exist yet. Adapt this template to your needs.\n\nThe `-R` option is only needed if the cache files are in an inconsistent state\nand need to be rebuild. Note that only the indices in the cache are rebuild\nthat are needed for the current search. A better way to completely clean the\ncache is to wipe the cache directory (default: `$HOME/.aman/cache/`).\n\n### Configuration\n\n`aman` can be configured in three different ways:\n\n * from a config file (`$HOME/.aman/config.json`)\n * via environment variables\n * with command line options (see above)\n\nAn option defined in a later stage overwrites the previous setting.\n\n#### Json Config File\n\nYou can write the options into a JSON config file located at\n`$HOME/.aman/config.json`:\n\n {\n \"aman_config\": 1,\n \"man_paths\": [ /path/to/autodocs, /more/paths/to/autodocs ],\n \"cache_dir\": \"/path/to/cache\",\n \"pager\": \"/usr/bin/less -R --use-color -Ddg -Du+y\"\n }\n\nThe version tag `aman_config` is required otherwise the config file is not\naccepted. The other options are similar to the command line options.\n\n#### Environment Variables\n\nThe following variables in the environment are used to configure `aman`:\n\n| Variable | Description |\n| -------- | --------------- |\n| `AMANPATH` | list of autodoc directories, separated by '`:`' | \n| `AMANCACHE` | directory of cache files (default `~/.aman/cache`) |\n| `MANPAGER` | set the default display program |\n| `PAGER` | set the default display program (if no `MANPAGER`) is given |\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Browse Amiga autodoc pages like man pages on your modern system",
"version": "0.1.1",
"project_urls": null,
"split_keywords": [
"amigaos",
" autodoc",
" man page"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ee907c82bfd104fb35b23b9262380026edbecf4f2809e994047bc7a39c7d280e",
"md5": "55ee83a0943e1c43ed91cb937c4f5cea",
"sha256": "67671d1d5a72ef2ac03427a42e501386165c4a3c5bd79df7db5804bcae4a316e"
},
"downloads": -1,
"filename": "amiman-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "55ee83a0943e1c43ed91cb937c4f5cea",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 19506,
"upload_time": "2024-05-27T17:08:33",
"upload_time_iso_8601": "2024-05-27T17:08:33.352339Z",
"url": "https://files.pythonhosted.org/packages/ee/90/7c82bfd104fb35b23b9262380026edbecf4f2809e994047bc7a39c7d280e/amiman-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-27 17:08:33",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "amiman"
}
