Tcl Library Source Code

    Enter description
    if {[IsNot header]} {Error hdrcmd}
    Go body
    fmt_description [Sectdef section Description description]
}

# Storage for (sub)section ids to enable checking for ambigous
# identification. The ids on this level are logical names. The backends
# are given physical names (via counters).
global sect   ; # Map of logical -> physical ids
global sectt  ; # Map of logical -> section title
global sectci ; # Current section (id)
global sectct ; # Current section (title)
global countersection
global countersubsection

# ==============+=======================+======================
# toc_begin	| toc_begin		| -> contents
# --------------+-----------------------+----------------------
# contents	| item			| -> contents
# division	|			| -> division
# --------------+-----------------------+----------------------
# contents	| division_start	| -> end, PUSH division
# division	|			| -> division, PUSH division
# end		|			| PUSH division
# --------------+-----------------------+----------------------
# division	| division_end		| POP (-> division / -> end)
# --------------+-----------------------+----------------------
# contents	| toc_end		| -> done
# end		|			| -> done
# --------------+-----------------------+----------------------

[def xref]

The value for this parameter has to be a list of triples specifying
cross-reference information. This information is used by the engine to
create more hyperlinks. Each triple is a list containing a pattern,
symbolic filename and fragment reference, in this order. If a pattern
is specified multiple times the last occurrence of the pattern will be
used.

[para]

The engine will consult the xref database when encountering specific
commands and will create a link if the relevant text matches one of
the patterns. No link will be created if no match was found. The link

global pEnv ; array set pEnv {} ; # Defined paragraph environments (bulleting, indentation, other).
global para ; set para ""       ; # Text buffer for paragraphs.

global nextId     ; set       nextId     0      ; # Counter for environment generation.
global currentId  ; set       currentId  {}     ; # Id of current environment in 'pEnv'
global currentEnv ; array set currentEnv {}     ; # Current environment, expanded form.
global contexts   ; set       contexts   [list] ; # Stack of saved environments.
global off        ; set off   1                 ; # Suppression of plain text in some places.

################################################################
# Management of the current context.

proc Text  {text}    {global para ; append para $text ; return}
proc Store {op args} {global cmds ; lappend cmds [list $op $args] ; return}
proc Off   {}        {global off ; set off 1 ; return}

mcset c tkoption_list    "Command restricted to usage in tkoption lists"
mcset c depr_strong      "Deprecated command \"%s\".\n\tPlease consider appropriate semantic markup or \[emph\] instead."
mcset c depr_lstitem     "Deprecated command \"%s\".\n\tPlease use \[def\] instead."
mcset c depr_nl          "Deprecated command \"%s\".\n\tPlease use \[para\] instead."
mcset c depr_bullet      "Deprecated command \"%s\".\n\tPlease use \[item\] instead."
mcset c depr_ltype       "Deprecated list type \"%s\".\n\tPlease use \"%s\" instead."
mcset c sectambig        "(Sub)Section title \"%s\" causes ambiguous section references."
mcset c missingsect      "Referred (Sub)Section \"%s\" is not known."

# TOC messages

mcset c end/open/toc  "\[toc_end\] missing."
mcset c toc/plaintext "Plain text beyond whitespace is not allowed."
mcset c toc/begincmd  "Command not allowed here."
mcset c toc/endcmd    "Command not allowed here."

mcset en tkoption_list    "Command restricted to usage in tkoption lists"
mcset en depr_strong      "Deprecated command \"%s\".\n\tPlease consider appropriate semantic markup or \[emph\] instead."
mcset en depr_lstitem     "Deprecated command \"%s\".\n\tPlease use \[def\] instead."
mcset en depr_nl          "Deprecated command \"%s\".\n\tPlease use \[para\] instead."
mcset en depr_bullet      "Deprecated command \"%s\".\n\tPlease use \[item\] instead."
mcset en depr_ltype       "Deprecated list type \"%s\".\n\tPlease use \"%s\" instead."
mcset en sectambig        "(Sub)Section title \"%s\" causes ambiguous section references."
mcset en missingsect      "Referred (Sub)Section \"%s\" is not known."

mcset en end/open/toc  "\[toc_end\] missing."
mcset en toc/plaintext "Plain text beyond whitespace is not allowed."
mcset en toc/begincmd  "Command not allowed here."
mcset en toc/endcmd    "Command not allowed here."
mcset en toc/titlecmd  "Command not allowed here."
mcset en toc/sectcmd   "Command not allowed here."

    if {$lastlevel > 1 } { append result [tag/ ul] \n }
    if {$close}          { append result [tag/ li] \n }

    append result [tag/ ul] \n

    # Implicit sections coming after the TOC (Synopsis, then the
    # description which starts the actual document). The other
    # implicit sections are added at the end of the document and
    # are generated by 'fmt_manpage_end' in the second pass.

    if {$syn != {} || $req != {}} {
	append result [fmt_section Synopsis synopsis] [para_close] [taga div {class doctools_synopsis}] \n
	if {$req != {}} {
	    append result [tag_ ul \n$req\n class doctools_requirements] \n
	}

proc fmt_file    {text} {return "\"[Italic $text]\""}
proc fmt_namespace     {text} {Bold $text]}
proc fmt_uri     {text {label {}}} {
    if {$label == {}} {
	# Without label we use the link directly as part of the text.
	return [Underline $text]
    } else {
	# Label is used in the text, referred link is delegated into a
	# footnote.
	return "[Underline $label] \1\\footnote\{[texEscape $text]\}"
    }
}
proc fmt_image {text {label {}}} {
    global _has_images
    # text = symbolic name of the image.

# export.tcl --
#
#	Exporting indices into other formats.
#
# Copyright (c) 2009-2018 Andreas Kupries <[email protected]>
#
# See the file "license.terms" for information on usage and redistribution
# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
# 
# RCS: @(#) $Id: export.tcl,v 1.1 2009/04/01 04:28:37 andreas_kupries Exp $

# Each object manages a set of plugins for the conversion of keyword

	if {!$iscanonical} {
	    set serial [doctools::idx::structure canonicalize $serial]
	}

	set     configuration [$myconfig get]
	lappend configuration user   $::tcl_platform(user)
	lappend configuration format [$plugin plugin]

	return [$plugin do export $serial $configuration]
    }

    # ### ### ### ######### ######### #########
    ## Internal methods

    ##
    # ### ### ### ######### ######### #########
}

# ### ### ### ######### ######### #########
## Ready

package provide doctools::idx::export 0.2
return

[vset VERSION 0.2]
[comment {-*- tcl -*- doctools manpage}]
[manpage_begin doctools::idx::export n [vset VERSION]]
[keywords conversion]
[keywords docidx]
[keywords documentation]
[keywords export]
[keywords formatting]
[keywords generation]
[keywords HTML]
[keywords index]
[keywords json]
[keywords {keyword index}]
[keywords manpage]
[keywords markup]
[keywords nroff]
[keywords plugin]
[keywords reference]
[keywords {tcler's wiki}]
[keywords text]
[keywords url]
[keywords wiki]
[copyright {2009-2018 Andreas Kupries <[email protected]>}]
[moddesc   {Documentation tools}]
[titledesc {Exporting keyword indices}]
[category  {Documentation tools}]
[require doctools::idx::export [opt [vset VERSION]]]
[require Tcl 8.4]
[require doctools::config]
[require doctools::idx::structure]
[require snit]
[require pluginmgr]
[description]

If no value is specified it simply returns the current value, without
changing it.

[para]

Note that while the user can set the predefined configuration
variables [const user] and [const format] doing so will have no
effect, these values will be internally overridden when invoking an
import plugin.

[call [arg objectName] [method {config unset}] [arg pattern]...]

This method unsets all configuration variables matching the specified
glob [arg pattern]s. If no pattern is specified it will unset all
currently defined configuration variables.

[vset VERSION 0.2]
[comment {-*- tcl -*- doctools manpage}]
[manpage_begin doctools::idx::import n [vset VERSION]]
[keywords conversion]
[keywords docidx]
[keywords documentation]
[keywords import]
[keywords index]
[keywords json]
[keywords {keyword index}]
[keywords manpage]
[keywords markup]
[keywords parsing]
[keywords plugin]
[keywords reference]
[keywords url]
[copyright {2009-2018 Andreas Kupries <[email protected]>}]
[moddesc   {Documentation tools}]
[titledesc {Importing keyword indices}]
[category  {Documentation tools}]
[require doctools::idx::import [opt [vset VERSION]]]
[require Tcl 8.4]
[require doctools::config]
[require doctools::idx::structure]
[require snit]
[require pluginmgr]
[description]

If no value is specified it simply returns the current value, without
changing it.

[para]

Note that while the user can set the predefined configuration
variables [const user] and [const format] doing so will have no
effect, these values will be internally overridden when invoking an
import plugin.

[call [arg objectName] [method {config unset}] [arg pattern]...]

This method unsets all configuration variables matching the specified
glob [arg pattern]s. If no pattern is specified it will unset all
currently defined configuration variables.

[enum]
Each error element will be a list containing six strings describing an
error in detail. The strings will be

[list_begin enumerated]
[enum]
The path of the file the error occurred in. This may be empty.

[enum]
The range of the token the error was found at. This range is a
two-element list containing the offset of the first and last character
in the range, counted from the beginning of the input (file). Offsets
are counted from zero.

# import.tcl --
#
#	Importing indices into other formats.
#
# Copyright (c) 2009-2018 Andreas Kupries <[email protected]>
#
# See the file "license.terms" for information on usage and redistribution
# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
# 
# RCS: @(#) $Id: import.tcl,v 1.2 2011/11/17 08:00:45 andreas_kupries Exp $

# Each object manages a set of plugins for the conversion of keyword

    # ### ### ### ######### ######### #########

    method {import text} {text {format {}}} {
	set plugin [$self GetPlugin $format]

	set     configuration [$myconfig get]
	lappend configuration user   $::tcl_platform(user)
	lappend configuration format [$plugin plugin]

	return [$plugin do import $text $configuration]
    }

    method {import file} {path {format {}}} {
	# The plugin is not trusted to handle the file to convert.
	return [$self import text [fileutil::cat $path] $format]

    ##
    # ### ### ### ######### ######### #########
}

# ### ### ### ######### ######### #########
## Ready

package provide doctools::idx::import 0.2
return

proc import {text configuration} {
    # Note: We cannot fail here on duplicate keys in the input,
    # especially for keywords and references, as we do for Tcl-based
    # canonical index serializations, because our underlying JSON
    # parser automatically merges them, by taking only the last found
    # definition. I.e. of two or more definitions for a key X the last
    # overwrites all previous occurrences.
    return [doctools::idx::structure canonicalize [json::json2dict $text]]
}

# ### ### ### ######### ######### #########
## Ready

package provide doctools::idx::import::json 0.1

[enum]
The [term type] of a reference can be one of two values,

[list_begin definitions][comment {-- types --}]
[def [const manpage]]
The identifier of the reference is interpreted as symbolic file name,
referring to one of the documents the index was made for.

[def [const url]]
The identifier of the reference is interpreted as an url, referring to
some external location, like a website, etc.

[list_end][comment {-- types --}]
[list_end][comment {-- regular points --}]

[def {canonical serialization}]

#                          attributes for reference and label.
#
# The order of the keywords under root, and of the references under
# their keyword reflects the order of the information in the parsed
# document.

# Attributes in the nodes, except root provide location information,
# i.e. referring from there in the input the information is coming from
# (human-readable output: line/col for end of token, offset start/end
# for range covered by token.

# # ## ### ##### ######## ############# #####################
## Requirements

package require Tcl 8.4                  ; # Required runtime.

if {![package vsatisfies [package provide Tcl] 8.4]} {return}

# Packages for the doctools idx v2 implementation
# (still v1.1 docidx language).

# - Index container, mutable index objects
# - Export and import management
# - Export and import plugins
# - Parser for docidx markup, and handling serializations
# - Message catalogs for the parser

package ifneeded doctools::idx                 2   [list source [file join $dir container.tcl]]

package ifneeded doctools::idx::export         0.2 [list source [file join $dir export.tcl]]
package ifneeded doctools::idx::import         0.2 [list source [file join $dir import.tcl]]

package ifneeded doctools::idx::export::docidx 0.1 [list source [file join $dir export_docidx.tcl]]
package ifneeded doctools::idx::export::html   0.2 [list source [file join $dir export_html.tcl]]
package ifneeded doctools::idx::export::json   0.1 [list source [file join $dir export_json.tcl]]
package ifneeded doctools::idx::export::nroff  0.3 [list source [file join $dir export_nroff.tcl]]
package ifneeded doctools::idx::export::text   0.2 [list source [file join $dir export_text.tcl]]
package ifneeded doctools::idx::export::wiki   0.2 [list source [file join $dir export_wiki.tcl]]

	*
	* Released and tagged Tcllib 1.12 ========================
	* 

2009-11-14  Andreas Kupries  <[email protected]>

	* container.test: Fixed up typos in comments referring to keyword
	* export.tcl: indices, while the packages are all about tables of
	* export_doctoc.tcl: contents. Unchanged functionality, version
	* export_doctoc.test: left unchanged.
	* export_html.tcl:
	* export_html.test:
	* export_json.tcl:
	* export_json.test:

# export.tcl --
#
#	Exporting indices into other formats.
#
# Copyright (c) 2009-2018 Andreas Kupries <[email protected]>
#
# See the file "license.terms" for information on usage and redistribution
# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
# 
# RCS: @(#) $Id: export.tcl,v 1.2 2009/11/15 05:50:03 andreas_kupries Exp $

# Each object manages a set of plugins for the conversion of keyword

	if {!$iscanonical} {
	    set serial [doctools::toc::structure canonicalize $serial]
	}

	set     configuration [$myconfig get]
	lappend configuration user   $::tcl_platform(user)
	lappend configuration format [$plugin plugin]

	return [$plugin do export $serial $configuration]
    }

    # ### ### ### ######### ######### #########
    ## Internal methods

    ##
    # ### ### ### ######### ######### #########
}

# ### ### ### ######### ######### #########
## Ready

package provide doctools::toc::export 0.2
return

# doctoc.tcl --
#
#	The doctoc export plugin. Generation of doctoc markup.
#
# Copyright (c) 2009 Andreas Kupries <[email protected]>
#
# See the file "license.terms" for information on usage and redistribution
# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
# 
# RCS: @(#) $Id: export_doctoc.tcl,v 1.3 2009/11/15 05:50:03 andreas_kupries Exp $

# This package is a plugin for the doctools::toc v2 system.  It takes
# the list serialization of a table of contents and produces text in
# doctoc format.

# ### ### ### ######### ######### #########
## Requisites

# @mdgen NODEP: doctools::toc::export::plugin

# import.tcl --
#
#	Importing indices into other formats.
#
# Copyright (c) 2009-2018 Andreas Kupries <[email protected]>
#
# See the file "license.terms" for information on usage and redistribution
# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
# 
# RCS: @(#) $Id: import.tcl,v 1.3 2011/11/17 08:00:45 andreas_kupries Exp $

# Each object manages a set of plugins for the conversion of keyword

    # ### ### ### ######### ######### #########

    method {import text} {text {format {}}} {
	set plugin [$self GetPlugin $format]

	set     configuration [$myconfig get]
	lappend configuration user   $::tcl_platform(user)
	lappend configuration format [$plugin plugin]

	return [$plugin do import $text $configuration]
    }

    method {import file} {path {format {}}} {
	# The plugin is not trusted to handle the file to convert.
	return [$self import text [fileutil::cat $path] $format]

    ##
    # ### ### ### ######### ######### #########
}

# ### ### ### ######### ######### #########
## Ready

package provide doctools::toc::import 0.2
return

proc import {text configuration} {
    # Note: We cannot fail here on duplicate keys in the input,
    # especially for keywords and references, as we do for Tcl-based
    # canonical toc serializations, because our underlying JSON parser
    # automatically merges them, by taking only the last found
    # definition. I.e. of two or more definitions for a key X the last
    # overwrites all previous occurrences.
    return [doctools::toc::structure canonicalize [json::json2dict $text]]
}

# ### ### ### ######### ######### #########
## Ready

package provide doctools::toc::import::json 0.1

# - children of divisions = if any, elements of the division, references and divisions.
#
# The order of the elements under root, and of the elements under
# their division reflects the order of the information in the parsed
# document.

# Attributes in the nodes, except root provide location information,
# i.e. referring from there in the input the information is coming from
# (human-readable output: line/col for end of token, offset start/end
# for range covered by token.

# # ## ### ##### ######## ############# #####################
## Requirements

package require Tcl 8.4                  ; # Required runtime.

if {![package vsatisfies [package provide Tcl] 8.4]} {return}

# Packages for the doctools toc v2 implementation
# (still v1.1 doctoc language).

# - Index container, mutable toc objects
# - Export and import management
# - Export and import plugins
# - Parser for doctoc markup, and handling serializations
# - Message catalogs for the parser

package ifneeded doctools::toc                 2   [list source [file join $dir container.tcl]]

package ifneeded doctools::toc::export         0.2 [list source [file join $dir export.tcl]]
package ifneeded doctools::toc::import         0.2 [list source [file join $dir import.tcl]]

package ifneeded doctools::toc::export::doctoc 0.1 [list source [file join $dir export_doctoc.tcl]]
package ifneeded doctools::toc::export::html   0.1 [list source [file join $dir export_html.tcl]]
package ifneeded doctools::toc::export::json   0.1 [list source [file join $dir export_json.tcl]]
package ifneeded doctools::toc::export::nroff  0.2 [list source [file join $dir export_nroff.tcl]]
package ifneeded doctools::toc::export::text   0.1 [list source [file join $dir export_text.tcl]]
package ifneeded doctools::toc::export::wiki   0.1 [list source [file join $dir export_wiki.tcl]]

The result of the method is the empty string.

[call [arg objectName] [method up] [arg id]]

This method returns the handle of the parent for the element
identified by its handle [arg id], or the empty string if [arg id]
referred to the root element.

[call [arg objectName] [method next] [arg id]]

This method returns the handle of the right sibling for the element
identified by its handle [arg id], or the handle of the parent if the
element has no right sibling, or the empty string if [arg id] referred
to the root element.

[call [arg objectName] [method prev] [arg id]]

This method returns the handle of the left sibling for the element
identified by its handle [arg id], or the handle of the parent if the
element has no left sibling, or the empty string if [arg id] referred
to the root element.

[call [arg objectName] [method child] [arg id] [arg label] [opt [arg ...]]]

This method returns the handle of a child of the element identified by
its handle [arg id]. The child itself is identified by a series of
labels.

[vset VERSION 0.2]
[comment {-*- tcl -*- doctools manpage}]
[manpage_begin doctools::toc::export n [vset VERSION]]
[keywords conversion]
[keywords doctoc]
[keywords documentation]
[keywords export]
[keywords formatting]
[keywords generation]
[keywords HTML]
[keywords json]
[keywords manpage]
[keywords markup]
[keywords nroff]
[keywords plugin]
[keywords reference]
[keywords table]
[keywords {table of contents}]
[keywords {tcler's wiki}]
[keywords text]
[keywords url]
[keywords wiki]
[copyright {2009-2018 Andreas Kupries <[email protected]>}]
[moddesc   {Documentation tools}]
[titledesc {Exporting tables of contents}]
[category  {Documentation tools}]
[require doctools::toc::export [opt [vset VERSION]]]
[require Tcl 8.4]
[require doctools::config]
[require doctools::toc::structure]
[require snit]
[require pluginmgr]
[description]

If no value is specified it simply returns the current value, without
changing it.

[para]

Note that while the user can set the predefined configuration
variables [const user] and [const format] doing so will have no
effect, these values will be internally overridden when invoking an
import plugin.

[call [arg objectName] [method {config unset}] [arg pattern]...]

This method unsets all configuration variables matching the specified
glob [arg pattern]s. If no pattern is specified it will unset all
currently defined configuration variables.

[vset VERSION 0.2]
[comment {-*- tcl -*- doctools manpage}]
[manpage_begin doctools::toc::import n [vset VERSION]]
[keywords conversion]
[keywords doctoc]
[keywords documentation]
[keywords import]
[keywords json]
[keywords manpage]
[keywords markup]
[keywords parsing]
[keywords plugin]
[keywords reference]
[keywords table]
[keywords {table of contents}]
[keywords url]
[copyright {2009-2018 Andreas Kupries <[email protected]>}]
[moddesc   {Documentation tools}]
[titledesc {Importing keyword indices}]
[category  {Documentation tools}]
[require doctools::toc::import [opt [vset VERSION]]]
[require Tcl 8.4]
[require doctools::config]
[require doctools::toc::structure]
[require snit]
[require pluginmgr]
[description]

If no value is specified it simply returns the current value, without
changing it.

[para]

Note that while the user can set the predefined configuration
variables [const user] and [const format] doing so will have no
effect, these values will be internally overridden when invoking an
import plugin.

[call [arg objectName] [method {config unset}] [arg pattern]...]

This method unsets all configuration variables matching the specified
glob [arg pattern]s. If no pattern is specified it will unset all
currently defined configuration variables.

[enum]
Each error element will be a list containing six strings describing an
error in detail. The strings will be

[list_begin enumerated]
[enum]
The path of the file the error occurred in. This may be empty.

[enum]
The range of the token the error was found at. This range is a
two-element list containing the offset of the first and last character
in the range, counted from the beginning of the input (file). Offsets
are counted from zero.