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