1# text.tcl --
2#
3#	The text export plugin. Generation of plain text (ReST -
4#	re-structured text).
5#
6# Copyright (c) 2009 Andreas Kupries <andreas_kupries@sourceforge.net>
7#
8# See the file "license.terms" for information on usage and redistribution
9# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
10#
11# RCS: @(#) $Id: export_text.tcl,v 1.3 2009/11/15 05:50:03 andreas_kupries Exp $
12
13# This package is a plugin for the the doctools::toc v2 system.  It
14# takes the list serialization of a table of contents and produces
15# text in text format.
16
17# ### ### ### ######### ######### #########
18## Requisites
19
20# @mdgen NODEP: doctools::toc::export::plugin
21
22package require Tcl 8.4
23package require doctools::toc::export::plugin ; # Presence of this
24						# pseudo package
25						# indicates execution
26						# inside of a properly
27						# initialized plugin
28						# interpreter.
29package require doctools::toc::structure ; # Verification that the
30					   # input is proper.
31package require doctools::text           ; # Text assembly package
32
33doctools::text::import ;# -> ::text::*
34
35# ### ### ### ######### ######### #########
36## API.
37
38proc export {serial configuration} {
39
40    # Phase I. Check that we got a canonical toc serialization. That
41    #          makes the unpacking easier, as we can mix it with the
42    #          generation of the output, knowing that everything is
43    #          already sorted as it should be.
44
45    ::doctools::toc::structure verify-as-canonical $serial
46
47    # ### ### ### ######### ######### #########
48    # Configuration ...
49    # * Standard entries
50    #   - user   = person running the application doing the formatting
51    #   - format = name of this format
52    #   - file   = name of the file the toc came from. Optional.
53    #   - map    = maps symbolic references to actual file path. Optional.
54
55    # //possible parameters to influence the output.
56    # //* symbolic mapping off/on
57
58    # Import the configuration and initialize the internal state
59
60    array set config $configuration
61    array set map    {}
62    if {[info exists config(map)]} {
63	array set map $config(map)
64    }
65
66    # ### ### ### ######### ######### #########
67
68    # Phase II. Generate the output, taking the configuration into
69    #           account.
70
71    # Unpack the serialization.
72    array set toc $serial
73    array set toc $toc(doctools::toc)
74    unset     toc(doctools::toc)
75
76    text::begin
77    text::+ [Header]
78    text::underline =
79
80    # Iterate over the keys and their references
81    PrintDivision $toc(items)
82
83    # Return final assembled text
84    return [text::done]
85}
86
87proc PrintDivision {items} {
88    foreach element $items {
89	foreach {etype edata} $element break
90	array set toc $edata
91
92	switch -exact -- $etype {
93	    reference {
94		text::newline
95		text::+ "[Map $toc(id)] : $toc(label)"
96		text::newline
97		text::indented 4 { text::+ $toc(desc) }
98		text::newline
99	    }
100	    division {
101		text::newline
102		if {[info exists toc(id)]} {
103		    text::+ "[Map $toc(id)] : $toc(label)"
104		} else {
105		    text::+ "$toc(label)"
106		}
107		text::underline -
108		text::indented 4 {
109		    PrintDivision $toc(items)
110		}
111		text::newline
112	    }
113	}
114    }
115    return
116}
117
118# ### ### ### ######### ######### #########
119
120proc Header {} {
121    upvar 1 toc(label) label toc(title) title
122    if {($label ne {}) && ($title ne {})} {
123	return "$label -- $title"
124    } elseif {$label ne {}} {
125	return $label
126    } elseif {$title ne {}} {
127	return $title
128    }
129    return -code error {Reached the unreachable}
130}
131
132proc Map {id} {
133    upvar 1 map map
134    if {![info exists map($id)]} { return $id }
135    return $map($id)
136}
137
138# ### ### ### ######### ######### #########
139## Ready
140
141package provide doctools::toc::export::text 0.1
142return
143