Check-in [72fac6ef80]

Not logged in

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Work on adding markdown into the standard set of doc formats.
Timelines: family | ancestors | doc-plus-markdown
Files: files | file ages | folders
SHA3-256:72fac6ef80eb66177bce4ae6f8f03e35b0955791e1cc8aaf32c1641e20190a39
User & Date: andreask 2019-07-22 22:14:00
Context
2019-07-22
22:14
Work on adding markdown into the standard set of doc formats. Leaf check-in: 72fac6ef80 user: andreask tags: doc-plus-markdown
2018-09-12
23:27
Fixed test utilities - Process --notfile, --file in Kettle instead of passing into the test file. Our testmain does not use the relevant command from Tcltest where this information would be used. Leaf check-in: 9a1f50ef97 user: aku tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to doc.tcl.

65
66
67
68
69
70
71

72
73

74
75
76
77
78
79
80
81
...
105
106
107
108
109
110
111









112
113
114
115
116
117
118
...
122
123
124
125
126
127
128








129
130
131
132
133
134
135
...
137
138
139
140
141
142
143








144
145
146
147

148
149
150
151

152
153
154
155
156
157
158
...
165
166
167
168
169
170
171

172
173
174
175
176
177
178
...
183
184
185
186
187
188
189















190
191
192
193

194
195
196
197
198
199
200
	root manpages

    # Put the documentation into recipes.

    set dd      [path sourcedir [option get --with-doc-destination]]
    set mansrc  $dd/man/files
    set htmlsrc $dd/www


    set mandst  [path mandir  mann]

    set htmldst [path htmldir [file tail [path sourcedir]]]

    set isfossil [expr {[path find.fossil [path sourcedir]] ne {}}]

    recipe define doc {
	(Re)generate the documentation embedded in the repository.
    } {root dst isfossil} {
	if {[option get @dtplite] eq "external"} {
................................................................................
	Install HTML documentation
    } {src dst} {
	path install-file-group \
	    "HTML documentation" \
	    $dst {*}[glob -directory $src *]
	return
    } $htmlsrc $htmldst










    recipe define uninstall-doc-manpages {
	Uninstall manpages
    } {src dst} {
	path uninstall-file-set \
	    "manpages" \
	    $dst {*}[glob -directory $src -tails *.n]
................................................................................
    recipe define uninstall-doc-html {
	Uninstall HTML documentation
    } {dst} {
	path uninstall-file-group \
	    "HTML documentation" \
	    $dst
    } $htmldst









    recipe define reinstall-doc-manpages {
	Reinstall manpages
    } {} {
	invoke self uninstall-doc-manpages
	invoke self install-doc-manpages
    }
................................................................................
    recipe define reinstall-doc-html {
	Reinstall HTML documentation
    } {} {
	invoke self uninstall-doc-html
	invoke self install-doc-html
    }









    recipe parent install-doc-html     install-doc
    recipe parent install-doc-manpages install-doc
    recipe parent install-doc          install


    recipe parent uninstall-doc-html     uninstall-doc
    recipe parent uninstall-doc-manpages uninstall-doc
    recipe parent uninstall-doc          uninstall


    recipe parent reinstall-doc-html     reinstall-doc
    recipe parent reinstall-doc-manpages reinstall-doc
    recipe parent reinstall-doc          reinstall

    recipe parent validate-doc validate
    return
}
................................................................................
    path in $root {

	io puts "Removing old documentation..."
	file delete -force $dst

	file mkdir $dst/man
	file mkdir $dst/www


	io puts "Generating man pages..."
	DtpliteRun -ext n -o $dst/man nroff .

	# Note: Might be better to run them separately.
	# Note @: Or we shuffle the results a bit more in the post processing stage.

................................................................................
	}

	io puts "\nGenerating HTML... Pass 1, draft..."
	DtpliteRun {*}$cmd

	io puts "\nGenerating HTML... Pass 2, resolving cross-references..."
	DtpliteRun {*}$cmd
















	# Remove some of the generated files, consider them transient.
	cd  $dst/man ; file delete -force .idxdoc .tocdoc
	cd  ../www   ; file delete -force .idxdoc .tocdoc

    }
}

proc ::kettle::DtpliteRun {args} {
    io trace { dtplite [path::T $args]}
    if {[option get --dry]} return








>

|
>
|







 







>
>
>
>
>
>
>
>
>







 







>
>
>
>
>
>
>
>







 







>
>
>
>
>
>
>
>




>




>







 







>







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>




>







65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
...
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
...
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
...
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
...
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
...
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
	root manpages

    # Put the documentation into recipes.

    set dd      [path sourcedir [option get --with-doc-destination]]
    set mansrc  $dd/man/files
    set htmlsrc $dd/www
    set mdsrc   $dd/md

    set mandst  [path mandir      mann]
    set htmldst [path htmldir     [file tail [path sourcedir]]]
    set mddst   [path markdowndir [file tail [path sourcedir]]]

    set isfossil [expr {[path find.fossil [path sourcedir]] ne {}}]

    recipe define doc {
	(Re)generate the documentation embedded in the repository.
    } {root dst isfossil} {
	if {[option get @dtplite] eq "external"} {
................................................................................
	Install HTML documentation
    } {src dst} {
	path install-file-group \
	    "HTML documentation" \
	    $dst {*}[glob -directory $src *]
	return
    } $htmlsrc $htmldst

    recipe define install-doc-markdown {
	Install Markdown documentation
    } {src dst} {
	path install-file-group \
	    "Markdown documentation" \
	    $dst {*}[glob -directory $src *]
	return
    } $mdsrc $mddst

    recipe define uninstall-doc-manpages {
	Uninstall manpages
    } {src dst} {
	path uninstall-file-set \
	    "manpages" \
	    $dst {*}[glob -directory $src -tails *.n]
................................................................................
    recipe define uninstall-doc-html {
	Uninstall HTML documentation
    } {dst} {
	path uninstall-file-group \
	    "HTML documentation" \
	    $dst
    } $htmldst

    recipe define uninstall-doc-markdown {
	Uninstall Markdown documentation
    } {dst} {
	path uninstall-file-group \
	    "Markdown documentation" \
	    $dst
    } $mddst

    recipe define reinstall-doc-manpages {
	Reinstall manpages
    } {} {
	invoke self uninstall-doc-manpages
	invoke self install-doc-manpages
    }
................................................................................
    recipe define reinstall-doc-html {
	Reinstall HTML documentation
    } {} {
	invoke self uninstall-doc-html
	invoke self install-doc-html
    }

    recipe define reinstall-doc-markdown {
	Reinstall Markdown documentation
    } {} {
	invoke self uninstall-doc-markdown
	invoke self install-doc-markdown
    }

    recipe parent install-doc-markdown install-doc
    recipe parent install-doc-html     install-doc
    recipe parent install-doc-manpages install-doc
    recipe parent install-doc          install

    recipe parent uninstall-doc-markdown uninstall-doc
    recipe parent uninstall-doc-html     uninstall-doc
    recipe parent uninstall-doc-manpages uninstall-doc
    recipe parent uninstall-doc          uninstall

    recipe parent reinstall-doc-markdown reinstall-doc
    recipe parent reinstall-doc-html     reinstall-doc
    recipe parent reinstall-doc-manpages reinstall-doc
    recipe parent reinstall-doc          reinstall

    recipe parent validate-doc validate
    return
}
................................................................................
    path in $root {

	io puts "Removing old documentation..."
	file delete -force $dst

	file mkdir $dst/man
	file mkdir $dst/www
	file mkdir $dst/md

	io puts "Generating man pages..."
	DtpliteRun -ext n -o $dst/man nroff .

	# Note: Might be better to run them separately.
	# Note @: Or we shuffle the results a bit more in the post processing stage.

................................................................................
	}

	io puts "\nGenerating HTML... Pass 1, draft..."
	DtpliteRun {*}$cmd

	io puts "\nGenerating HTML... Pass 2, resolving cross-references..."
	DtpliteRun {*}$cmd

	# Note: Might be better to run them separately.
	# Note @: Or we shuffle the results a bit more in the post processing stage.

	if {$isfossil} {
	    set cmd [list -nav Home ../../../../home -merge -o $dst/md markdown .]
	} else {
	    set cmd [list -merge -o $dst/md markdown .]
	}

	io puts "\nGenerating Markdown... Pass 1, draft..."
	DtpliteRun {*}$cmd

	io puts "\nGenerating Markdown... Pass 2, resolving cross-references..."
	DtpliteRun {*}$cmd

	# Remove some of the generated files, consider them transient.
	cd  $dst/man ; file delete -force .idxdoc .tocdoc
	cd  ../www   ; file delete -force .idxdoc .tocdoc
	cd  ../md    ; file delete -force .idxdoc .tocdoc
    }
}

proc ::kettle::DtpliteRun {args} {
    io trace { dtplite [path::T $args]}
    if {[option get --dry]} return

Changes to options.tcl.

347
348
349
350
351
352
353
354
355
356
357

358
359
360
361
362
363
364
365
...
368
369
370
371
372
373
374







375
376
377
378
379
380
381
	Path to the root directory for the installation of any files.
	Default is the twice parent directory of [info library] of the
	tclsh running kettle.
    } {} directory
    onchange --prefix {} {
	# Implied arguments: option old new
	::set new [path norm $new]
	set!        --prefix      $new
	set-default --exec-prefix $new
	set-default --man-dir     $new/man
	set-default --html-dir    $new/html

	set-default --include-dir $new/include
    }

    # - -- --- ----- -------- -------------
    define --man-dir {
	Path to the root directory to install manpages into.
	Default is $(--prefix)/man.
    } {} directory
................................................................................
    # - -- --- ----- -------- -------------
    define --html-dir {
	Path to the root directory to install HTML documentation into.
	Default is $(--prefix)/html.
    } {} directory
    onchange --html-dir    {} { set! --html-dir [path norm $new] }








    # - -- --- ----- -------- -------------
    define --include-dir {
	Path to the root directory to install C header files into.
	Default is $(--prefix)/include.
    } {} directory
    onchange --include-dir {} { set! --include-dir [path norm $new] }








|
|
|
|
>
|







 







>
>
>
>
>
>
>







347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
...
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
	Path to the root directory for the installation of any files.
	Default is the twice parent directory of [info library] of the
	tclsh running kettle.
    } {} directory
    onchange --prefix {} {
	# Implied arguments: option old new
	::set new [path norm $new]
	set!        --prefix       $new
	set-default --exec-prefix  $new
	set-default --man-dir      $new/man
	set-default --html-dir     $new/html
	set-default --markdown-dir $new/md
	set-default --include-dir  $new/include
    }

    # - -- --- ----- -------- -------------
    define --man-dir {
	Path to the root directory to install manpages into.
	Default is $(--prefix)/man.
    } {} directory
................................................................................
    # - -- --- ----- -------- -------------
    define --html-dir {
	Path to the root directory to install HTML documentation into.
	Default is $(--prefix)/html.
    } {} directory
    onchange --html-dir    {} { set! --html-dir [path norm $new] }

    # - -- --- ----- -------- -------------
    define --markdown-dir {
	Path to the root directory to install markdown documentation into.
	Default is $(--prefix)/md.
    } {} directory
    onchange --markdown-dir {} { set! --markdown-dir [path norm $new] }

    # - -- --- ----- -------- -------------
    define --include-dir {
	Path to the root directory to install C header files into.
	Default is $(--prefix)/include.
    } {} directory
    onchange --include-dir {} { set! --include-dir [path norm $new] }

Changes to path.tcl.

118
119
120
121
122
123
124




125
126
127
128
129
130
131
proc ::kettle::path::mandir {{path {}}} {
    return [norm [file join [kettle option get --man-dir] $path]]
}

proc ::kettle::path::htmldir {{path {}}} {
    return [norm [file join [kettle option get --html-dir] $path]]
}





proc ::kettle::path::set-executable {path} {
    io trace {	!chmod ugo+x   $path}
    dry-barrier
    catch {
	file attributes $path -permissions ugo+x
    }







>
>
>
>







118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
proc ::kettle::path::mandir {{path {}}} {
    return [norm [file join [kettle option get --man-dir] $path]]
}

proc ::kettle::path::htmldir {{path {}}} {
    return [norm [file join [kettle option get --html-dir] $path]]
}

proc ::kettle::path::markdowndir {{path {}}} {
    return [norm [file join [kettle option get --markdown-dir] $path]]
}

proc ::kettle::path::set-executable {path} {
    io trace {	!chmod ugo+x   $path}
    dry-barrier
    catch {
	file attributes $path -permissions ugo+x
    }