• Antelope Release 5.5 Mac OS X 10.8.5 2015-04-21

 

NAME

dbrtfm - tool to help read the full manual-page complement for Antelope

SYNOPSIS

dbrtfm [-t] [-s] [-l] [-S] [-m mode] [-q] [+n] [manpage [mansect]]

SUPPORT


Contributed code: NO BRTT support.
THIS PIECE OF SOFTWARE WAS CONTRIBUTED BY THE ANTELOPE USER COMMUNITY. BRTT DISCLAIMS ALL OWNERSHIP, LIABILITY, AND SUPPORT FOR THIS PIECE OF SOFTWARE.

FOR HELP WITH THIS PIECE OF SOFTWARE, PLEASE CONTACT THE CONTRIBUTING AUTHOR.

DESCRIPTION

The dbrtfm application is a tool designed to help one progressively read the full manual-page set for Antelope. Upon first execution, dbrtfm builds a database of all available man pages so the user can track which ones have been read. The location of this database is set by the parameter dbrtfm_database in the parameter file (the default is in the user's home directory); the database schema is dbrtfm1.0. Currently, the next unread man-page is chosen from those listed in the tracking database. If desired, an optional man-page name may be specified on the command line, in which case the first available man page with that name is shown. If a man-page section is specified also, that further constrains the selection. If the ignore_contrib parameter is set to true in the parameter file, man pages from the Antelope contributed-code distribution are ignored when the next unread manual page is chosen automatically. If the +n argument is used, where n is an integer, the specified number of man-pages are skipped past the next available man page, when nothing else is specified on the command line (i.e. when choosing the next unread man page automatically). If the -S option is used, a summary is printed of the number of man-pages read so far (assuming those with NULL value for the time field have not yet been read). dbrtfm sets the chosen file to the perl value $file, then eval's the perl-code given in the showman parameter of the parameter file, which should provide some way to display (or email, or print, or whatever is desired) the specified man-page on your system. One may specify several different modes of display in the showman parameter; barring overrides with the command-line arguments, the default is set by the default_mode parameter. After the dbrtfm run, dbrtfm asks the user to mark whether the man page has been read.

OPTIONS

PARAMETER FILE


default_mode pager

home &env(HOME)

dbrtfm_database &home/rtfmdb

ignore_contrib  yes

lines_per_full_page 60

showman &Arr{

        pager &Literal{

                if( defined( $ENV{PAGER} ) ) {

                        $pager = $ENV{PAGER};

                } else {

                        $pager = "more";
                }

                exec( "nroff -man $nroff | $pager" );
        }

        netscape &Literal{

                chomp( $rc = system( "netscape -remote 'ping()'" ) );
                if( $rc != 0 ) {

                        chomp( $whoami = `whoami` );
                        system( "netscape -P $whoami 'file://$file' &" );

                } else {

                        system( "netscape -remote 'openFILE($file)' &" );
                }
        }

        mozilla &Literal{

                chomp( $rc = system( "netscape -remote 'ping()'" ) );
                if( $rc != 0 ) {

                        chomp( $whoami = `whoami` );
                        system( "netscape -P $whoami 'file://$file' &" );

                } else {

                        system( "netscape -remote 'openFILE($file)' &" );
                }
        }

        pager &Literal{

                exec( "nroff -man $ENV{ANTELOPE}/man$section/$manpage
        }
}

EXAMPLE

% dbrtfm

  [a chosen man-page opens in a separate xterm and stays until exited]

dbrtfm: Mark not_threadsafe(3) as read? y

dbrtfm: Man-page
        'not_threadsafe(3)' by
        'Dan Quinlan'
marked as read at
        '11/27/2006   0:50:02.655 UTC'

%

% dbrtfm -S

dbrtfm report for </Users/testuser/rtfmdb>:
=======================================================

Ignoring contrib:
-----------------

  Distinct man-pages read:       142 of     741,  19% done,     599 left
               Lines read:     13759 of   84808,  16% done,   71049 left
   Equiv. full-text pages:       229 of    1413,  16% done,    1184 left

Including contrib:
------------------

  Distinct man-pages read:       151 of     978,  15% done,     827 left
               Lines read:     14264 of  115856,  12% done,  101592 left
   Equiv. full-text pages:       238 of    1931,  12% done,    1693 left
%

DIAGNOSTICS

dbrtfm: dbrtfm: initializing tracking database '/Users/kent/rtfmdb' dbrtfm: Build rtfm database '/Users/kent/rtfmdb' from scratch? (dbrtfm asks for confirmation before rebuilding the man-page database; this can avert the small mess when one accidentally uses the default parameter file instead of one that one has customized).

BUGS AND CAVEATS

The netscape and mozilla configurations of the parameter file do not open or raise the netscape/mozilla windows if they are iconified or buried. The command-line specification of man-pages works only for the actual names under which they are stored. One cannot, for example, use the command-line specification to call up the man page for something that is actually just a link to another man page. The line count for manual pages is based on the number of lines in the nroff source file, rather than the number of lines in the formatted text seen in a standard pager utility, which can be a bit misleading. This accounting strategy is a good approximation in bulk, however may be a small mistake (defensible, though, since line count is dependent on the exact configuration of the display utility). The matching done to figure out the author during initial database build is very, perhaps overly simplistic.

AUTHOR

Kent Lindquist
Lindquist Consulting, Inc.

Antelope User Group Contributed Software
Printer icon