Changes to ChangeLog.
Changes to apps/dtplite.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
|
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
|
#! /bin/sh
# -*- tcl -*- \
exec tclsh "$0" ${1+"$@"}
# @@ Meta Begin
# Application dtplite 1.0.3
# Application dtplite 1.0.4
# Meta platform tcl
# Meta summary Lightweight DocTools Processor
# Meta description This application is a simple processor
# Meta description for documents written in the doctools
# Meta description markup language. It covers the most
# Meta description common use cases, but is not as
# Meta description configurable as its big brother dtp.
# Meta category Processing doctools documents
# Meta subject doctools doctoc docidx
# Meta require {doctools 1}
# Meta require {doctools::idx 1}
# Meta require {doctools::toc 1}
# Meta require fileutil
# Meta require textutil::repeat
# Meta author Andreas Kupries
# Meta license BSD
# @@ Meta End
package provide dtplite 1.0.3
package provide dtplite 1.0.4
# dtp lite - Lightweight DocTools Processor
# ======== = ==============================
#
# Use cases
# ---------
#
#
# (1) Validation of a single manpage, i.e. checking that it is valid
# doctools format.
#
#
# (1a) Getting a preliminary version of the formatted output, for
# display in a browser, nroff, etc., proofreading the
# formatting.
#
#
# (2) Generate documentation for a single package, i.e. all the
# manpages, plus index and table of contents.
#
#
# (3) Generation of unified documentation for several
# packages. Especially unified keyword index and table of
# contents. This may additionally generate per-package TOCs
# as well (Per-package indices don't make sense IMHO).
#
#
# Command syntax
# --------------
#
#
# Ad 1) dtplite -o output format file
#
#
# The option -o specifies where to write the output to. Using
# the string "-" as name of the output file causes the tool to
# write the generated data to stdout. If $output is a directory
# then a file named [[file rootname $file].$format] is written
# to the directory.
# Ad 1a) dtplite validate file
#
# The "validate" format does not generate output at all, only
# syntax checking is performed.
#
#
# Ad 2) dtplite -o output format directory
#
#
# I.e. we distinguish (2) from (1) by the type of the input,
# file, or directory. In this situation output has to be a
# directory. Use the path "." to place the results into the
# current directory.
#
#
# We locate _all_ files under directory, i.e. all subdirectories
# are scanned as well. We replicate the found directory
# structure in the output (See example below). The index and
# table of contents are written to the toplevel directory in the
# output. The names are hardwired to "toc.$format" and
# "index.$format".
#
#
# Ad 3) dtplite -merge -o output format directory
#
#
# This can be treated as special case of (2). The -merge option
# tells it that the output is nested one level deeper, to keep a
# global toc and index in the toplevel and to merge the package
# toc and index into them.
#
#
# This way the global documents are built up incrementally. This
# can help us in a future extended installer as well!, extending
# a global documentation tree of all installed packages.
#
#
# Additional features.
#
#
# * As described above the format name is used as the extension
# for the generated files. Does it make sense to introduce an
# option with which we can overide this, or should we simply
# extect that a calling script does a proper renaming of all the
# files ? ... The option is better. In HTML output we have
# links between the files, and renaming from the outside just
# breaks the links. This option is '-ext'. It is ignored if the
# output is a single file (fully specified via -o), or stdout.
#
#
# -ext extension
#
#
# * Most of the formats don't need much/none of customizability.
# I.e. text, nroff, wiki, tmml, ... For HTML however some
# degree of customizability is required for good output. What
# should we given to the user ?
#
#
# - Allow setting of a stylesheet.
# - Allow integration of custom body header and footer html.
# - Allow additional links for the navigation bar.
#
#
# Note: The tool generates standard navigation bars to link the
# all tocs, indices, and pages together.
#
#
# -style file
# -header file
# -footer file
# -nav label url
#
#
# * The application may mis-detect files as doctools input.
# And we cannot always mark them as non-doctools because
# they may be such. Test cases, for example. To exclude
# these we have the option '-exclude' taking a glob pattern.
# Multiple uses of the option accumulate.
#
# -exclude glob
#
# * For tcllib itself we have external tools generating a nicer
# TOC. Use option -toc to specify the doctoc file to use instead
# of generating our own.
#
# -toc path
#
# That should be enough to allow the creation of good looking formatted
# documentation without getting overly complex in both implementation
# and use.
package require doctools 1.4.11 ; # 'image' support, -ibase support
package require doctools::idx 1.0.4 ;
package require doctools::toc 1.1.3 ;
|
︙ | | |
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
|
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
|
-
+
+
+
+
+
|
# Database of image files for use by dt_imap.
variable imap
array set imap {}
# Database of exclusion patterns. Files matching these are not
# manpages. For example, test files for doctools itself may full
# manpages. For example, test files for doctools itself may fall
# under this.
variable excl {}
# Path of a user specified table of contents (doctoc format).
variable utoc {}
}
# ### ### ### ######### ######### #########
## External data and status
#
## Only the directory merge mode uses external data, saving the
## internal representations of current toc, index. and xref
|
︙ | | |
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
|
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
|
+
+
-
-
+
+
+
+
+
+
|
# dtplite -o outputpath \
# ?-merge? \
# ?-ext ext? \
# ?-style file? \
# ?-header file? \
# ?-footer file? \
# ?-nav label url?... \
# ?-exclude glob?... \
# ?-toc path? \
# format inputpath
##
proc ::dtplite::processCmdline {} {
global argv
variable output ; variable style ; variable stdout
variable format ; variable header ; variable single
variable input ; variable footer ; variable mode
variable ext ; variable nav ; variable merge
variable module ; variable excl
variable ext ; variable nav ; variable merge
variable module ; variable excl ; variable utoc
# Process the options, perform basic validation.
while {[llength $argv]} {
set opt [lindex $argv 0]
if {![string match "-*" $opt]} break
if {[string equal $opt "-o"]} {
if {[llength $argv] < 2} Usage
set output [lindex $argv 1]
set argv [lrange $argv 2 end]
} elseif {[string equal $opt "-merge"]} {
set merge 1
set argv [lrange $argv 1 end]
} elseif {[string equal $opt "-ext"]} {
if {[llength $argv] < 2} Usage
set ext [lindex $argv 1]
set argv [lrange $argv 2 end]
} elseif {[string equal $opt "-toc"]} {
if {[llength $argv] < 2} Usage
set utoc [lindex $argv 1]
set argv [lrange $argv 2 end]
} elseif {[string equal $opt "-exclude"]} {
if {[llength $argv] < 2} Usage
lappend excl [lindex $argv 1]
set argv [lrange $argv 2 end]
} elseif {[string equal $opt "-style"]} {
if {[llength $argv] < 2} Usage
|
︙ | | |
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
|
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
|
+
-
+
+
+
+
+
+
+
-
+
+
|
# and toc. I.e. any existing index and toc files are overwritten.
variable input
variable out
variable module
variable meta
variable format
variable utoc
# Phase 0. Find the documents to convert.
# Phase I. Collect meta data, and compute the map from input to
# ........ output files. This is also the map for the symbolic
# ........ references. We extend an existing map (required for use
# ........ in merge op.
# Phase II. Build index and toc information from the meta data.
# Phase III. Convert each file, using index, toc and meta
# .......... information.
MapImages
set files [LocateManpages $input]
if {![llength $files]} {
ArgError "Module \"$module\" has no files to process."
ArgError "Module \"$module\" has no files to process."
}
MetadataGet $files
StyleMakeLocal
if {$utoc ne {}} {
if {[file exists $utoc]} {
set utoc [Get $utoc]
}
TocWrite toc index $utoc
} else {
TocWrite toc index [TocGenerate [TocGet $module toc]]
TocWrite toc index [TocGenerate [TocGet $module toc]]
}
IdxWrite index toc [IdxGenerate $module [IdxGet]]
dt configure -module $module
XrefGet
XrefSetup dt
FooterSetup dt
MapSetup dt
|
︙ | | |
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
|
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
|
+
-
+
+
+
+
+
+
+
-
-
+
+
+
-
+
|
variable input
variable out
variable module
variable meta
variable output
variable format
variable utoc
# Phase 0. Find the documents to process.
# Phase I. Collect meta data, and compute the map from input to
# ........ output files. This is also the map for the symbolic
# ........ references. We extend an existing map (required for use
# ........ in merge op.
# Phase II. Build module local toc from the meta data, insert it
# ......... into the main toc as well, and generate a global
# ......... index.
# Phase III. Process each file, using cross references, and links
# .......... to boths tocs and the index.
MapImages
set files [LocateManpages $input]
if {![llength $files]} {
ArgError "Module \"$module\" has no files to process."
ArgError "Module \"$module\" has no files to process."
}
MetadataGet $files $module
StyleMakeLocal $module
set localtoc [TocGet $module $module/toc]
TocWrite $module/toc index [TocGenerate $localtoc] [TocMap $localtoc]
if {$utoc ne {}} {
if {[file exists $utoc]} {
set utoc [Get $utoc]
}
TocWrite toc index $utoc
} else {
TocWrite toc index [TocGenerate [TocMergeSaved $localtoc]]
IdxWrite index toc [IdxGenerate {} [IdxGetSaved index]]
TocWrite toc index [TocGenerate [TocMergeSaved $localtoc]]
}
IdxWrite index toc [IdxGenerate {} [IdxGetSaved index]]
dt configure -module $module
XrefGetSaved
XrefSetup dt
FooterSetup dt
MapSetup dt
foreach f [lsort -dict $files] {
puts stdout \t$f
set o $out($f)
dt configure -file [At $o]
dt configure -file [At $o] -ibase $input/$f
NavbuttonPush {Keyword Index} [Output index] $o
NavbuttonPush {Table Of Contents} [Output $module/toc] $o
NavbuttonPush {Main Table Of Contents} [Output toc] $o
HeaderSetup dt
NavbuttonPop
NavbuttonPop
|
︙ | | |
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
|
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
|
-
+
-
+
-
+
|
}
proc ::dtplite::TocGenerate {data} {
# Handling single and multiple divisions.
# single div => div is full toc
# multi div => place divs into the toc in alpha order.
#
# Sort toc (each division) by label.
# Sort toc (each division) by label (index 1).
# Write as doctoc.
array set toc $data
TagsBegin
if {[array size toc] < 2} {
# Empty, or single division. The division is the TOC, toplevel.
unset toc
set desc [lindex $data 0]
set data [lindex [lindex $data 1] 1]
TocAlign mxf mxl $data
Tag+ toc_begin [list {Table Of Contents} $desc]
foreach item [lsort -dict -index 2 $data] {
foreach item [lsort -dict -index 1 $data] {
foreach {symfile label desc} $item break
Tag+ item \
[FmtR mxf $symfile] \
[FmtR mxl $label] \
[list $desc]
}
} else {
Tag+ toc_begin [list {Table Of Contents} Modules]
foreach desc [lsort -dict [array names toc]] {
foreach {ref div} $toc($desc) break
TocAlign mxf mxl $div
Tag+ division_start [list $desc [Output $ref]]
foreach item [lsort -dict -index 2 $div] {
foreach item [lsort -dict -index 1 $div] {
foreach {symfile label desc} $item break
Tag+ item \
[FmtR mxf $symfile] \
[FmtR mxl $label] \
[list $desc]
}
Tag+ division_end
|
︙ | | |
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
|
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
|
-
+
|
TagsBegin
Tag+ index_begin [list {Keyword Index} $desc]
foreach k [lsort -dict [array names keys]] {
IdxAlign mxf $keys($k)
Tag+ key [list $k]
foreach v [lsort -dict -index 0 $keys($k)] {
foreach v [lsort -dict -index 1 $keys($k)] {
foreach {file label} $v break
Tag+ manpage [FmtR mxf $file] [list $label]
}
}
Tag+ index_end
#puts ____________________\n[join $lines \n]\n_________________________
|
︙ | | |
Changes to apps/dtplite.man.
Added embedded/man/files/apps/dtplite.n.