fpman

manpages for Free Pascal Compiler.

Why and how?

Mostly because I grew fed up with having to read FPC documentation in the browser and thought to myself "wouldn't it be nice to have manpages?" Y'know, instead of having to click and manuever through the index files, being able to just type in the subject and have the appropriate manpage appear right there in the terminal.

fpman works by performing crude string matching on HTML files generated by fpdoc in order to convert them into troff files, which man can read. It then stores the converted pages in the user's home directory, keeping a list of pages in an SQLite database for quick searching.

Wouldn't it make more sense to add troff output to fpdoc?

Probably, yeah. But as we all know, working with other people's code takes some diving in, whereas if you code your own stuff, you can start hacking right away - and my lazy ass didn't really feel like going into fpdoc source. That is to say, I may consider working on troff output for fpdoc in the future.

Still, even if fpdoc could output troff, you'd still need for the documentation maintainer to provide you with the .man files to use (or generate them yourself, if you have both the .pas sources and .xml docs). By mutilating HTML files, fpman is able to provide manpages without the need for anyone to do any extra work on the docs.

Dependencies

Quite obviously, fpman requires man to run. sqlite3 is used for, well, manipulation on the page database. Also, rm is required, but I'd be seriously worried about the state of your system if that wasn't available.

Usage

Usage: fpman OPTION | PAGE
 PAGE
        When no option is specified, fpman requires a PAGE argument. It will
        then search its sqlite database for a matching entry. For routines and
        properties which are part of object / class / interface definition,
        PAGE must be in TYPE.MEMBER format. To avoid ambiguity, PAGE can be
        prefixed with unit name, and even package name, if required - as in
        package.unit.page. The wildcards ? * can be used in PAGE. If the page
        is found, fpman will execute man to display it. If multiple matching
        pages are found, fpman will print a list of matching pages and ask
        which page to display.

 --list PAGE
        Like the default mode of operation, except that instead of firing man,
        prints a summary of each matching page.

 --import PATH
        Imports .html or .man documentation files from PATH to fpman library.
        PATH can specify either a single file to import, or a directory to
        scan for .html/.man files. Subdirectories will be scanned recursively.

 --purge[=SECTION]
        Cleans fpman library directory and sqlite database. If SECTION is
        specified, instead of the whole library, only the selected part will
        be purged. SECTION must be in "type:name" format, where type must be
        either "package" or "unit". Unit names can be prefixed with the
        package name, followed by a dot, to avoid ambiguity.

 --rebuild[=SECTION]
        Purges fpman sqlite database, and then rebuilds its contents based on
        files found in the library directory. SECTION can be used in the same
        manner as in the --purge option.

 --revalidate[=SECTION]
        Looks through all the entries present in sqlite database and checks if
        their manpages are still in library. Any dead entries are removed from
        the database. SECTION can be used in the same manner as in --purge or
        --rebuild options.

 --help
        Displays this help list and exits.

 --version
        Displays version information and exits.

To get started with fpman, you can either download FPC documentation in HTML format from here and run fpman --import, or clone this repo and either run fpman --import on the pre-converted pages, or copy the whole pages/ directory to ~/.suve/fpman/ and then run fpman --rebuild.

Note: Import / rebuild can take a couple of minutes.

Once you've got some manpages imported, just run fpman PAGE and the program will search its library for your desired topic. The search is case-insensitive. To avoid ambiguity, you can prefix the page with the name of the unit, e.g. fpman system.read.

Building

fpman, as a tool for Free Pascal enthusiasts, is also written in Pascal. Thus, you're going to need a Pascal compiler (for obvious reasons, I recommend FPC) and also the dev packages for sqlite3.

In Fedora, you can do this by running (don't forget root):

yum install fpc sqlite-devel

Or, if you're using Ubuntu:

apt-get install fpc libsqlite3-dev

No additional steps are needed before compiling, so you can just tap in fpc fpman.pas. Or, if you insist on using make:

cd src/
make release

Note: sometimes when recompiling, FPC seems to have problems with the program's use of generics and simply crashes. This can be worked around by simply running make clean, forcing a full recompile.

License

fpman is available under the terms of a slightly modified zlib license. For full text of the license, check LICENSE.txt.