1#
2# bldmanhelp.tcl --
3#
4#  Build help files from the manual pages.  This uses a table of manual
5# pages, sections. Brief entries are extracted from the name line.
6# This is not installed as part of Extended Tcl, its just used during the
7# build phase.
8#
9# This program is very specific to extracting manual files from John
10# Ousterhout's Tcl and Tk man pages.  Its not general.
11#
12# The command line is:
13#
14#   bldmanhelp maninfo helpdir
15#
16# Where:
17#    o maninfo is the path to a file that when sources returns a list of
18#      entries describing manual pages to convert.  Each entry is a list
19#      of manual file and the path of the help file to generate.
20#    o helpdir is the directory to create the help files in.
21#    o brief is the brief file to create.
22#------------------------------------------------------------------------------
23# Copyright 1992-1999 Karl Lehenbauer and Mark Diekhans.
24#
25# Permission to use, copy, modify, and distribute this software and its
26# documentation for any purpose and without fee is hereby granted, provided
27# that the above copyright notice appear in all copies.  Karl Lehenbauer and
28# Mark Diekhans make no representations about the suitability of this
29# software for any purpose.  It is provided "as is" without express or
30# implied warranty.
31#------------------------------------------------------------------------------
32# $Id: bldmanhelp.tcl,v 8.5 2002/11/12 21:35:31 karll Exp $
33#------------------------------------------------------------------------------
34#
35
36package require Tclx
37
38#
39# pull in buildhelp procs
40#
41source $env(TCLX_LIBRARY)/buildhelp.tcl
42
43#
44# Flag indicating if errors occured.
45#
46set gotErrors 0
47
48#-----------------------------------------------------------------------------
49# Process the name section.  This is used to generate a @brief: entry.
50# It returns the line that was read.
51
52proc ProcessNameSection {manFH outFH} {
53    set line [gets $manFH]
54    case [lindex $line 0] {
55        {.HS .BS .BE .VS .VE} {
56            set line [gets $manFH]
57        }
58    }
59    set brief [string trim [crange $line [string first - $line]+1 end]]
60    puts $outFH "'\\\"@brief: $brief"
61    return $line
62}
63
64#-----------------------------------------------------------------------------
65# Copy the named manual page source to the target, recursively including
66# .so files.  Remove macros usages that don't work good in a help file.
67
68proc CopyManPage {manPage outFH} {
69    global skipSection
70    global tcl_version
71
72    set section [lindex [split $manPage .] end]
73    if {$section == "macros"} {
74      return
75    }
76    set manPage [file rootname $manPage]
77    if {[catch {exec man -w $section $manPage} page] &&
78	[catch {exec man -w $section $manPage$tcl_version} page]} {
79        global gotErrors
80        set gotErrors 1
81	puts stderr "can't find man-page for \"$manPage\": $page"
82	return
83    }
84    set manPage [split $page ":)"]
85    if {[llength $manPage] > 1} { # Get the source, not from cat
86	set manPage [string trim [lindex $manPage 1]]
87    }
88
89    if {[string match *.gz $manPage]} {
90	set stat [catch {open "|gzip -d -c $manPage"} fh]
91    } elseif {[string match *.bz2 $manPage]} {
92	set stat [catch {open "|bzip2 -d -c $manPage"} fh]
93    } else {
94	set stat [catch {open $manPage} fh]
95    }
96    if {$stat != 0} {
97        global gotErrors
98        set gotErrors 1
99        puts stderr "can't open \"$manPage\" $fh. (cwd is [pwd])"
100        return
101    }
102    while {[gets $fh line] >= 0} {
103        switch -glob -- $line {
104	    {.so man.macros} {}
105            .so* {
106                CopyManPage [lindex $line 1] $outFH
107            }
108            .SH* {
109                puts $outFH $line
110                if {[lindex $line 1] == "NAME"} {
111                    set line [ProcessNameSection $fh $outFH]
112                    puts $outFH $line
113                }
114            }
115            .HS* - .BS* - .BE* - .VS* - .VE* - .TH* {
116            }
117            default {
118                if !$skipSection {
119                    puts $outFH $line
120                }
121            }
122        }
123    }
124    close $fh
125}
126
127#-----------------------------------------------------------------------------
128# Process a manual file and copy it to the temporary file.  Assumes current
129# dir is the directory containing the manual files.
130
131proc ProcessManFile {ent tmpFH} {
132    global skipSection
133    set skipSection 0
134    puts $tmpFH "'\\\"@help: [lindex $ent 1]"
135    CopyManPage [lindex $ent 0] $tmpFH
136    puts $tmpFH "'\\\"@endhelp"
137}
138
139#-----------------------------------------------------------------------------
140# Procedure to create a temporary file containing the file constructed
141# for input to buildhelp.
142#
143
144proc GenInputFile {manInfoTbl tmpFile} {
145
146   set tmpFH [open $tmpFile w]
147   set cwd [pwd]
148
149   foreach ent $manInfoTbl {
150       puts stdout "    preprocessing $ent"
151       ProcessManFile $ent $tmpFH
152   }
153   cd $cwd
154   close $tmpFH
155}
156
157#-----------------------------------------------------------------------------
158# Main program for building help from manual files.  Constructs tmp input
159# file for the buildhelp command.
160
161if {[llength $argv] != 4} {
162    puts stderr "wrong # args: bldmanhelp docdir maninfo helpdir brief"
163    exit 1
164}
165
166set tmpFile "bldmanhelp.tmp"
167
168set manInfoTbl [source [lindex $argv 1]]
169set helpDir [lindex $argv 2]
170set brief [lindex $argv 3]
171
172puts stdout "Begin preprocessing UCB manual files"
173GenInputFile $manInfoTbl $tmpFile
174
175buildhelp $helpDir $brief [list $tmpFile]
176
177file delete -force $tmpFile
178
179if $gotErrors {
180    puts stderr "Errors occured processing manual files"
181    exit 1
182}
183exit 0
184
185
186