1doctools::toc::export::nroff(n)Documentation tooldsoctools::toc::export::nroff(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       doctools::toc::export::nroff - nroff export plugin
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require doctools::toc::export::nroff  ?0.2?
14
15       package require doctools::text
16
17       package require doctools::nroff::man_macros
18
19       export serial configuration
20
21______________________________________________________________________________
22

DESCRIPTION

24       This  package  implements  the doctools table of contents export plugin
25       for the generation of nroff markup.
26
27       This is an internal package of doctools, for use by  the  higher  level
28       management  packages  handling  tables  of  contents,  especially  doc‐
29       tools::toc::export, the export manager.
30
31       Using it from a regular interpreter is possible, however only with con‐
32       tortions, and is not recommended.  The proper way to use this function‐
33       ality is through the package doctools::toc::export and the export  man‐
34       ager objects it provides.
35

API

37       The  API  provided  by  this package satisfies the specification of the
38       doctoc export plugin API version 2.
39
40       export serial configuration
41              This command takes the canonical serialization  of  a  table  of
42              contents,  as specified in section ToC serialization format, and
43              contained in serial, the configuration, a dictionary, and gener‐
44              ates  nroff  markup  encoding  the table.  The created string is
45              then returned as the result of the command.
46

CONFIGURATION

48       The nroff export plugin recognizes the  following  configuration  vari‐
49       ables and changes its behaviour as they specify.
50
51       string user
52              This  standard  configuration  variable contains the name of the
53              user running the process which invoked the export  plugin.   The
54              plugin  puts this information into the provenance comment at the
55              beginning of the generated document.
56
57       string file
58              This standard configuration variable contains the  name  of  the
59              file  the  table of contents came from. This variable may not be
60              set or contain the empty string.  The plugin puts this  informa‐
61              tion,  if  defined,  i.e. set and not the empty string, into the
62              provenance comment at the beginning of the generated document.
63
64       boolean inline
65              If this flag is set (default) the plugin will place the  defini‐
66              tions of the man macro set directly into the output.
67
68              If  this  flag  is not set, the plugin will place a reference to
69              the definitions of the man macro set into the  output,  but  not
70              the macro definitions themselves.
71
72       Note that this plugin ignores the standard configuration variables for‐
73       mat, and map, and their values.
74

TOC SERIALIZATION FORMAT

76       Here we specify the format used by the doctools v2 packages to  serial‐
77       ize  tables  of contents as immutable values for transport, comparison,
78       etc.
79
80       We distinguish between regular and canonical serializations.   While  a
81       table  of  contents  may  have more than one regular serialization only
82       exactly one of them will be canonical.
83
84       regular serialization
85
86              [1]    The serialization of any table of contents  is  a  nested
87                     Tcl dictionary.
88
89              [2]    This  dictionary  holds  a single key, doctools::toc, and
90                     its value. This value holds the contents of the table  of
91                     contents.
92
93              [3]    The  contents  of the table of contents are a Tcl dictio‐
94                     nary holding the title of the table of contents, a label,
95                     and its elements. The relevant keys and their values are
96
97                     title  The  value is a string containing the title of the
98                            table of contents.
99
100                     label  The value is a string containing a label  for  the
101                            table of contents.
102
103                     items  The  value  is  a Tcl list holding the elements of
104                            the table, in the order they are to be shown.
105
106                            Each element is a Tcl list holding the type of the
107                            item,  and  its  description,  in  this  order. An
108                            alternative description would be that it is a  Tcl
109                            dictionary  holding  a  single key, the item type,
110                            mapped to the item description.
111
112                            The two legal item types  and  their  descriptions
113                            are
114
115                            reference
116                                   This  item  describes a single entry in the
117                                   table of  contents,  referencing  a  single
118                                   document.   To  this end its value is a Tcl
119                                   dictionary containing an id for the  refer‐
120                                   enced  document, a label, and a longer tex‐
121                                   tual description which  can  be  associated
122                                   with  the  entry.   The  relevant  keys and
123                                   their values are
124
125                                   id     The value is a string containing the
126                                          id  of  the document associated with
127                                          the entry.
128
129                                   label  The value is a string  containing  a
130                                          label  for  this  entry. This string
131                                          also identifies the  entry,  and  no
132                                          two  entries  (references  and divi‐
133                                          sions) in the  containing  list  are
134                                          allowed to have the same label.
135
136                                   desc   The  value  is a string containing a
137                                          longer description for this entry.
138
139                            division
140                                   This item describes a group of  entries  in
141                                   the table of contents, inducing a hierarchy
142                                   of entries.  To this end its value is a Tcl
143                                   dictionary   containing  a  label  for  the
144                                   group, an optional id to a document for the
145                                   whole group, and the list of entries in the
146                                   group.  The relevant keys and their  values
147                                   are
148
149                                   id     The value is a string containing the
150                                          id of the document  associated  with
151                                          the   whole   group.   This  key  is
152                                          optional.
153
154                                   label  The value is a string  containing  a
155                                          label  for  the  group.  This string
156                                          also identifies the  entry,  and  no
157                                          two  entries  (references  and divi‐
158                                          sions) in the  containing  list  are
159                                          allowed to have the same label.
160
161                                   items  The  value is a Tcl list holding the
162                                          elements of the group, in the  order
163                                          they are to be shown.  This list has
164                                          the same structure as the value  for
165                                          the  keyword  items used to describe
166                                          the whole  table  of  contents,  see
167                                          above.  This  closes  the  recusrive
168                                          definition of  the  structure,  with
169                                          divisions  holding  the same type of
170                                          elements as the whole table of  con‐
171                                          tents, including other divisions.
172
173       canonical serialization
174              The  canonical serialization of a table of contents has the for‐
175              mat as specified in the previous  item,  and  then  additionally
176              satisfies  the constraints below, which make it unique among all
177              the possible serializations of this table of contents.
178
179              [1]    The keys found in all the  nested  Tcl  dictionaries  are
180                     sorted  in  ascending  dictionary  order, as generated by
181                     Tcl's builtin command lsort -increasing -dict.
182

BUGS, IDEAS, FEEDBACK

184       This document, and the package it describes, will  undoubtedly  contain
185       bugs  and  other problems.  Please report such in the category doctools
186       of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].   Please
187       also  report any ideas for enhancements you may have for either package
188       and/or documentation.
189
190       When proposing code changes, please provide unified diffs, i.e the out‐
191       put of diff -u.
192
193       Note  further  that  attachments  are  strongly  preferred over inlined
194       patches. Attachments can be made by going  to  the  Edit  form  of  the
195       ticket  immediately  after  its  creation, and then using the left-most
196       button in the secondary navigation bar.
197

KEYWORDS

199       doctools, export, nroff, serialization, table of contents, toc
200

CATEGORY

202       Text formatter plugin
203
205       Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
206
207
208
209
210tcllib                                0.2      doctools::toc::export::nroff(n)
Impressum