summaryrefslogtreecommitdiffstats
path: root/tcllib/support/devel/sak/doc/doc_auto.tcl
diff options
context:
space:
mode:
Diffstat (limited to 'tcllib/support/devel/sak/doc/doc_auto.tcl')
-rw-r--r--tcllib/support/devel/sak/doc/doc_auto.tcl323
1 files changed, 323 insertions, 0 deletions
diff --git a/tcllib/support/devel/sak/doc/doc_auto.tcl b/tcllib/support/devel/sak/doc/doc_auto.tcl
new file mode 100644
index 0000000..2c1a20e
--- /dev/null
+++ b/tcllib/support/devel/sak/doc/doc_auto.tcl
@@ -0,0 +1,323 @@
+# -*- tcl -*-
+# sak::doc::auto - Documentation facilities, support for automatic
+# list of manpages, keyword index, and table of contents.
+
+package require sak::util
+
+namespace eval ::sak::doc::auto {
+ set here [file dirname [file normalize [info script]]]
+}
+
+getpackage fileutil fileutil/fileutil.tcl
+getpackage doctools doctools/doctools.tcl
+getpackage textutil::repeat textutil/repeat.tcl
+
+# ###
+# API commands
+
+proc ::sak::doc::auto::manpages {} {
+ variable here
+ return [file join $here manpages.txt]
+}
+
+proc ::sak::doc::auto::kwic {} {
+ variable here
+ return [file join $here kwic.txt]
+}
+
+proc ::sak::doc::auto::toc {{name toc.txt}} {
+ variable here
+ return [file join $here $name]
+}
+
+## ### ### ### ######### ######### #########
+
+proc ::sak::doc::auto::findManpages {base {excluded {}}} {
+ set top [file normalize $base]
+ set manpages {}
+ foreach page [glob -nocomplain -directory $top/modules */*.man] {
+ set rpage [fileutil::stripPath $top $page]
+ # rpage = modules/*/foo.man
+ set m [file tail [file dirname $rpage]]
+ if {[isExcluded $excluded $m]} continue
+ lappend manpages $rpage
+ }
+ foreach page [glob -nocomplain -directory $top/apps *.man] {
+ lappend manpages [fileutil::stripPath $top $page]
+ }
+ return [lsort -dict $manpages]
+}
+
+proc ::sak::doc::auto::isExcluded {excluded m} {
+ foreach e $excluded {
+ if {$e eq $m} { return yes }
+ }
+ return no
+}
+
+proc ::sak::doc::auto::saveManpages {manpages} {
+ fileutil::writeFile [manpages] [join [lsort -dict $manpages] \n]\n
+ return
+}
+
+proc ::sak::doc::auto::loadManpages {} {
+ return [lsort -dict [split [fileutil::cat [manpages]] \n]]
+}
+
+## ### ### ### ######### ######### #########
+
+proc ::sak::doc::auto::scanManpages {manpages} {
+ ::doctools::new dt -format list
+ set data {}
+ puts Scanning...
+ foreach page $manpages {
+ puts ...$page
+ if {![file size $page]} { puts "\tEMPTY, IGNORED" ; continue }
+ dt configure -ibase $page
+ lappend data $page [lindex [dt format [fileutil::cat $page]] 1]
+ }
+
+ dt destroy
+ return $data
+}
+
+## ### ### ### ######### ######### #########
+
+proc ::sak::doc::auto::saveKeywordIndex {kv nv} {
+ upvar 1 $kv kwic $nv name
+ # kwic: keyword -> list (files)
+ # name: file -> label
+
+ TagsBegin
+ Tag+ index_begin [list {Keyword Index} {}]
+
+ # Handle the keywords in dictionary order for nice display.
+ foreach kw [lsort -dict [array names kwic]] {
+ set tmp [Sortable $kwic($kw) name max _]
+
+ Tag+ key [list $kw]
+ foreach item [lsort -dict -index 0 $tmp] {
+ foreach {label file} $item break
+ Tag+ manpage [FmtR max $file] [list $label]
+ }
+ }
+
+ Tag+ index_end
+
+ fileutil::writeFile [kwic] [join $lines \n]
+ return
+}
+
+## ### ### ### ######### ######### #########
+
+proc ::sak::doc::auto::saveTableOfContents {tv nv cv av mv} {
+ upvar 1 $tv title $nv name $cv cat $av apps $mv mods
+ # title: file -> description
+ # name: file -> label
+ # cat: category -> list (file...)
+
+ TagsBegin
+ Tag+ toc_begin [list {Table Of Contents} {}]
+
+ # The man pages are sorted in several ways for the toc.
+ # 1. First section by category. Subsections are categories.
+ # Sorted by category name, in dictionary order.
+ # Inside the subsections the files, sorted by label and
+ # description.
+ # 2. Second section for types. Subsections are modules and apps.
+ # Apps first, then modules. For apps items directly, sorted
+ # by name and description. For modules one sub-subsection
+ # per module, elements the packages, sorted by label and
+ # description.
+
+ Tag+ division_start [list {By Categories}]
+ foreach c [lsort -dict [array names cat]] {
+ Tag+ division_start [list $c]
+ foreach item [lsort -dict -index 0 [Sortable $cat($c) name maxf maxl]] {
+ foreach {label file} $item break
+ Tag+ item \
+ [FmtR maxf $file] \
+ [FmtR maxl $label] \
+ [list $title($file)]
+ }
+ Tag+ division_end
+ }
+ Tag+ division_end
+
+ Tag+ division_start [list {By Type}]
+ # Not handled: 'no applications'
+ Tag+ division_start [list {Applications}]
+ foreach item [lsort -dict -index 0 [Sortable $apps name maxf maxl]] {
+ foreach {label file} $item break
+ Tag+ item \
+ [FmtR maxf $file] \
+ [FmtR maxl $label] \
+ [list $title($file)]
+ }
+ Tag+ division_end
+ # Not handled: 'no modules'
+ Tag+ division_start [list {Modules}]
+ foreach m [lsort -dict [array names mods]] {
+ Tag+ division_start [list $m]
+ foreach item [lsort -dict -index 0 [Sortable $mods($m) name maxf maxl]] {
+ foreach {label file} $item break
+ Tag+ item \
+ [FmtR maxf $file] \
+ [FmtR maxl $label] \
+ [list $title($file)]
+ }
+ Tag+ division_end
+ }
+ Tag+ division_end
+ Tag+ division_end
+ Tag+ toc_end
+
+ fileutil::writeFile [toc] [join $lines \n]
+ return
+}
+
+proc ::sak::doc::auto::saveSimpleTableOfContents1 {tv nv dv fname} {
+ upvar 1 $tv title $nv name $dv data
+ # title: file -> description
+ # name: file -> label
+ # data: list(file...)
+
+ TagsBegin
+ Tag+ toc_begin [list {Table Of Contents} {}]
+
+ # The man pages are sorted in several ways for the toc.
+ # Subsections are the modules or apps, whatever is in data.
+
+ # Not handled: 'no applications'
+ Tag+ division_start [list {Applications}]
+ foreach item [lsort -dict -index 0 [Sortable $data name maxf maxl]] {
+ foreach {label file} $item break
+ Tag+ item \
+ [FmtR maxf $file] \
+ [FmtR maxl $label] \
+ [list $title($file)]
+ }
+ Tag+ division_end
+ Tag+ toc_end
+
+ fileutil::writeFile [toc $fname] [join $lines \n]
+ return
+}
+
+proc ::sak::doc::auto::saveSimpleTableOfContents2 {tv nv dv fname} {
+ upvar 1 $tv title $nv name $dv data
+ # title: file -> description
+ # name: file -> label
+ # data: module -> list (file...)
+
+ TagsBegin
+ Tag+ toc_begin [list {Table Of Contents} {}]
+
+ # The man pages are sorted in several ways for the toc.
+ # Subsections are the modules or apps, whatever is in data.
+
+ # Not handled: 'no modules'
+ Tag+ division_start [list {Modules}]
+ foreach m [lsort -dict [array names data]] {
+ Tag+ division_start [list $m]
+ foreach item [lsort -dict -index 0 [Sortable $data($m) name maxf maxl]] {
+ foreach {label file} $item break
+ Tag+ item \
+ [FmtR maxf $file] \
+ [FmtR maxl $label] \
+ [list $title($file)]
+ }
+ Tag+ division_end
+ }
+ Tag+ division_end
+ Tag+ toc_end
+
+ fileutil::writeFile [toc $fname] [join $lines \n]
+ return
+}
+
+proc ::sak::doc::auto::saveSimpleTableOfContents3 {tv nv cv fname} {
+ upvar 1 $tv title $nv name $cv cat
+ # title: file -> description
+ # name: file -> label
+ # cat: category -> list (file...)
+
+ TagsBegin
+ Tag+ toc_begin [list {Table Of Contents} {}]
+
+ Tag+ division_start [list {By Categories}]
+ foreach c [lsort -dict [array names cat]] {
+ Tag+ division_start [list $c]
+ foreach item [lsort -dict -index 0 [Sortable $cat($c) name maxf maxl]] {
+ foreach {label file} $item break
+ Tag+ item \
+ [FmtR maxf $file] \
+ [FmtR maxl $label] \
+ [list $title($file)]
+ }
+ Tag+ division_end
+ }
+ Tag+ division_end
+ Tag+ toc_end
+
+ fileutil::writeFile [toc $fname] [join $lines \n]
+ return
+}
+
+proc ::sak::doc::auto::Sortable {files nv mfv mnv} {
+ upvar 1 $nv name $mfv maxf $mnv maxn
+ # Generate a list of files sortable by name, and also find the
+ # max length of all relevant names.
+ set maxf 0
+ set maxn 0
+ set tmp {}
+ foreach file $files {
+ lappend tmp [list $name($file) $file]
+ Max maxf $file
+ Max maxn $name($file)
+ }
+ return $tmp
+}
+
+## ### ### ### ######### ######### #########
+
+proc ::sak::doc::auto::Max {v str} {
+ upvar 1 $v max
+ set x [string length $str]
+ if {$x <= $max} return
+ set max $x
+ return
+}
+
+proc ::sak::doc::auto::FmtR {v str} {
+ upvar 1 $v max
+ return [list $str][textutil::repeat::blank \
+ [expr {$max - [string length [list $str]]}]]
+}
+
+## ### ### ### ######### ######### #########
+
+proc ::sak::doc::auto::Tag {n args} {
+ if {[llength $args]} {
+ return "\[$n [join $args]\]"
+ } else {
+ return "\[$n\]"
+ }
+ #return \[[linsert $args 0 $n]\]
+}
+
+proc ::sak::doc::auto::Tag+ {n args} {
+ upvar 1 lines lines
+ lappend lines [eval [linsert $args 0 ::sak::doc::auto::Tag $n]]
+ return
+}
+
+proc ::sak::doc::auto::TagsBegin {} {
+ upvar 1 lines lines
+ set lines {}
+ return
+}
+
+## ### ### ### ######### ######### #########
+
+package provide sak::doc::auto 1.0
generated by cgit v0.12 at 2024-07-18 11:41:08 (GMT)