;;; mantool.el --- generate provisional manual pages for Web2C programs ;; Copyright (C) 1997 Ulrik Vieth. ;; Author: Ulrik Vieth ;; Maintainer: UV ;; Version: 1.0 ;; Keywords: tex, maint ;;; This file is *not* part of GNU Emacs. ;; This program is free software; you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by ;; the Free Software Foundation; either version 2, or (at your option) ;; any later version. ;; This program is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs; see the file COPYING. If not, write to the ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, ;; Boston, MA 02111-1307, USA. ;;; Commentary: ;; This GNU Emacs Lisp program attempts to generate privisional manual ;; pages from the output of running `prog --help' and `prog --version' ;; which may be used to fill the void after the original manual pages ;; have been obsoleted by a more extensive manual written in Texinfo. ;; ;; It is assumed that for each program `prog' the output of running ;; `prog --version' and `prog --help' has been dumped into a file ;; `prog.data'. We attempt to parse that file and extract various ;; pieces of information that we want to put into the manual page. ;; ;; It also assumed that a template manual page `manual.tmpl' was ;; prepared which contains various `@magic@' strings indicating where ;; to insert the extracted information. Finally, we rely on a third ;; file `whatis.tmpl' which contains appropriate one-line descriptions ;; for the whatis database. ;; ;; History: ;; ;; v 1.0 -- 1997/03/28 UV created ;;; Code: (defconst mantool-manual-file "manual.tmpl" "Name of file containing template for generated man pages.") (defconst mantool-whatis-file "whatis.tmpl" "Name of file containing one-line program descriptions.") (defvar mantool-whatis-alist nil "Lookup table for program descriptions to go into whatis database. Initialized from `mantool-whatis-file' in `mantool-whatis-init'.") (defvar mantool-replace-alist nil "Translation table for magic strings in the man page template. Initialized dynamically in `mantool-generate-file'.") (defvar mantool-date (let ((time (current-time-string))) (concat (substring time 4 10) ", " (substring time 20 24))) "Date string to be inserted in the generated manual pages.") (defvar mantool-man-title-alist (list '("kpathsea" . "Kpathsea 3.0") '("web2c" . "Web2C 7.0") '("dvips" . "Dvips(k)") ) "Title string to be inserted in the generated manual pages.") (defvar mantool-texi-title-alist (list '("kpathsea" . "Kpathsea: A library for path searching") '("web2c" . "Web2C: A TeX implementation") '("dvips" . "Dvips: A DVI driver") ) "Titles of Texinfo manual containing the primary documentation.") (defconst mantool-kpse-files (list "MakeTeXMF" "MakeTeXPK" "MakeTeXTFM" "MakeTeXls-R" "kpsewhich") "List of manual pages to generate for Kpathsea programs.") (defconst mantool-web2c-files (list "bibtex" "dmp" "dvicopy" "dvitomp" "dvitype" "gftodvi" "gftopk" "gftype" "makempx" "mf" "mft" "mpost" "mpto" "newer" "patgen" "pktogf" "pktype" "pltotf" "pooltype" "tangle" "tex" "tftopl" "vftovp" "vptovf" "weave") "List of manual pages to generate for Web2C programs.") (defconst mantool-dvips-files (list "afm2tfm") "List of manual pages to generate for Dvips programs.") ;; utility functions (defun mantool-string-replace (string to-string) "Search for occurences of STRING and replace by TO-STRING." (save-excursion (goto-char (point-min)) (while (search-forward string nil t) (replace-match to-string t t)))) (defun mantool-regexp-replace (regexp to-regexp) "Search for occurences of REGEXP and replace by TO-REGEXP." (save-excursion (goto-char (point-min)) (while (re-search-forward regexp nil t) (replace-match to-regexp t nil)))) (defun mantool-assoc-replace (regexp assoc-table) "Search for ocurrences of REGEXP and replace using ASSOC-TABLE. If no match is found in ASSOC-TABLE, leave the text unchanged." (save-excursion (goto-char (point-min)) (while (re-search-forward regexp nil t) (let ((the-match (match-string 1))) (replace-match (or (cdr (assoc the-match assoc-table)) the-match) t t))))) ;;; conversion functions (defun mantool-generate-all () (interactive) (mantool-generate-kpse) (mantool-generate-web2c) (mantool-generate-dvips)) (defun mantool-generate-kpse () (interactive) (let ((file-list mantool-kpse-files)) (while file-list (mantool-generate-file (car file-list) "kpathsea") (setq file-list (cdr file-list))))) (defun mantool-generate-web2c () (interactive) (let ((file-list mantool-web2c-files)) (while file-list (mantool-generate-file (car file-list) "web2c") (setq file-list (cdr file-list))))) (defun mantool-generate-dvips () (interactive) (let ((file-list mantool-dvips-files)) (while file-list (mantool-generate-file (car file-list) "dvips") (setq file-list (cdr file-list))))) (defun mantool-whatis-init () "Initialize lookup table for one-line whatis program descriptions. Extracts required information from the file `mantool-whatis-file'." (setq mantool-whatis-alist nil) (save-excursion (set-buffer (get-buffer-create "*whatis*")) (erase-buffer) (insert-file-contents-literally mantool-whatis-file) (goto-char (point-min)) (while (re-search-forward "^* \\([A-Za-z0-9-]+\\)[ \t]*- \\(.*\\)\n" nil t) (let ((name (match-string 1)) (whatis (match-string 2))) (setq mantool-whatis-alist (append mantool-whatis-alist (list (cons name whatis)))))) (kill-buffer "*whatis*") )) (defun mantool-generate-file (file dist) "Generate manual page for FILE, which is part of the DIST distribution. FILE is the name of the man page to generate, producing \"FILE.man\" using information from \"FILE.data\" which contains --version and --help output. DIST is the name of the distribution which is used to determine the name of the Texinfo manual containg the authorative documentation." ;; if necesssary, initialize lookup table for whatis strings (if (null mantool-whatis-alist) (mantool-whatis-init)) ;; initialize file and buffer names (let* ((data-file (concat file ".data")) (man-file (concat file ".man")) (data-buffer (get-buffer-create data-file)) (man-buffer (get-buffer-create man-file)) ;; initialize strings to replace in the man page (name file) (whatis (or (cdr (assoc file mantool-whatis-alist)) (error "No \"whatis\" string for %s" name))) (version (cdr (assoc dist mantool-man-title-alist))) (texi-title (cdr (assoc dist mantool-texi-title-alist))) (texi-node dist) (texi-file (concat dist ".texi")) prog-name authors copyrights ) ;; load "file.data" containing --version and --help output (save-excursion (set-buffer data-buffer) (erase-buffer) (insert-file-contents-literally data-file) ;; extract name with fancy spelling (such as TeX or DVItoMP) ;; from first word in the first line of --version output (goto-char (point-min)) (re-search-forward "^\\([A-Za-z-]+\\)" nil t) ;; extract copyright owner and author information (if any) ;; from subsequent lines of the --version oupu (setq prog-name (match-string 1)) (if (re-search-forward "^\\(Copyright .*\\)\n" nil t) (setq copyrights (match-string 1)) (goto-char (point-min))) (if (re-search-forward "^\\(Primary author .*\\)\n" nil t) (setq authors (match-string 1)) (goto-char (point-min))) ) ;; initialize translation table for @magic@ strings in man page (setq mantool-replace-alist (list (cons "@name@" name) (cons "@NAME@" (upcase name)) (cons "@DATE@" (concat "\"" mantool-date "\"")) (cons "@VERSION@" (concat "\"" version "\"")) (cons "@whatis@" (or whatis "")) (cons "@texi_node@" texi-node) (cons "@texi_title@" texi-title) (cons "@texi_file@" texi-file) (cons "@prog_name@" prog-name) (cons "@authors@" (or authors "")) (cons "@copyrights@" (or copyrights "")) )) ;; create "file.man" from template file and replace @magic@ strings (save-excursion (set-buffer man-buffer) (erase-buffer) (insert-file-contents-literally mantool-manual-file) (goto-char (point-min)) (mantool-assoc-replace "\\(@[A-Za-z_]+@\\)" mantool-replace-alist) ) ;; extract usage message from --help output and copy to man page (save-excursion (set-buffer man-buffer) (goto-char (re-search-forward "^@usage@\n" nil t)) (replace-match "") ) (save-excursion (set-buffer data-buffer) ;; some programs apparently output an absolute path instead of ;; just the basename in the usage message (while (re-search-forward (concat "^\\(Usage\\| or\\): \\(/[A-Za-z/]+/\\)?" "\\([A-Za-z0-9-]+\\) \\(.*\\)\n") nil t) (let ((usage-name (match-string 3)) (usage-options (match-string 4))) (save-excursion (set-buffer man-buffer) (insert ".B " name "\n" usage-options "\n") (insert ".br\n")) ))) ;; extract description short following the usage message (save-excursion (set-buffer man-buffer) (goto-char (search-forward "@begin_description@" nil t)) (forward-line 1) ;; no replace-match yet, we need this later for narrowing ) (save-excursion (set-buffer data-buffer) ;; we assume that the description consists of one or more ;; paragraphs starting with two spaces indentation (while (re-search-forward "^ \\w" nil t) (let* ((beg (match-beginning 0)) (end (progn (re-search-forward "^\n" nil t) (forward-line -1) (point))) (copy-text (buffer-substring beg end))) (save-excursion (set-buffer man-buffer) (insert copy-text) (insert ".PP\n")) ))) ;; clean up the material just inserted into the man page (save-excursion (set-buffer man-buffer) (goto-char (point-min)) (save-restriction (let ((beg (progn (search-forward "@begin_decription@" nil t) (forward-line 1) (point))) (end (progn (search-forward "@end_description@" nil t) (match-beginning 0)))) (narrow-to-region beg end) ;; get rid of the two spaces indentation (goto-char (point-min)) (while (re-search-forward "^\\( \\)" nil t) (replace-match "")) ;; replace blank lines by paragraphs (goto-char (point-min)) (while (re-search-forward "^\n" nil t) (replace-match ".PP\n" t t)) )) (goto-char (search-forward "@begin_options@" nil t)) (forward-line 1) ;; no replace-match yet, we need this later for narrowing ) ;; extract list of options from --help output (save-excursion (set-buffer data-buffer) ;; we assume that the list of options consists of a single ;; paragraph of lines starting with "-" on the first column (while (re-search-forward "^-" nil t) (let* ((beg (match-beginning 0)) (end (progn (re-search-forward "^\n" nil t) (forward-line -1) (point))) (copy-text (buffer-substring beg end))) (save-excursion (set-buffer man-buffer) (insert copy-text) (insert ".PP\n")) ))) ;; clean up and reformat the material just copied (save-excursion (set-buffer man-buffer) (goto-char (point-min)) (save-restriction (let ((beg (progn (search-forward "@begin_options@" nil t) (forward-line 1) (point))) (end (progn (search-forward "@end_options@") (match-beginning 0)))) (narrow-to-region beg end) (goto-char (point-min)) ;; reformat options into hanging paragraphs in man pages ;; ;; we need to support quite a few syntax variations such as ;; "[-no]-option", "-O, -option", or "-option=FILE[.ext]" (while (re-search-forward (concat "^\\(\\(\\[-no\\]\\)?\\(-[A-Z], \\)?" "-\\([A-Za-z]\\|[a-z-]+\\)" "\\([ =][A-Z-]+\\(\\[.[a-z]+\\]\\)?\\)?\\)" "[ \t]+\\(.*\\)\n") nil t) (replace-match (concat ".TP\n" ".B " (match-string 1) "\n" (match-string 7) "\n") t t)) ;; get rid of indent for continuation lines (goto-char (point-min)) (while (re-search-forward "^[ \t]+\\(.*\\)\n" nil t) (replace-match (concat (match-string 1) "\n") t t)) ))) ;; final cleanup (save-excursion (set-buffer man-buffer) (goto-char (point-min)) ;; remove any remaining marker strings (flush-lines "\\(@begin\\|@end\\)_\\(.*\\)@") ;; quote backslahes as double backslashes (mantool-string-replace "\\FIRST" "\\\\FIRST") (mantool-string-replace "\\char" "\\\\char") (mantool-string-replace "\\job" "\\\\job") (mantool-string-replace "\\write" "\\\\write") (mantool-string-replace "\\$" "\\\\$") ;; quote various troff contructs (mantool-string-replace "..." "\\|.\\|.\\|.") (mantool-string-replace "--" "\\-\\-") (mantool-string-replace ".B -" ".B \\-") ;; finally, save the generated man page (setq make-backup-files nil) (write-file man-file)) )) ;;; mantool.el ends here