# 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 multifont 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 richtext type and destination with the `j:rt` command.

2. Optionally, configure visual attributes associated with text styles

3. Issue richtext 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 richtext 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 donothing procedure

### RichText 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 textintensive 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 richtext 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 richtext 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 richtext 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 twoelement `{`style`` font`}` lists as arguments. For each style, a tag in the current destination widget is set to font; the richtext 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 richtext 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 richtext 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 richtext 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 fixedpitch 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 deadend; I doubt I'll be doing further work on it.
`
`