Mkhelp(1)
mkhelp - make a help book
As shipped in IRIX 6.5.7. Unchanged since IRIX 6.5.
NAME mkhelp - make a help book SYNOPSIS mkhelp [-fa] [-fi] [-si] [-nl] [-pub] [-comp] [-bkdb book_database] [-sl stop_list] [-output out_directory] book_name DESCRIPTION Mkhelp makes a help book given the name of the book to make. Although mkhelp will run over a networked file system (such as NFS), we highly recommend that this program be run on the file server where the book is found. Performance can be up to 10 times better when run locally. Mkhelp first looks to see if the book database (given either in the .ebtrc file or on the command line) exists. If it does not exist, it is created and initialized. Thus, to create a new book database, mkhelp should simply be run with either no parameters, or just the -bkdb parameter. If a valid book database already exists, mkhelp looks for a directory in the book database directory named books . Within this directory, mkhelp looks for a directory named book_name, where book_name is given on the command line. Within this directory, mkhelp looks for a file named book_name.sgm . Within the book directory, there should also be a directory called styles, containing the ascii style sheets for the book. Often, this directory is a symbolic link to a directory containing the stylesheets for a given DTD. Mkhelp works in three stages. First, the sgml file is compiled into a database directory, producing the directory ebt . Second, any toc stylesheets are used to build table of contents directories which are also stored in the ebt directory . Finally, the index for the book is created, and stored in the index database. Once mkhelp has run, you can remove the .sgml file from the book directory (still save it somewhere for later revisions), since the resulting files contain all of the information needed to display an sgml document. CONFIGURATIONS Mkhelp uses the .ebtrc file to find configurations. The .ebtrc file is found by the following method. EBTRC should be set to /usr/share/Insight/system.insightrc. If the EBTRC environment variable is set, its values is taken to be the path of the .ebtrc file. If not, the current directory is searched for a .ebtrc file. Finally, the user's home directory is searched for the .ebtrc file. The following configurations are used by Mkhelp. BOOK_DBASE, if set, is used as the database directory for books. The -bkdb command line option overrides this setting. DATA_DIR is used to find EBT general data, such as the help document. This should be set to the EBT data directory which is /usr/share/Insight/lib/data. OPTIONS -fa force all operation involved in the making of the book. All stages of the book are made regardless of when they were last made and if they are up to date. This option should be used when making books with a newly released version of mkhelp. -fi forces just the making of the full text index. The index is remade regardless of when it was last made and if it is out of date or not. -si suppresses the making of the full text index. The index is not made, regardless of when it was last made, or if it was last made. -nl sets no locking mode to on. In this case, books will not be locked. You are on your own to make sure that two users don't make the same book at the same time. Use this when the network will not allow locks to work correctly. -mem size sets the amount of memory mkhelp will use to size megabytes. The more memory used, the fewer flush files are created. By default, mkhelp uses only 4 MB on UNIX systems. -pub sets publishing to on. In this mode, mkhelp will create a book which is certified for publication for use with a stand-alone browser. It will print a message giving you the serial number which you should use to allow browsers to read this book. -comp sets compression on. In this mode, mkhelp will create a book which is more compressed than the norm. This might hurt performance. -bkdb book_database Sets the book database directory to book_database. This overrides the BOOK_DBASE setting in the .ebtrc. -sl stop_list Sets the stop list file for the indexer to stop_list. The full path is DATA_DIR/index/stop_list.stp. Any words on this list are not indexed. -out output_directory specifies a directory in which to output sgml data. This directory better not be the book directory, or else you will be warned an no directory will be used. The outputted information is an equivalent SGML file(s) containing unique EBTIDs, such that link information can be kept valid from revision to revision of the document. book_name Sets the name of the book to make to book_name. This option is required by EXAMPLES To make a book in the book database specified in the .ebtrc file, you might use this command: mkhelp my_book To make a book in the my_book_database, try this command: mkhelp -bkdb my_book_database my_book To make a book without a full text index, try this command: mkhelp -si my_book To force the making of a book, but to leave out the full text index, try this: mkhelp -fa -si my_book To force just the full text indexing of a book, use this command: mkhelp -fi my_book DIAGNOSTICS Along the way, mkhelp will try to keep the user informed of its progress. In most cases, it will not perform an operation if it can recognize that the operation has been performed since the last modification to the source file. Of course, it will notify the user about any operations it deems unnecessary to perform. If mkhelp finds an error in the sgml file or in a style sheet, it will print a friendly error message and abort. In this case, you should contact the person responsible for publishing the book.