1# text.tcl --
2#
3#	The NROFF export plugin. Generation of man.macros based nroff markup.
4#
5# Copyright (c) 2009 Andreas Kupries <andreas_kupries@sourceforge.net>
6#
7# See the file "license.terms" for information on usage and redistribution
8# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
9#
10# RCS: @(#) $Id: export_nroff.tcl,v 1.4 2009/08/07 18:53:11 andreas_kupries Exp $
11
12# This package is a plugin for the doctools::idx v2 system.  It takes
13# the list serialization of a keyword index and produces text in nroff
14# format, man.macros based.
15
16# ### ### ### ######### ######### #########
17## Requisites
18
19# @mdgen NODEP: doctools::idx::export::plugin
20
21package require Tcl 8.4
22package require doctools::idx::export::plugin ; # Presence of this
23						# pseudo package
24						# indicates execution
25						# inside of a properly
26						# initialized plugin
27						# interpreter.
28package require doctools::idx::structure    ; # Verification that the
29					      # input is proper.
30package require doctools::text              ; # Text assembly package
31package require doctools::nroff::man_macros ; # Macro definitions for result.
32
33doctools::text::import ;# -> ::text::*
34
35# ### ### ### ######### ######### #########
36## API.
37
38proc export {serial configuration} {
39
40    # Phase I. Check that we got a canonical index 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::idx::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 index came from. Optional.
53    #   - map    = maps symbolic references to actual file path. Ignored
54    #
55    # Specific
56    #   - inline = boolean. if set (default) man.macros is inlined in
57    #              the output. other a .so reference to the file is
58    #              generated.
59
60    # Import the configuration and initialize the internal state
61
62    array set config {
63	inline 1
64    }
65    array set config $configuration
66
67    # ### ### ### ######### ######### #########
68
69    # Phase II. Generate the output, taking the configuration into
70    #           account.
71
72    # Unpack the serialization.
73    array set idx $serial
74    array set idx $idx(doctools::idx)
75    unset     idx(doctools::idx)
76    array set r $idx(references)
77
78    text::begin
79    text::indenting 0 ; # Just in case someone tries to.
80
81    Provenance
82    if {$config(inline)} {
83	text::newline?
84	text::+ [doctools::nroff::man_macros::contents]
85    } else {
86	.so man.macros
87    }
88    .TH $idx(label)
89    .SH index
90    if {$idx(title) ne {}} {
91	text::+ $idx(title)
92    }
93    .RS
94
95    # Iterate over the keys and their references
96    foreach {keyword references} $idx(keywords) {
97	# Print the key
98	text::+ $keyword
99	text::newline
100	# Iterate over the references
101	.RS
102	foreach id $references {
103	    foreach {type label} $r($id) break
104	    .TP [BOLD $id]
105	    text::newline
106	    text::+ $label
107	    text::newline
108	}
109	.RE
110	if {[llength $references]} {
111	    .PP
112	}
113    }
114
115    return [text::done]
116}
117
118# ### ### ### ######### ######### #########
119
120proc Provenance {} {
121    upvar 1 config config
122    COMMENT  "Generated @ [clock format [clock seconds]]"
123    COMMENT  "By          $config(user)"
124    if {[info exists config(file)] && ($config(file) ne {})} {
125	COMMENT "From file   $config(file)"
126    }
127    return
128}
129
130proc .so {file} {
131    text::newline?
132    text::+ ".so $file"
133    text::newline
134    return
135}
136
137proc .TP {text} {
138    text::newline?
139    text::+ .TP
140    text::newline
141    text::+ $text
142    return
143}
144
145proc COMMENT {text} {
146    set pfx "'\\\" " ;#
147    text::newline?
148
149    foreach line [split $text \n] {
150	text::+ $pfx
151	text::+ $line
152	text::newline
153    }
154    #text::+ $pfx[join [split $text \n] \n$pfx]
155    return
156}
157
158proc BOLD {text} {
159    return \\fB$text\\fR
160}
161
162proc .RS {} {
163    text::newline?
164    text::+ .RS
165    text::newline
166    return
167}
168
169proc .RE {} {
170    text::newline?
171    text::+ .RE
172    text::newline
173    return
174}
175
176proc .PP {} {
177    text::newline?
178    text::+ .PP
179    text::newline
180    return
181}
182
183proc .SH {name} {
184    text::newline?
185    text::+ ".SH "
186    set hasspaces [regexp {[ 	]} $name]
187    set name [string toupper $name]
188
189    if {$hasspaces} { text::+ \" }
190    text::+ $name
191    if {$hasspaces} { text::+ \" }
192    text::newline
193    return
194}
195
196proc .TH {name} {
197    text::newline?
198    text::+ ".TH "
199    set hasspaces [regexp {[ 	]} $name]
200    set name [string toupper $name]
201
202    if {$hasspaces} { text::+ \" }
203    text::+ $name
204    if {$hasspaces} { text::+ \" }
205    text::newline
206    return
207}
208
209# ### ### ### ######### ######### #########
210## Ready
211
212package provide doctools::idx::export::nroff 0.3
213return
214