1# -*- tcl -*-
2# sak::doc - Documentation facilities
3
4package require sak::util
5package require sak::doc::auto
6
7namespace eval ::sak::doc {}
8
9# ###
10# API commands
11
12## ### ### ### ######### ######### #########
13
14proc ::sak::doc::index {modules} {
15    # The argument (= set of modules) is irrelevant to this command.
16    global base
17
18    # First locate all manpages in the CVS workspace.
19    set manpages [auto::findManpages $base]
20    auto::saveManpages $manpages
21
22    # Then scan the found pages and extract the information needed for
23    # keyword index and table of contents.
24    array set meta [auto::scanManpages $manpages]
25
26    # Sort through the extracted data.
27    array set kwic  {}
28    array set title {}
29    array set cat   {}
30    array set name  {}
31    set       apps  {}
32    array set mods  {}
33
34    foreach page [array names meta] {
35	unset -nocomplain m
36	array set m $meta($page)
37
38	# Collect keywords and file mapping for index.
39	foreach kw $m(keywords) {
40	    lappend kwic($kw) $page
41	}
42	# Get page title, relevant for display order
43	if {$m(desc) eq ""} {
44	    set m(desc) $m(shortdesc)
45	}
46	set title($page) $m(desc)
47	# Get page name/title, relevant for display order.
48	set name($page) $m(title)
49	# Get page category, for sectioning and display order in the
50	# table of contents
51	if {$m(category) ne ""} {
52	    set c $m(category)
53	} else {
54	    set c Unfiled
55	}
56	lappend cat($c) $page
57
58	# Type of documented entity
59	set type [lindex [file split $page] 0]
60	if {$type eq "apps"} {
61	    lappend apps $page
62	} else {
63	    lappend mods([lindex [file split $page] 1]) $page
64	}
65    }
66
67    #parray meta
68    #parray kwic
69    #parray title
70    #parray name
71    #parray cat
72    #puts "apps = $apps"
73    #parray mods
74
75    auto::saveKeywordIndex    kwic  name
76    auto::saveTableOfContents title name cat apps mods
77    return
78}
79
80proc ::sak::doc::imake {modules} {
81    # The argument (= set of modules) is irrelevant to this command.
82    auto::saveManpages [auto::findManpages]
83    return
84}
85
86proc ::sak::doc::ishow {modules} {
87    if {[catch {
88	set manpages [auto::loadManpages]
89    } msg]} {
90	puts stderr "Unable to use manpage listing '[auto::manpages]'\n$msg"
91    } else {
92	puts [join $manpages \n]
93    }
94    return
95}
96
97## ### ### ### ######### ######### #########
98
99proc ::sak::doc::validate {modules} {Gen null  null $modules}
100proc ::sak::doc::html     {modules} {Gen html  html $modules}
101proc ::sak::doc::nroff    {modules} {Gen nroff n    $modules}
102proc ::sak::doc::tmml     {modules} {Gen tmml  tmml $modules}
103proc ::sak::doc::text     {modules} {Gen text  txt  $modules}
104proc ::sak::doc::wiki     {modules} {Gen wiki  wiki $modules}
105proc ::sak::doc::latex    {modules} {Gen latex tex  $modules}
106
107proc ::sak::doc::dvi {modules} {
108    latex $modules
109    file mkdir [file join doc dvi]
110    cd         [file join doc dvi]
111
112    foreach f [lsort -dict [glob -nocomplain ../latex/*.tex]] {
113
114	set target [file rootname [file tail $f]].dvi
115	if {[file exists $target]
116	    && [file mtime $target] > [file mtime $f]} {
117	    continue
118	}
119
120	puts "Gen (dvi): $f"
121	exec latex $f 1>@ stdout 2>@ stderr
122    }
123    cd ../..
124    return
125}
126
127proc ::sak::doc::ps {modules} {
128    dvi $modules
129    file mkdir [file join doc ps]
130    cd         [file join doc ps]
131    foreach f [lsort -dict [glob -nocomplain ../dvi/*.dvi]] {
132
133	set target [file rootname [file tail $f]].ps
134	if {[file exists $target]
135	    && [file mtime $target] > [file mtime $f]} {
136	    continue
137	}
138
139	puts "Gen (ps): $f"
140	exec dvips -o $target $f >@ stdout 2>@ stderr
141    }
142    cd ../..
143    return
144}
145
146proc ::sak::doc::pdf {modules} {
147    dvi $modules
148    file mkdir [file join doc pdf]
149    cd         [file join doc pdf]
150    foreach f [lsort -dict [glob -nocomplain ../ps/*.ps]] {
151
152	set target [file rootname [file tail $f]].pdf
153	if {[file exists $target]
154	    && [file mtime $target] > [file mtime $f]} {
155	    continue
156	}
157
158	puts "Gen (pdf): $f"
159	exec ps2pdf $f $target >@ stdout 2>@ stderr
160    }
161    cd ../..
162    return
163}
164
165proc ::sak::doc::list {modules} {
166    Gen list l $modules
167
168    set FILES [glob -nocomplain doc/list/*.l]
169    set LIST  [open [file join doc list manpages.tcl] w]
170
171    foreach file $FILES {
172        set f [open $file r]
173        puts $LIST [read $f]
174        close $f
175    }
176    close $LIST
177
178    eval file delete -force $FILES
179    return
180}
181
182# ### ### ### ######### ######### #########
183## Implementation
184
185proc ::sak::doc::Gen {fmt ext modules} {
186    global distribution
187    global tcl_platform
188
189    getpackage doctools doctools/doctools.tcl
190
191    set null   0 ; if {![string compare $fmt null]} {set null   1}
192    set hidden 0 ; if {![string compare $fmt desc]} {set hidden 1}
193
194    if {!$null} {
195	file mkdir [file join doc $fmt]
196	set prefix "Gen ($fmt)"
197    } else {
198	set prefix "Validate  "
199    }
200
201    foreach m $modules {
202	set mpath [sak::util::module2path $m]
203
204	::doctools::new dt \
205		-format $fmt \
206		-module $m
207
208	set fl [glob -nocomplain [file join $mpath *.man]]
209
210	if {[llength $fl] == 0} {
211	    dt destroy
212	    continue
213	}
214
215	foreach f $fl {
216	    if {!$null} {
217                set target [file join doc $fmt \
218                                [file rootname [file tail $f]].$ext]
219                if {[file exists $target]
220                    && [file mtime $target] > [file mtime $f]} {
221                    continue
222                }
223	    }
224	    if {!$hidden} {puts "$prefix: $f"}
225
226	    dt configure -file $f
227	    if {$null} {
228		dt configure -deprecated 1
229	    }
230
231	    set fail [catch {
232		set data [dt format [get_input $f]]
233	    } msg]
234
235	    set warnings [dt warnings]
236	    if {[llength $warnings] > 0} {
237		puts stderr [join $warnings \n]
238	    }
239
240	    if {$fail} {
241		puts stderr $msg
242		continue
243	    }
244
245	    if {!$null} {
246		write_out $target $data
247	    }
248	}
249	dt destroy
250    }
251}
252
253# ### ### ### ######### ######### #########
254
255package provide sak::doc 1.0
256
257##
258# ###
259