{jrichtext.tcl

Introduction
The jrichtext.tcl library is distributed as part of the jstools package.  It consists of a number of procedures for working with multi­font text.  At present, it only supports putting rich text in text widgets; I hope to extend it in the future to generate rich text in other formats, such as PostScript or TeX.  (Once you have rich text in a text widget, though, you can use the jtagconvert.tcl library to convert it to other formats.)

This document describes jrichtext.tcl version 4.1/4.4.

Usage
Accessing the Library
In order to use the jrichtext.tcl library, it (and any other libraries it depends on) must be in your Tcl auto_path, described in tclvars(n).  Information about how to arrange that, and other conventions common to the jstools libraries, is in the Usage section of The jstools Libraries.

Using Rich Text
The general paradigm for using rich text is as follows:

1. Specify a rich­text type and destination with the j:rt command.

2. Optionally, configure visual attributes associated with text styles

3. Issue rich­text generation commands, which can also be thought of as a text format

4. Issue j:rt:done to perform any necessary cleanup

In theory, a type is any kind of object, like a text widget, a file, or a kind of printer or terminal, which can display or store rich text.  Currently, only type text (a Tk text widget) is supported.  A destination is a particular instance of a type - currently a particular text widget, in theory also a particular file or printer.

It's often convenient to group rich­text generation commands together so they can be treated as a unit, or passed as arguments.  (Some of the procedures in the jabout.tcl library do this.)

Here's a short example of using rich text:

	set richtext_example {
	  j:rt:rm {This is a }
	  j:rt:it {very}
	  j:rt:rm { simple example of using the }
	  j:rt:bf {jrichtext.tcl}
	  j:rt:rm { library.}
	}
	
	toplevel .foo
	text .foo.t
	pack .foo.t -in .foo
	j:rt text .foo.t
	eval $richtext_example
	j:rt:done

Credits and Copyright
Author
Jay Sekora 
js@aq.org
http://www.aq.org/~js/

Also, some of the code is modified from code in the standard Tk library from the Tk distribution.

Copyright
The library is copyright © 1992-1995 by Jay Sekora, but may be freely redistributed under the conditions at the top of the file.

Overview
General Convenience Procedures
j:tagged_insert - insert tagged text into a text widget
rm - dummy do­nothing procedure

Rich­Text Management Procedures

These procedures deal with possible destinations - objects (currently only Tk text widgets) that you want to put rich text into.  The most important are j:rt, which identifies a destination, and j:rt:done, which you use when you've finished writing the rich text.

j:rt text - prepare to write rich text to a text widget
j:rt:type - return type of current rich text destination (text, TeX)
j:rt:destination - return current rich text destination (widget, file)
j:rt:textfonts - set fonts for text widget
j:rt:done - finish writing rich text (clear vars, close files)
j:rt:mkabbrevs - make shorter convenience procs, for text­intensive apps

Procedures for Generating Rich Text

These procedures all put rich text into the current destination.  It is an error for there not to be a valid destination - you must already have issued j:rt to set a destination.

j:rt:rm - write rich text (roman)
j:rt:it - write rich text (italic)
j:rt:bf - write rich text (bold face)
j:rt:bi - write rich text (bold italic)
j:rt:tt - write rich text (typewriter - monospaced)
j:rt:h0 - write rich text (level 0 heading, appropriate for document titles)
j:rt:h1 - write rich text (level 1 heading)
j:rt:h2 - write rich text (level 2 heading)
j:rt:h3 - write rich text (level 3 heading)
j:rt:h4 - write rich text (level 4 heading)
j:rt:h5 - write rich text (level 5 heading)
j:rt:hl - an obsolete alias for j:rt:h1
j:rt:tab - tab in rich text
j:rt:cr - line break in rich text
j:rt:par - paragraph break in rich text

See Also
	jtexttags.tcl
	jtagconvert.tcl

j:tagged_insert
Usage
	j:tagged_insert w text taglist
Arguments
	w is the text widget to insert into
	text is the text to insert
	taglist is a list of tags to apply to text

Description
This procedure is lifted from the mkStyles.tcl demo, included in the Tk distribution.  There it was called insertWithTags; I've changed the name for consistency.

This procedure inserts text into w at w's insert point.  It then applies all the tags in taglist, which must be a valid Tcl list, to text, removing any other tags that text might have inherited from it's left neighbor.  If taglist is empty, text will end up without any tags.

rm

Description
This procedure doesn't do anything at all.  It's defined in case you try to use the rm abbreviation for j:rt:rm without first calling j:rt:mkabbrevs.  Depending on your Tcl configuration, the Tcl unknown(n) procedure might then try to execute the Unix rm(1) command, with potentially dangerous results.

j:rt
Usage
	j:rt text w
Arguments
	text tells j:rt that you want to work with a text widget
	w is the text widget you want to start displaying rich text in

Description
This procedure must be used to specify the text widget you want to use before you start using rich­text generation commands.  (Text widget w must already exist.)

j:rt:type
Usage
	j:rt:type

Description
Currently, this procedure just returns the string text.  When the jrichtext.tcl library supports multiple rich­text destination types, this command will return a string specifying what the type of the current destination is.

If there is no current destination, this procedure returns {}.

j:rt:destination
Usage
	j:rt:destination

Description
If the current destination is a text widget (currently the only possible kind of destination), this procedure will return its pathname.

If there is no current destination, this procedure returns {}.

j:rt:textfonts
Usage
	j:rt:textfonts {style font}...
Argument components
	style is a rich­text style (see below)
	font is the X font to use for displaying text in that style

Description
This procedure is only valid if the current destination is a text widget. It takes one or more two­element {style font} lists as arguments.  For each style, a tag in the current destination widget is set to font; the rich­text generation procedures use those tags.  (The actual tags are named richtext:font:style.)

The style argument must be one of roman, italic, bold, bolditalic, typewriter, or heading0 through heading5, corresponding to j:rt:rm, j:rt:it, j:rt:bf, j:rt:bi, j:rt:tt, or j:rt:h0 through j:rt:h5.  (These tags are used by the jtexttags.tcl library, on top of which the procedures in jrichtext.tcl are built.)

j:rt:done
Usage
	j:rt:done

Description
This procedure is used to signal that you are done, at least for the time being, with the current rich­text destination.  It does any necessary cleanup, such as closing open files.  (Actually, with text widgets, this isn't strictly necessary, but I suggest that you use it so that your rich­text sequences will work with other formats in the future.)

j:rt:mkabbrevs
Usage
	j:rt:mkabbrevs

Description
This procedure is useful when you want to allow your users to type stretches of rich text, or when it's important for rich text to be concise.  It simply makes aliases for the rich­text generation procedures without the `j:rt:' prefix.  If you've called j:rt:mkabbrevs, you can then issue, for instance, `rm {Roman nose}' instead of `j:rt:rm {Roman nose}'

Procedures for Inserting Rich Text
Usage
	j:rt:style text
Styles
	rm - roman (ordinary) type
	it - italic or oblique type
	bf - bold face type
	bi - bold italic (or bold oblique) type
	tt - a fixed­pitch font, useful for code examples
	h0 - level 0 heading, appropriate for document titles
	h1 - level 1 heading, appropriate for main section headings
	h2 - level 2 heading
	h3 - level 3 heading
	h4 - level 4 heading
	h5 - level 5 heading
	hl - an obsolete alias for h1
Argument
	text is the text to be inserted in the specified style

Description
These procedures insert the text text in the current destination widget in the given style.  (Strictly speaking, they insert text tagged with specific tags, and you can configure the correspondence of fonts to styles arbitrarily with j:rt:textfonts.)

j:rt:tab
Usage
	j:rt:tab

Description
This procedure inserts a tab into the current destination (in the roman font).

j:rt:cr
Usage
	j:rt:cr

Description
This procedure inserts a line break into the current destination (in the roman font).

j:rt:par
Usage
	j:rt:par

Description
This procedure inserts a paragraph break into the current destination (in the roman font).

Bugs and Misfeatures
* j:rt:textfonts probably really belongs in jtexttags.tcl, unless I generalise it to be useful for other kinds of destination than text widgets.

* Since I'm imposing so many constraints based on generalising to other kinds of destinations than text widgets, I really ought to support some.

* It would be nice to have some way of handling tags other than font tags, so that (say) hypertext or colours could be expressed with the library.  Currently the only way to do that is with the format supported by j:tag:archive_text_widget and j:tag:restore_text_widget in jtexttags.tcl, which isn't really suited for the kinds of uses the jrichtext.tcl library supports.

* In general, jrichtext.tcl and jtexttags.tcl seem to be working at cross purposes to some extent; I wish they were better integrated.

Future Directions
* I think this format is a dead­end; I doubt I'll be doing further work on it.
} {{{jdoc:anchor:anchorname {3.0 4.0 8.0 9.0 44.0 45.0 55.0 56.0 95.0 96.0 108.0 109.0 113.0 114.0 123.0 124.0 132.0 133.0 141.0 142.0 153.0 154.0 160.0 161.0 167.0 168.0 189.0 190.0 196.0 197.0 203.0 204.0}} {sel {6.46 6.53}} {jdoc:xref:link {4.56 4.63 4.380 4.395 10.214 10.235 10.243 10.260 10.264 10.285 25.160 25.170 57.0 57.15 58.0 58.2 62.153 62.157 62.194 62.204 64.0 64.4 65.0 65.9 66.0 66.16 67.0 67.14 68.0 68.9 69.0 69.14 73.152 73.156 75.0 75.7 76.0 76.7 77.0 77.7 78.0 78.7 79.0 79.7 80.0 80.7 81.0 81.7 82.0 82.7 83.0 83.7 84.0 84.7 85.0 85.7 86.0 86.7 87.0 87.8 88.0 88.7 89.0 89.8 92.1 92.14 93.1 93.16 111.134 111.148 151.228 151.241 187.234 187.248 215.214 215.239 215.244 215.269 215.273 215.286 217.32 217.45}} {jdoc:xref:manpage {10.130 10.137 111.196 111.203 111.252 111.254}} {richtext:font:roman {2.0 3.0 4.0 4.4 4.17 4.56 4.63 4.380 4.395 6.24 6.37 8.0 10.0 10.20 10.33 10.106 10.115 10.130 10.137 10.218 10.225 10.247 10.252 10.264 10.285 12.0 13.0 15.23 15.27 15.32 15.43 15.53 15.57 21.9 21.18 23.13 23.17 23.163 23.167 23.204 23.215 25.160 25.170 29.0 43.0 44.0 46.0 47.0 47.9 48.0 48.22 52.0 53.0 55.0 57.18 58.0 58.5 60.0 61.0 62.36 62.48 62.153 62.157 62.194 62.204 64.0 64.12 65.0 65.12 66.0 66.19 67.0 67.17 68.0 68.12 69.0 69.17 71.0 72.0 73.152 73.156 75.0 75.10 76.0 76.10 77.0 77.10 78.0 78.10 79.0 79.10 80.0 80.7 81.0 81.7 82.0 82.7 83.0 83.7 84.0 84.7 85.0 85.7 86.0 86.10 86.32 86.39 87.0 87.11 88.0 88.10 89.0 89.11 91.0 92.0 92.1 92.14 93.1 93.16 95.0 97.0 97.1 97.31 98.0 99.0 99.1 99.2 100.1 100.5 101.1 101.8 101.39 101.43 103.0 104.0 104.34 104.46 104.107 104.121 106.23 106.27 106.33 106.34 106.38 106.39 106.89 106.96 106.133 106.137 106.168 106.172 106.223 106.230 106.241 106.245 108.0 109.0 110.0 111.0 111.84 111.86 111.104 111.111 111.134 111.148 111.196 111.203 111.252 111.254 113.0 115.0 115.1 115.12 116.0 117.0 117.1 117.5 117.12 117.16 118.1 118.2 120.0 121.0 121.139 121.140 123.0 125.0 125.1 125.10 127.0 128.0 128.50 128.54 128.66 128.79 130.59 130.61 132.0 134.0 134.1 134.17 136.0 137.0 139.59 139.61 141.0 143.0 143.1 143.28 144.0 145.0 145.1 145.6 146.1 146.5 148.0 149.0 149.107 149.119 149.207 149.211 149.293 149.312 151.4 151.9 151.34 151.39 151.41 151.47 151.49 151.53 151.55 151.65 151.67 151.77 151.82 151.90 151.99 151.107 151.126 151.133 151.135 151.142 151.144 151.151 151.153 151.160 151.162 151.169 151.174 151.181 151.190 151.197 151.228 151.241 151.285 151.298 153.0 155.0 155.1 155.10 157.0 158.0 160.0 162.0 162.1 162.15 164.0 165.0 165.221 165.226 165.254 165.268 165.305 165.320 165.334 165.354 167.0 169.0 169.1 169.16 170.0 171.0 171.1 171.3 172.1 172.3 173.1 173.3 174.1 174.3 175.1 175.3 176.1 176.3 177.1 177.3 178.1 178.3 179.1 179.3 180.1 180.3 181.1 181.3 182.1 182.3 182.28 182.30 183.0 184.0 184.1 184.5 184.50 184.55 186.0 187.0 187.33 187.37 187.85 187.90 187.234 187.248 189.0 191.0 191.1 191.9 193.0 194.0 196.0 198.0 198.1 198.8 200.0 201.0 203.0 205.0 205.1 205.9 207.0 208.0 210.0 211.0 211.2 211.16 211.44 211.57 215.214 215.239 215.244 215.269 215.273 215.286 215.340 215.353 217.14 217.27 217.32 217.45 219.0 220.0 221.0}} {richtext:font:italic {15.23 15.27 15.32 15.43 23.13 23.17 23.204 23.215 62.36 62.48 97.17 97.18 97.19 97.23 97.24 97.31 99.1 99.2 100.1 100.5 101.1 101.8 101.39 101.43 106.23 106.27 106.33 106.34 106.38 106.39 106.89 106.96 106.133 106.137 106.168 106.172 106.223 106.230 106.241 106.245 115.11 115.12 118.1 118.2 121.139 121.140 143.17 143.22 143.23 143.27 145.1 145.6 146.1 146.5 149.108 149.113 149.114 149.118 149.207 149.211 149.307 149.312 151.4 151.9 169.6 169.11 169.12 169.16 184.1 184.5 184.50 184.55 187.33 187.37 187.85 187.90}} {richtext:font:bold {4.4 4.17 4.56 4.63 4.380 4.395 6.24 6.37 10.20 10.33 10.218 10.225 25.160 25.170 92.1 92.14 93.1 93.16 104.34 104.46 128.66 128.79 151.228 151.241 151.285 151.298 211.44 211.57 215.273 215.286 215.340 215.353 217.14 217.27 217.32 217.45}} {richtext:font:bolditalic {10.247 10.252 10.264 10.285}} {richtext:font:typewriter {10.106 10.115 10.130 10.137 15.53 15.57 21.9 21.18 23.163 23.167 29.0 43.0 47.0 47.9 48.0 48.22 57.0 57.18 58.0 58.5 62.153 62.157 62.194 62.204 64.0 64.12 65.0 65.12 66.0 66.19 67.0 67.17 68.0 68.12 69.0 69.17 73.152 73.156 75.0 75.10 76.0 76.10 77.0 77.10 78.0 78.10 79.0 79.10 80.0 80.7 81.0 81.7 82.0 82.7 83.0 83.7 84.0 84.7 85.0 85.7 86.0 86.10 86.32 86.39 87.0 87.11 88.0 88.10 89.0 89.11 97.1 97.17 97.18 97.19 97.23 97.24 104.107 104.121 111.84 111.86 111.104 111.111 111.134 111.148 111.196 111.203 111.252 111.254 115.1 115.11 117.1 117.5 117.12 117.16 125.1 125.10 128.50 128.54 130.59 130.61 134.1 134.17 139.59 139.61 143.1 143.17 143.22 143.23 143.27 143.28 149.107 149.108 149.113 149.114 149.118 149.119 149.293 149.307 151.34 151.39 151.41 151.47 151.49 151.53 151.55 151.65 151.67 151.77 151.82 151.90 151.99 151.107 151.126 151.133 151.135 151.142 151.144 151.151 151.153 151.160 151.162 151.169 151.174 151.181 151.190 151.197 155.1 155.10 162.1 162.15 165.221 165.226 165.254 165.268 165.305 165.320 165.334 165.354 169.1 169.6 169.11 169.12 171.1 171.3 172.1 172.3 173.1 173.3 174.1 174.3 175.1 175.3 176.1 176.3 177.1 177.3 178.1 178.3 179.1 179.3 180.1 180.3 181.1 181.3 182.1 182.3 182.28 182.30 187.234 187.248 191.1 191.9 198.1 198.8 205.1 205.9 211.2 211.16 215.214 215.239 215.244 215.269}} {richtext:font:heading0 {1.0 2.0}} {richtext:font:heading1 {3.0 4.0 8.0 9.0 44.0 45.0 55.0 56.0 95.0 96.0 108.0 109.0 113.0 114.0 123.0 124.0 132.0 133.0 141.0 142.0 153.0 154.0 160.0 161.0 167.0 168.0 189.0 190.0 196.0 197.0 203.0 204.0 210.0 211.0 219.0 220.0}} {richtext:font:heading2 {9.0 10.0 12.0 13.0 45.0 46.0 52.0 53.0 56.0 57.0 60.0 61.0 71.0 72.0 91.0 92.0 96.0 97.0 98.0 99.0 103.0 104.0 110.0 111.0 114.0 115.0 116.0 117.0 120.0 121.0 124.0 125.0 127.0 128.0 133.0 134.0 136.0 137.0 142.0 143.0 144.0 145.0 148.0 149.0 154.0 155.0 157.0 158.0 161.0 162.0 164.0 165.0 168.0 169.0 170.0 171.0 183.0 184.0 186.0 187.0 190.0 191.0 193.0 194.0 197.0 198.0 200.0 201.0 204.0 205.0 207.0 208.0}} {jdoc:anchorname:Introduction {3.0 4.0}} {jdoc:link:jstools.jdoc {4.56 4.63}} {jdoc:anchorname:Usage {8.0 9.0}} {jdoc:manpage:tclvars {10.130 10.137}} {jdoc:link:jslibraries.tcl {10.214 10.235}} {jdoc:link:jslibraries.jdoc#Usage {10.243 10.260}} {jdoc:link:jslibraries.jdoc {10.264 10.285}} {{} {44.0 49.0 51.0 53.0 218.0 219.0}} {jdoc:anchorname:Credits_and_Copyright {44.0 45.0}} {jdoc:anchorname:Overview {55.0 56.0}} {jdoc:link:jtagconvert.tcl.jdoc {4.380 4.395 93.1 93.16}} {jdoc:link:jabout.tcl.jdoc {25.160 25.170}} {jdoc:link:#j:tagged_insert {57.0 57.15}} {jdoc:link:j:rt.jdoc {64.0 64.4}} {jdoc:link:j:rt:type.jdoc {65.0 65.9}} {jdoc:link:j:rt:destination.jdoc {66.0 66.16}} {jdoc:link:j:rt:textfonts.jdoc {67.0 67.14}} {jdoc:link:j:rt:done.jdoc {68.0 68.9}} {jdoc:link:j:rt:mkabbrevs.jdoc {69.0 69.14}} {jdoc:link:j:rt:tab.jdoc {87.0 87.8}} {jdoc:link:j:rt:cr.jdoc {88.0 88.7}} {jdoc:link:j:rt:par.jdoc {89.0 89.8}} {jdoc:link:#rm {58.0 58.2}} {jdoc:anchorname:j:tagged_insert {95.0 96.0}} {jdoc:anchorname:rm {108.0 109.0}} {jdoc:link:#j:rt:mkabbrevs {111.134 111.148}} {jdoc:manpage:rm {111.252 111.254}} {jdoc:manpage:unknown {111.196 111.203}} {jdoc:link:#j:rt {62.153 62.157 73.152 73.156}} {jdoc:link:#j:rt:done {62.194 62.204}} {jdoc:anchorname:j:rt {113.0 114.0}} {jdoc:anchorname:j:rt:type {123.0 124.0}} {jdoc:anchorname:j:rt:destination {132.0 133.0}} {jdoc:anchorname:j:rt:textfonts {141.0 142.0}} {jdoc:anchorname:j:rt:done {153.0 154.0}} {jdoc:anchorname:j:rt:mkabbrevs {160.0 161.0}} {jdoc:link:jtexttags.tcl.jdoc {92.1 92.14 151.228 151.241 215.273 215.286 217.32 217.45}} {jdoc:anchorname:j:rt: {167.0 168.0}} {jdoc:link:#j:rt:textfonts {187.234 187.248}} {jdoc:link:#j:rt: {75.0 75.7 76.0 76.7 77.0 77.7 78.0 78.7 79.0 79.7 80.0 80.7 81.0 81.7 82.0 82.7 83.0 83.7 84.0 84.7 85.0 85.7 86.0 86.7}} {jdoc:anchorname:j:rt:tab {189.0 190.0}} {jdoc:anchorname:j:rt:cr {196.0 197.0}} {jdoc:anchorname:j:rt:par {203.0 204.0}} {jdoc:link:jtexttags.tcl.jdoc#j:tag:archive_text_widget {215.214 215.239}} {jdoc:link:jtexttags.tcl.jdoc#j:tag:restore_text_widget {215.244 215.269}}} {{matchend 217.23} {richptr 221.0} {abbrevstart 220.75} {abbrevend 220.78} {insert 6.53} {matchstart 217.14} {anchor 1.0} {current 9.21}}} {}