Metadata-Version: 2.1 Name: amiman Version: 0.1.1 Summary: Browse Amiga autodoc pages like man pages on your modern system Author-email: Christian Vogelgsang License: MIT Keywords: AmigaOS,autodoc,man page Classifier: Development Status :: 4 - Beta Classifier: Intended Audience :: Developers Classifier: Programming Language :: Python Classifier: Topic :: System :: Emulators Requires-Python: >=3.7 Description-Content-Type: text/markdown License-File: LICENSE Requires-Dist: termcolor # 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 |