amiman 0.1.1
Browse Amiga autodoc pages like man pages on your modern system
License: MIT
Requires Python: >=3.7
Keywords: AmigaOS, autodoc, man page

# 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 |