tkar 0.63 → 0.64

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4196633cb35d88e09177f98152a39c7e270e430c
+  data.tar.gz: d49c7da5c07643a4eb64a122dfcaf719739570a2
+SHA512:
+  metadata.gz: 8c3331fa2839d571f00e824df61e30e8c22e3a85d1043d8af16d403bac82b0c29725a9ffdbb02f19d7556144717b62b4a645d8a46bcbaecb51afd6290f34494d
+  data.tar.gz: 41d04aded1f21bc6bda145d67f288d512fab7a64bf456825683b80c32cfdc5ad9d88b39748e835cd1947bda13f21fd8690ce0ba2b7355952b7b312771a1fa1de

data/COPYING

@@ -0,0 +1,22 @@
+Copyright (c) 2006-2014, Joel VanderWerf, vjoel@users.sourceforge.net
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met: 
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer. 
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution. 
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,142 @@
+# Tkar -- Tk-based animation process and protocol
+
+The Tkar animator aims to do one thing well: listen to an incoming stream of data and animate it in a 2D canvas. User interaction is streamed back out.
+
+Additional documentation:
+
+* [protocol](doc/protocol.md)
+* [FAQ](doc/faq.md)
+
+## Overview
+
+Tkar is a Tk/ruby-based animation program using TkCanvas. It accepts command input from stdin or a socket. Commands may define parametrized shapes, place them on the canvas, move and rotate them, change parameters, etc. User interaction events (click, drag, etc) are sent back on the socket or stdout. The canvas can be resized, scrolled, zoomed, and tracked to an object.
+
+### Graphical constructs
+
+* Shapes include: arc, oval, polygon, line, curve, text, bitmap. 
+
+* Parameters include color/pattern of border/area, arrowheads, splines, line dot/dash/width, text font, etc.
+
+* Can group, layer, rotate, move, and scale objects
+
+### Tkar command summary
+
+command| effect
+------| ------
+_shape_| define shape in terms of primitives (Tk Canvas objects). Shape may expose any Tk parameters (e.g, colors, lengths of poly sides)
+_add_| add object to canvas with specified shape, layer, position, rotation, params
+_move_, _rotate_, _scale_, _delete_| operate on existing object
+_param_| change param value of an object (e.g. change color or geometry over time; change arrow shape because endpoint moves)
+_wait_| playback with specified frame rate
+_update_| finish time step
+_params_| set window params (color, size, zoom)
+_follow_| follow a specified object
+_load_| load file (like #include)
+
+### User interaction
+
+* Use keys and mouse to zoom, pan/scroll, select, double-click, drag, drop, etc.
+
+* User commands are sent back over stream to controlling process, e.g. "drag 2 140.0 259.0" and "drop 2 7" ("2" and "7" are object ids)
+
+
+## Installation
+
+### Prerequisites
+
+#### Tcl/Tk
+
+For windows: http://www.activestate.com/Products/ActiveTcl/
+
+For linux, just use your distribution's package tool to install tcl. However, you may need to make sure that ruby and linux both use (or do not use) the pthread library.
+
+#### Ruby
+
+For windows: http://rubyforge.org/projects/rubyinstaller/
+
+For other platforms: http://www.ruby-lang.org
+
+### Gem installation
+
+      gem install tkar
+
+Alternately, you can download the source code (tar ball or git repo) and run it in place using the <tt>--local-lib</tt> command line option
+
+      bin/tkar --local-lib
+
+
+## Usage
+
+### Command line
+
+See the -h command line option for details on running tkar.
+
+Examples are available with the source code--read the comments to see how to run.
+
+### Tkar window
+
+Press the "h" key for on-line help using the tkar window.
+
+### Protocol
+
+See [protocol](doc/protocol.md) for details on the protocol and writing shape files.
+
+### Integrating tkar with other applications
+
+There are three transport options:
+
+1. Over pipe
+
+  Invoke as
+
+      cat data | tkar
+
+  or
+
+      program | tkar
+
+  - unidirectional (no mouseclick feedback to program)
+
+  - output messages simply go to stdout
+
+  - easy to write filters this way
+
+2. Over TCP socket
+
+  Invoke as
+
+      tkar [<ipaddr>] <port>
+
+  - bidirectional; client can block waiting for update to finish
+
+  - remote host possible, using ipaddr=="localhost"
+
+  - if port is 0, lets OS choose port and prints it to stderr
+
+  - can still write filters by using netcat
+
+3. Over unix domain socket
+
+  Invoke as
+
+      tkar /path/to/socket
+
+  - bidirectional; client can block waiting for update to finish
+
+  - faster than TCP (but unix/linux only)
+
+Note that tkar has a -c option which tells it to be the socket client rather than the server. This is useful when your main program needs to choose the port, for example.
+
+## Tkar and Simulink
+
+Tkar can be interfaced with Simulink. Tkar appears in a simulink model as a block to which can be wired to any number of data sources that drive objects in the animation. You can have several tkar blocks. Think of tkar as the animation version of the built-in plotting block. (Simulink's built-in animation capabilities are bad.)
+
+An additional set of C files need to be compiled as a Simulink extension. Contact author for details.
+
+## Author
+
+Copyright 2006-2014, Joel VanderWerf, mailto:vjoel@users.sourceforge.org
+
+## License
+
+License is BSD. See [COPYING](COPYING).

data/Rakefile

@@ -0,0 +1,64 @@
+require 'rake'
+require 'rake/testtask'
+
+PRJ = "tkar"
+
+def version
+  @version ||= begin
+    require 'tkar/version'
+    warn "Tkar::VERSION not a string" unless Tkar::VERSION.kind_of? String
+    Tkar::VERSION
+  end
+end
+
+def tag
+  @tag ||= "#{PRJ}-#{version}"
+end
+
+desc "Run tests"
+Rake::TestTask.new :test do |t|
+  t.libs << "lib"
+  t.libs << "ext"
+  t.test_files = FileList["test/**/*.rb"]
+end
+
+desc "Commit, tag, and push repo; build and push gem"
+task :release => "release:is_new_version" do
+  require 'tempfile'
+  
+  sh "gem build #{PRJ}.gemspec"
+
+  file = Tempfile.new "template"
+  begin
+    file.puts "release #{version}"
+    file.close
+    sh "git commit --allow-empty -a -v -t #{file.path}"
+  ensure
+    file.close unless file.closed?
+    file.unlink
+  end
+
+  sh "git tag #{tag}"
+  sh "git push"
+  sh "git push --tags"
+  
+  sh "gem push #{tag}.gem"
+end
+
+namespace :release do
+  desc "Diff to latest release"
+  task :diff do
+    latest = `git describe --abbrev=0 --tags --match '#{PRJ}-*'`.chomp
+    sh "git diff #{latest}"
+  end
+
+  desc "Log to latest release"
+  task :log do
+    latest = `git describe --abbrev=0 --tags --match '#{PRJ}-*'`.chomp
+    sh "git log #{latest}.."
+  end
+
+  task :is_new_version do
+    abort "#{tag} exists; update version!" unless `git tag -l #{tag}`.empty?
+  end
+end

data/{FAQ.rdoc → doc/faq.md}

@@ -1,18 +1,18 @@
-= Design Decisions
+# Design Decisions
 
-== what is tkar trying to be?
+## what is tkar trying to be?
 
 The gnuplot of animation -- a quick and dirty way to get data (stream or file) into a window to see what is happening.
 
-== why Tk?
+## why Tk?
 
 Tcl/Tk is widely available, and the Ruby/Tk interface is a standard part of ruby.
 
-== why TkCanvas?
+## why TkCanvas?
 
 TkCanvas has easy access to relatively high-level 2D vector graphics constructs, such as groups, layers, splines, fonts, icons, zoom, and scroll. Plus, it supports mouse/keyboard operations, dialogs, and so on.
 
-== why not just write code in Ruby/Tk instead of stream to tkar?
+## why not just write code in Ruby/Tk instead of stream to tkar?
 
 1. Because you may not want to write your code in the Tk framework. Maybe you're using a different gui, or not a gui at all.
 
@@ -22,18 +22,18 @@ TkCanvas has easy access to relatively high-level 2D vector graphics constructs,
 
 4. You can distribute processing: take advantage of 2 cpus, or even 2 hosts across a network.
 
-== why not HTML 5 canvas, other gui canvas, or Processing?
+## why not HTML 5 canvas, other gui canvas, or Processing?
 
 Those are heavyweight and add more dependencies (browser, java), and in some cases still lack some of the features of TkCanvas. Tkar is light enough that you can run several instances at once even on resource limited machines.
 
-== why not opengl?
+## why not opengl?
 
 It would be more work to get the diagram and user interaction stuff. Anyway, it's overkill.
 
-== why a special protocol, rather than ruby/tk method calls serialized as text?
+## why a special protocol, rather than ruby/tk method calls serialized as text?
 
 The protocol is not a programming language: there are no variables, functions, loops, etc. There are only macros. It is very simple, which makes it much easier to emit from other languages than ruby, and less prone to programming errors.
 
-== why is the protocol so ugly?
+## why is the protocol so ugly?
 
 It's not meant to be written by hand. You wouldn't write http headers by hand, would you?

data/{History.txt → doc/old-history.txt}

@@ -1,3 +1,7 @@
+tkar 0.64
+
+- move to github; standardize release tasks; update docs
+
 tkar 0.63
 
 - Use bones and git.

data/{protocol.rdoc → doc/protocol.md}

@@ -1,206 +1,205 @@
-= Tkar protocol
+# Tkar protocol
 
 This document describes the syntax and semantics of the text commands sent over the two-way communication stream (pipe, tcp socket, unix socket) to the tkar process. (The binary protocol is not documented here.)
 
 See also the command-line options for tkar by running it with the -h option:
 
-  tkar -h
+      tkar -h
 
-== Syntax
+## Syntax
 
 Commands are case sensitive and separated by newlines, and arguments are separated (from commands and from each other) by spaces:
 
-  command1 arg0 arg1 arg2
-  command2 arg0 arg1 arg2
+      command1 arg0 arg1 arg2
+      command2 arg0 arg1 arg2
 
 Use a backslash ("\") character at the end of a line to continue to the next line:
 
-  command1 arg0 \
-    arg1 arg2
+      command1 arg0 \
+        arg1 arg2
 
 Blank lines are ignored. Spaces before text on a line are ignored. Extra spaces between arguments is not significant.
 
 Lines which are blank up to a # character are ignored (the text after the # is a comment):
 
-  command1 arg0 arg1 arg2
-  #command2 arg0 arg1 arg2 this line is not executed
+      command1 arg0 arg1 arg2
+      #command2 arg0 arg1 arg2 this line is not executed
 
 However, # characters are significant after non-whitespace characters:
 
-  command1 arg0 arg1 #F0A020
+      command1 arg0 arg1 #F0A020
 
 The last argument is a typical color parameter.
 
-== Process control
+## Process control
 
-<b><tt>wait t</tt></b>
+*`wait t`*
 
 Tells tkar to sleep for up to t seconds before processessing the next command. The value may be floating point.
 
 Wait is a way to keep the frame rate constant. A single timer with memory is used for all waits, so that if wait is called repeatedly, sleep time is reduced by the amount of time used for processing since the last wait. If processing time is less than wait time, the next processing cycle will begin exactly t seconds after the previous one (subject to OS process scheduling limitations).
 
-<b><tt>done</tt></b>
+*`done`*
 
 Tells tkar to stop processing inputs, closing the input stream.
 
-This is useful in exactly one case: only on MS Windows _and_ when input comes from a pipe (not a socket). Send a +done+ message when you are finished sending animation data to tkar. Otherwise, waiting for input that never arrives causes the UI thread to freeze, due to a bug in the VC6 MSVCRT.DLL.
+This is useful in exactly one case: only on MS Windows _and_ when input comes from a pipe (not a socket). Send a `done` message when you are finished sending animation data to tkar. Otherwise, waiting for input that never arrives causes the UI thread to freeze, due to a bug in the VC6 MSVCRT.DLL.
 
-<b><tt>exit</tt></b>
+*`exit`*
 
 Exit the tkar process.
 
-<b><tt>load FILE</tt></b>
+*`load FILE`*
 
-Load the specified command file before proceeding with the next command. Any commands take the same effect as if they occurred in the current command sequence. Any number of files may be nested. The file is searched for first assuming that <tt>FILE</tt> is an absolute path and then, if the load command is nested in another file, relative to the dir of that file. The file name may contain spaces; no quotation is needed.
+Load the specified command file before proceeding with the next command. Any commands take the same effect as if they occurred in the current command sequence. Any number of files may be nested. The file is searched for first assuming that `FILE` is an absolute path and then, if the load command is nested in another file, relative to the dir of that file. The file name may contain spaces; no quotation is needed.
 
-<b><tt>echo arg arg ...</tt></b>
+*`echo arg arg ...`*
 
 Echo the arguments back on the output stream from tkar (the same output stream that contains user command messages as described later in this document).
 
 
-== Window control
+## Window control
 
-<b><tt>title TITLE</tt></b>
+*`title TITLE`*
 
-Sets the title of the window to <tt>TITLE</tt>.
+Sets the title of the window to `TITLE`.
 
-<b><tt>background COLOR</tt></b>
+*`background COLOR`*
 
 Sets the window background color to <TT>COLOR</tt>. See the section on colors for an explanation of the argument.
 
-<b><tt>width X</tt></b>
+*`width X`*
 
 Sets the width (in pixels) of the animation window. (The window can be resized using the mouse.)
 
-<b><tt>height Y</tt></b>
+*`height Y`*
 
 Sets the height (in pixels) of the animation window. (The window can be resized using the mouse.)
 
-<b><tt>window_xy X Y</tt></b>
+*`window_xy X Y`*
 
 Sets the position of the window on the screen. Positive coordinates denote offset of window from left or top edge of screen. Negative coordinates denote offset from right or bottom edge.
 
-<b><tt>zoom_to Z</tt></b>
+*`zoom_to Z`*
 
 Sets the zoom level of the animation window. A value of 1 means no zoom. A larger value makes objects look bigger. A smaller (positive) value makes objects look smaller. (The zoom can be changed using the mouse or the keyboard--see the help text for the window.)
 
-<b><tt>view_at X Y</tt></b>
+*`view_at X Y`*
 
 Scroll the canvas so that the point X Y (in canvas coordinates) is at the center of the window.
 
-<b><tt>view_id ID</tt></b>
+*`view_id ID`*
 
 Scroll the canvas so that the object with specified id is at the center of the window.
 
-<b><tt>follow ID</tt></b>
+*`follow ID`*
 
 As the animation updates, scroll the window so that the object with specified id is at the center of the window.
 
-<b><tt>bounds X_MIN Y_MIN X_MAX Y_MAX</tt></b>
+*`bounds X_MIN Y_MIN X_MAX Y_MAX`*
 
 Sets the dimensions of the canvas (of which only a portion is visible at a time in the window). The default values are <tt>-3000 -3000 3000 3000</tt>.
 
-<b><tt>update</tt></b>
+*`update`*
 
 Draws all changed objects to the canvas.
 
-<i>Should be called after each time-step (and after all the +move+, +rot+, etc. commands pertaining to the timestep have been sent) to update the display</i>.
+*Should be called after each time-step (and after all the `move`, `rot`, etc. commands pertaining to the timestep have been sent) to update the display*.
 
 
-== Shape definition
+## Shape definition
 
 A shape definition is used to define how an object is drawn. Each object on the canvas has a shape. A shape is built out of one or more drawing primitives. A shape can reference another shape as a macro and can be parametrized, so that two objects with the same shape may look quite different. A parametrized shape can also be used for an object which changes its geometry or color dynamically.
 
 The basic syntax of a shape definition is:
 
-<b><tt>shape SHAPE_NAME PART0 PART1 PART2...</tt></b>
+*`shape SHAPE_NAME PART0 PART1 PART2...`*
 
-This defines a new shape with specified SHAPE_NAME, which may be any string without whitespace. The PART strings are one or more space-free strings defining
-the parts of the shape.
+This defines a new shape with specified `SHAPE_NAME`, which may be any string without whitespace. The `PART` strings are one or more space-free strings defining the parts of the shape.
 
-The order of the PARTs is significant: later parts are drawn after, and therefore appear to be above the earlier parts.
+The order of the `PART`s is significant: later parts are drawn after, and therefore appear to be above the earlier parts.
 
 The parts can be primitives (discussed below) or other shapes that have already been defined.
 
-=== Part Syntax
+### Part Syntax
 
-Each PART is of the form:
+Each `PART` is of the form:
 
-  partnameARG,ARG,ARG,....
+    partnameARG,ARG,ARG,....
 
-There are no spaces (or line continuations) within the entire PART.
+There are no spaces (or line continuations) within the entire `PART`.
 
 The following rules apply:
 
-- +partname+ can be the name of a primitive or of another shape. In the latter case, the other shape acts as a _macro_, expanding its own primitives within the shape being defined. For example:
-
-    shape foo line0,0,10,10
-    shape bar foo
+- `partname` can be the name of a primitive or of another shape. In the latter case, the other shape acts as a _macro_, expanding its own primitives within the shape being defined. For example:
+  
+      shape foo line0,0,10,10
+      shape bar foo
 
   is equivalent to
 
-    shape foo line0,0,10,10
-    shape bar line0,0,10,10
+      shape foo line0,0,10,10
+      shape bar line0,0,10,10
 
   Any (finite!) number of macros can be nested. Macros may take arguments; see the section on parametrized shapes.
 
 - Arguments are separated from each other by a comma, but no spaces.
 
-- The _positional_ arguments (i.e., the arguments whose meaning derives from their index in the list of arguments) of a primitive are appended to the name of the primitive <i>without any separating spaces or other characters</i>. For example:
-
-    shape label text0,50
+- The _positional_ arguments (i.e., the arguments whose meaning derives from their index in the list of arguments) of a primitive are appended to the name of the primitive *without any separating spaces or other characters*. For example:
+  
+      shape label text0,50
 
   Positional arguments are almost always coordinates, distances, or angles.
 
 - The _key_-_value_ arguments (i.e., the arguments whose meaning derives from the key string paired with the value), if any, are appended after the positional arguments. They may occur in any order. The key and value are separated by a colon. For example:
-
-    shape label text0,50,anchor:c,justify:center,width:40,text:Untitled,fc:0
+  
+      shape label text0,50,anchor:c,justify:center,width:40,text:Untitled,fc:0
 
 - In some cases, a single argument must be used to designate a list. In those cases, the "+" character is used to separate the values. For example, as an argument to a line primitive, the following denotes a list of three numbers, 10, 8, and 6, as the value for the arrowshape option:
-
-    shape arrow line0,0,*0,0,arrow:last,arrowshape:10+8+6
+  
+      shape arrow line0,0,*0,0,arrow:last,arrowshape:10+8+6
 
 - If only key-value arguments are present, use a comma to separate the first argument from the name of the shape:
+  
+      shape car carbox,fc:red
 
-    shape car carbox,fc:red
-
-- In some cases, a value might need to include spaces (text, for example). In that case, use a parameter for that value and use the +param+ command to set the actual value. See the +text+ command entry.
+- In some cases, a value might need to include spaces (text, for example). In that case, use a parameter for that value and use the `param` command to set the actual value. See the `text` command entry.
 
-=== Parametrized shapes
+### Parametrized shapes
 
-If a string of the form <tt>*N</tt>, where N is a sequence of digits, occurs in a shape definition, then the shape is parametric. Parameters are not named and can only be referred to by the number +N+.
+If a string of the form `*N`, where `N` is a sequence of digits, occurs in a shape definition, then the shape is parametric. Parameters are not named and can only be referred to by the number `N`.
 
-In an +add+ command, the +N+-th parameter supplied with the command is substituted into all places where <tt>*N</tt> appears in the shape definition. For example, the commands:
+In an `add` command, the `N`-th parameter supplied with the command is substituted into all places where `*N` appears in the shape definition. For example, the commands:
 
-  shape box rect*0,*0,*1,*1
-  add box 3 - 100 30 50 0 5 10
+      shape box rect*0,*0,*1,*1
+      add box 3 - 100 30 50 0 5 10
 
 add a box defined by the points 5 5 and 10 10 at position 30 50. (Note that the coordinates 5 5 and 10 10 are in the shape's local coordinate system, whereas the coordinates 30 50 are in the canvas's global coordinates.)
 
-<i>Note: all of these examples can be entered as standard input to tkar. Just make sure to type</i> +update+ <i>when you want to see the effect.</i>
+*Note: all of these examples can be entered as standard input to tkar. Just make sure to type* `update` *when you want to see the effect.*
 
 Parametrized shapes can be used as macros inside of shape definitions, in which case their parameters are substituted when the macro is expanded. For example:
 
-  shape box rect*0,*0,*1,*1
-  shape two_boxes box-20,-10 box10,20
-  add two_boxes 3 - 100 30 50 0
+      shape box rect*0,*0,*1,*1
+      shape two_boxes box-20,-10 box10,20
+      add two_boxes 3 - 100 30 50 0
 
-Paramters can be passed to a macro as well as to a primitive:
+Parameters can be passed to a macro as well as to a primitive:
 
-  shape box rect*0,*0,*1,*1
-  shape two_boxes box-20,*0 box*0,20
-  add two_boxes 3 - 100 30 50 0 10
+      shape box rect*0,*0,*1,*1
+      shape two_boxes box-20,*0 box*0,20
+      add two_boxes 3 - 100 30 50 0 10
 
-Note that the last line above ends with a single parameter value, 10, which is passed to the *0 parameter in +two_boxes+.
+Note that the last line above ends with a single parameter value, 10, which is passed to the *0 parameter in `two_boxes`.
 
 Note that not only positional arguments but also key-value arguments can be parametrized:
 
-  shape box rect*0,*0,*1,*1,fc:*2
-  add box 3 - 100 30 50 0 5 10 red
+      shape box rect*0,*0,*1,*1,fc:*2
+      add box 3 - 100 30 50 0 5 10 red
 
-== Drawing primitives
+## Drawing primitives
 
-Drawing primitives are used only within shape definitions. Primitives cannot be +add+-ed directily to the canvas. (This is because all primitives require some coordinates to outline the shape, but the +add+ command only supplies coordinates of the _center_ [or origin] of the shape.)
+Drawing primitives are used only within shape definitions. Primitives cannot be `add`-ed directily to the canvas. (This is because all primitives require some coordinates to outline the shape, but the `add` command only supplies coordinates of the _center_ [or origin] of the shape.)
 
 Since these primitives are implemented directly in terms of TkCanvas primitives, the Tk manual is a helpful reference: http://www.tcl.tk/man/tcl8.4/TkCmd/canvas.htm. Individual sections are linked to from the sections below.
 
@@ -218,186 +217,189 @@ Points to bear in mind when reading the Tk documentation:
 
 - The object ID is handled by Tk as a _tag_.
 
-=== Coordinates
+### Coordinates
 
-The coordinate system while defining shapes always has the following characteristics, regardless of the <tt>--flip</tt> and <tt>--radians</tt> command-line arguments:
+The coordinate system while defining shapes always has the following characteristics, regardless of the `--flip` and `--radians` command-line arguments:
 
 - The coordinate system is left-handed: positive x is to the right, positive y is down.
 
-- The origin is the center of the shape (about which the shape will be rotated by the +rot+ command).
+- The origin is the center of the shape (about which the shape will be rotated by the `rot` command).
 
 - Angles are measured in degrees clockwise from the positive x axis.
 
 All primitives in the shape definition use this same coordinate system.
 
-The coordinate system used when _adding_ objects to the canvas or moving them is different, and the orientation and units depend on the <tt>--flip</tt> and <tt>--radians</tt> options.
+The coordinate system used when _adding_ objects to the canvas or moving them is different, and the orientation and units depend on the `--flip` and `--radians` options.
 
-=== Colors
+### Colors
 
 Color can be specified by name or by numeric value, using one of the notations
 
-  #RGB
-  #RRGGBB
-  #RRRGGGBBB
+      #RGB
+      #RRGGBB
+      #RRRGGGBBB
 
 where each R or G or B is replaced by a hexidecimal digit. Alternately, a decimal integer can be used.
 
 A list of color names is at http://www.tcl.tk/man/tcl8.4/TkCmd/colors.htm. Examples:
 
-  green
-  DarkOrchid2
-  #EECC66
-  #F0F
+      green
+      DarkOrchid2
+      #EECC66
+      #F0F
 
-=== Generic options
+### Generic options
 
 The following options apply to most primitives (each option has a shortcut, which is listed second).
 
-====<b><tt>fill:COLOR</tt></b>
+#### *`fill:COLOR`*
 
-====<b><tt>fc:COLOR</tt></b>
+#### *`fc:COLOR`*
 
 Set the fill color of the primitive.
 
-====<b><tt>outline:COLOR</tt></b>
+#### *`outline:COLOR`*
 
-====<b><tt>oc:COLOR</tt></b>
+#### *`oc:COLOR`*
 
 Set the outline color of the primitive.
 
-====<b><tt>width:WIDTH</tt></b>
+#### *`width:WIDTH`*
 
-====<b><tt>wi:WIDTH</tt></b>
+#### *`wi:WIDTH`*
 
 Set the line (or outline) width.
 
-====<b><tt>dash:DASH_TYPE</tt></b>
+#### *`dash:DASH_TYPE`*
 
-====<b><tt>da:DASH_TYPE</tt></b>
+#### *`da:DASH_TYPE`*
 
 Set the dash type for the line (or outline). The value can be an integer or a string. See http://www.tcl.tk/man/tcl8.4/TkCmd/canvas.htm#M27. For example,
 
-  da:48
+      da:48
 
 produces a nice dashed line to represent the lines between lanes in a roadway. The 4 means 4 pixels without color; the 8 means 8 pixels with the specified outline color. Tk accepts any sequence of digits, but not all platforms support all sequences.
 
-====<b><tt>stipple:STIPPLE_TYPE</tt></b>
+#### *`stipple:STIPPLE_TYPE`*
 
-====<b><tt>st:STIPPLE_TYPE</tt></b>
+#### *`st:STIPPLE_TYPE`*
 
 Set the stipple type for the region. See http://www.tcl.tk/man/tcl8.4/TkCmd/canvas.htm#M111. (This is not very useful.)
 
-=== Primitives
+### Primitives
 
 The primitives are the basic shapes from which user-defined shapes are built.
 
-==== arc
+#### arc
 
-<b><tt>arcX,Y,W,H,key:val...</tt></b>
+*`arcX,Y,W,H,key:val...`*
 
 Draw an arc-based shape, which may be a pieslice, a chord region (between a chord and the arc), or a true arc (segment of a circle or oval).
 
-The point X Y is the center, W is width, H is height.
+The point `X Y` is the center, `W` is width, `H` is height.
 
-<i>Note that this differs from Tk's arc command,</i> whose inputs are two points: "two diagonally opposite corners of a rectangular region enclosing the oval". It's generally easier to work with center and height/width. Rotation may look strange if width != height (this is because the rectangular region is still used internally, and Tk doesn't rotate rectangles).
+*Note that this differs from Tk's arc command,* whose inputs are two points: "two diagonally opposite corners of a rectangular region enclosing the oval". It's generally easier to work with center and height/width. Rotation may look strange if width != height (this is because the rectangular region is still used internally, and Tk doesn't rotate rectangles).
 
 Options (in addition to the generic options) are:
 
-<tt>extent:angle</tt>::  angular span of the arc
-<tt>start:angle</tt>::   angle of rotation of the arc, measured
-                         _counterclockwise_ from the positive x-axis
-<tt>style:sty</tt>::     +pieslice+, +chord+, or +arc+
-<tt></tt>
+option| values
+------| ------
+`extent:angle`|  angular span of the arc
+`start:angle`|   angle of rotation of the arc, measured _counterclockwise_ from the positive x-axis
+`style:sty`|     `pieslice`, `chord`, or `arc`
 
 See http://www.tcl.tk/man/tcl8.4/TkCmd/canvas.htm#M119
 
-==== line
+#### line
 
-<b><tt>lineX1,Y1,X2,Y2...,key:val...</tt></b>
+*`lineX1,Y1,X2,Y2...,key:val...`*
 
 Draw a line or other one-dimensional curve.
 
-The curve follows the sequence of points X1 Y1, X2 Y2, ....
+The curve follows the sequence of points `X1 Y1, X2 Y2, ....`
 
 Options (in addition to the generic options) are:
 
-<tt>arrow:val</tt>::            +none+, +first+, +last+, or +both+
-<tt>arrowshape:N+N+N</tt>::     three numbers separated by a \+ character(*)
-<tt>capstyle:style</tt>::       +butt+, +projecting+, +round+
-<tt>joinstyle:style</tt>::      +miter+, +bevel+, +round+
-<tt>smooth:bool</tt>::          +true+ or +false+
-<tt>splinesteps:number</tt>::   number of smoothing steps
-<tt></tt>
+option| values
+------| ------
+`arrow:val`|            `none`, `first`, `last`, or `both`
+`arrowshape:N+N+N`|     three numbers separated by a \+ character(*)
+`capstyle:style`|       `butt`, `projecting`, `round`
+`joinstyle:style`|      `miter`, `bevel`, `round`
+`smooth:bool`|          `true` or `false`
+`splinesteps:number`|   number of smoothing steps
 
 (*) Paraphrasing the Tk documentation on arrowshape: The first number gives the distance along the line from the neck of the arrowhead to its tip. The second number gives the distance along the line from the trailing points of the arrowhead to the tip, and the third number gives the distance from the outside edge of the line to the trailing points.
 
 See http://www.tcl.tk/man/tcl8.4/TkCmd/canvas.htm#M139
 
-==== oval
+#### oval
 
-<b><tt>ovalX1,Y1,X2,Y2,key:val...</tt></b>
+*`ovalX1,Y1,X2,Y2,key:val...`*
 
 Draws a circle or oval.
 
-The points X1 Y1 and X2 Y2 define the diagonally opposite corners of the bounding box of the oval.
+The points `X1 Y1` and `X2 Y2` define the diagonally opposite corners of the bounding box of the oval.
 
 There are no options other than the generic options.
 
 See http://www.tcl.tk/man/tcl8.4/TkCmd/canvas.htm#M146
 
-==== rect
+#### rect
 
-<b><tt>rectX1,Y1,X2,Y2,key:val...</tt></b>
+*`rectX1,Y1,X2,Y2,key:val...`*
 
 Draws a rectangle.
 
-The points X1 Y1 and X2 Y2 define the diagonally opposite corners.
+The points `X1 Y1` and `X2 Y2` define the diagonally opposite corners.
 
-<i>Note: A rect is not rotatable. Use a polygon instead.</i>
+*Note: A rect is not rotatable. Use a polygon instead.*
 
 There are no options other than the generic options.
 
 See http://www.tcl.tk/man/tcl8.4/TkCmd/canvas.htm#M151
 
-==== poly
+#### poly
 
-<b><tt>polyX1,Y1,X2,Y2,...key:val...</tt></b>
+*`polyX1,Y1,X2,Y2,...key:val...`*
 
 Draw a polygon or closed curve.
 
-The edges or curve segments follow the sequence of points X1 Y1, X2 Y2, .... and the last point is connected to the first.
+The edges or curve segments follow the sequence of points `X1 Y1, X2 Y2, ....` and the last point is connected to the first.
 
 Options (in addition to the generic options) are:
 
-<tt>joinstyle:val</tt>::        +miter+, +bevel+, or +round+
-<tt>smooth:bool</tt>::          +true+ or +false+
-<tt>splinesteps:number</tt>::   number of smoothing steps
-<tt></tt>
+option| values
+------| ------
+`joinstyle:val`|        `miter`, `bevel`, or `round`
+`smooth:bool`|          `true` or `false`
+`splinesteps:number`|   number of smoothing steps
 
 See http://www.tcl.tk/man/tcl8.4/TkCmd/canvas.htm#M147
 
-==== text
+#### text
 
-<b><tt>textX,Y,key:val...</tt></b>
+*`textX,Y,key:val...`*
 
 Draws text string at the indicated location. (Text is not rotatable.)
 
 Options (in addition to the generic options) are:
 
-<tt>anchor:anchorPos</tt>::     +center+, +n+, +nw+, ...
-<tt>font:fontName</tt>::        font name
-<tt>justify:how</tt>::          +left+, +right+, or +center+
-<tt>text:string</tt>::          string to display(**)
-<tt>width:lineLength</tt>::     length at which line is wrapped
-<tt></tt>
+option| values
+------| ------
+`anchor:anchorPos`|     `center`, `n`, `nw`, ...
+`font:fontName`|        font name
+`justify:how`|          `left`, `right`, or `center`
+`text:string`|          string to display(**)
+`width:lineLength`|     length at which line is wrapped
 
 (**) text with embedded spaces can be specified only via a param command.
 
 See http://www.tcl.tk/man/tcl8.4/TkCmd/canvas.htm#M152
 
-==== image
+#### image
 
-<b><tt>imageX,Y,key:val...</tt></b>
+*`imageX,Y,key:val...`*
 
 Draws an image from a file at the indicated location. (An image is not rotatable.)
 
@@ -405,135 +407,136 @@ Tk supports only GIF, by default, though Tk can be extended to support other for
 
 Options (in addition to the generic options) are:
 
-<tt>anchor:anchorPos</tt>::     +center+, +n+, +nw+, ...
-<tt>image:imageFileName</tt>::  file name of the gif file 
-<tt></tt>
+option| values
+------| ------
+`anchor:anchorPos`|     `center`, `n`, `nw`, ...
+`image:imageFileName`|  file name of the gif file 
 
 Note that tkar is smart about caching image data. The file is read once, no matter how many times it is referenced in different shapes.
 
 See http://www.tcl.tk/man/tcl8.4/TkCmd/canvas.htm#M134
 
-==== polybox
+#### polybox
 
-<b><tt>polyboxDX,DY</tt></b>
+*`polyboxDX,DY`*
 
-Draws a rotatable rectangle extending DX units on each side of the Y axis, and extending DY units above and below the X axis.
+Draws a rotatable rectangle extending `DX` units on each side of the Y axis, and extending `DY` units above and below the X axis.
 
 Not a Tk primitive, but a simple poly-derived shape that can be used to draw a rectangle with rotation. This doesn't have an offset parameter. If the rectangle needs to be offset from the shape origin, use a polygon.
 
 There are no options other than the generic options.
 
 
-== Object manipulation
+## Object manipulation
 
-<b><tt>add SHAPE_NAME ID FLAGS LAYER X Y R [PARAM0 PARAM1 ...]</tt></b>
+*`add SHAPE_NAME ID FLAGS LAYER X Y R [PARAM0 PARAM1 ...]`*
 
-Add an object to the canvas. The shape of the object is determined by the SHAPE_NAME, which must have been defined using the <tt>shape</tt> command.
+Add an object to the canvas. The shape of the object is determined by the SHAPE_NAME, which must have been defined using the `shape` command.
 
-The ID must be a unique nonnegative integer in the range 0..2^32-1. If an object with that ID already exists (with any shape), the new object will replace the existing object.
+The `ID` must be a unique nonnegative integer in the range 0..2^32-1. If an object with that `ID` already exists (with any shape), the new object will replace the existing object.
 
-FLAGS is a string which is currently unused but will be used to set various flags (such as clickable and draggable).
+`FLAGS` is a string which is currently unused but will be used to set various flags (such as clickable and draggable).
 
-LAYER is a nonnegative integer in the range 0..2^32-1 which specifies the drawing order. Higher numbers cause objects to be drawn on top of objects with lower layer numbers.
+`LAYER` is a nonnegative integer in the range 0..2^32-1 which specifies the drawing order. Higher numbers cause objects to be drawn on top of objects with lower layer numbers.
 
-The X Y and R parameters are floating point signed decimal numbers describing the global coordinates and rotation of the object. These numbers define the origin and rotation that are used to draw the primitives of SHAPE_NAME. See the <tt>moveto</tt> and <tt>rot</tt> commands.
+The `X` `Y` and `R` parameters are floating point signed decimal numbers describing the global coordinates and rotation of the object. These numbers define the origin and rotation that are used to draw the primitives of `SHAPE_NAME`. See the `moveto` and `rot` commands.
 
-The PARAM parameters are as described for the <tt>param</tt> command. A PARAM given in the add command cannot include spaces. However, a PARAM given with the param command _can_ include spaces.
+The `PARAM` parameters are as described for the `param` command. A `PARAM` given in the add command cannot include spaces. However, a `PARAM` given with the `param` command _can_ include spaces.
 
-Only the PARAM fields are optional--all others are required.
+Only the `PARAM` fields are optional--all others are required.
 
-<b><tt>del ID</tt></b>
+*`del ID`*
 
-Deletes the object with the specified ID from the canvas.
+Deletes the object with the specified `ID` from the canvas.
 
-<b><tt>delete_all</tt></b>
+*`delete_all`*
 
 Deletes all objects. Does not delete shape definitions.
 
-<b><tt>moveto ID X Y</tt></b>
+*`moveto ID X Y`*
 
-Move the object with the specified ID to canvas coordinates X Y. (The coordinate system is left handed unless the --flip command line option is used.)
+Move the object with the specified `ID` to canvas coordinates `X` `Y`. (The coordinate system is left handed unless the --flip command line option is used.)
 
-<b><tt>rot ID R</tt></b>
+*`rot ID R`*
 
-Rotate the object with the specified ID to R degrees (absolute, not relative to current rotation). (Uses radians if the --radians command line option is given.)
+Rotate the object with the specified `ID` to `R` degrees (absolute, not relative to current rotation). (Uses radians if the --radians command line option is given.)
 
-<b><tt>param ID N VALUE</tt></b>
+*`param ID N VALUE`*
 
-Set the N-th parameter (index starting from 0) of object ID to VALUE. Params can be used to control many aspects of a shape, including colors, dimensions, offsets, line characteristics, boolean flags, text, etc.
+Set the N-th parameter (index starting from 0) of object `ID` to `VALUE`. Params can be used to control many aspects of a shape, including colors, dimensions, offsets, line characteristics, boolean flags, text, etc.
 
 It is not possible to modify the flags, layer, or shape--use an add command to do that (if you add an object with the same ID as before, the old object will be deleted).
 
-<b><tt>scale_obj ID xf yf</tt></b>
+*`scale_obj ID xf yf`*
 
-Scales the object in the x dimension by a x factor of +xf+ and in the y dimension by a factor of +yf+. A factor of 1.0 means no scaling. A factor of 2.0 means double size, and so on.
+Scales the object in the x dimension by a x factor of `xf` and in the y dimension by a factor of `yf`. A factor of 1.0 means no scaling. A factor of 2.0 means double size, and so on.
 
-== Abbreviations
+## Abbreviations
 
 Most commands have abbreviated or alternate versions. The following list shows all commands with alternates indicated by a | character and abbreviations indicated by a > character (for example, update can be abbreviated as "u" or "up").
 
-  a>dd
-  d>el>ete
-  m>ove>to
-  r>ot>ate
-  p>ar>am
-  s>h>ape
-  u>p>date
-  title
-  background|bg
-  height
-  width
-  zoom_to|zoom
-  view_at|view
-  view_id
-  wait
-  follow
-  done
-  bound>s
-  load
-  exit
-  delete_all
-  scale>_obj
-  echo
-  window_xy
-
-
-== Tkar outputs
+      a>dd
+      d>el>ete
+      m>ove>to
+      r>ot>ate
+      p>ar>am
+      s>h>ape
+      u>p>date
+      title
+      background|bg
+      height
+      width
+      zoom_to|zoom
+      view_at|view
+      view_id
+      wait
+      follow
+      done
+      bound>s
+      load
+      exit
+      delete_all
+      scale>_obj
+      echo
+      window_xy
+
+
+## Tkar outputs
 
 Tkar sends outputs back on the stream to the controlling process. Typically this stream is either the stdout of tkar or a socket. Tkar also writes output to stderr.
 
-=== User command messages
+### User command messages
 
 Tkar sends back outputs as the result of user interaction. These output commands can be used to update the controlling program's model of the objects, or to implement simple GUI widgets (buttons, sliders, control points, etc.).
 
-<b><tt>drag DRAG_ID X Y</tt></b>
+*`drag DRAG_ID X Y`*
 
-User has dragged the object with id DRAG_ID to X Y.
+User has dragged the object with id `DRAG_ID` to `X` `Y`.
 
-<b><tt>drop DRAG_ID [TARGET_ID]</tt></b>
+*`drop DRAG_ID [TARGET_ID]`*
 
-User has dropped the object with id DRAG_ID. If TARGET_ID is given, the object was dropped on top of the object with id TARGET_ID.
+User has dropped the object with id `DRAG_ID`. If `TARGET_ID` is given, the object was dropped on top of the object with id `TARGET_ID`.
 
-<b><tt>click ID</tt></b>
+*`click ID`*
 
-User has clicked on object with id ID.
+User has clicked on object with id `ID`.
 
-<b><tt></tt>doubleclick ID</b>
+*`doubleclick ID`*
 
-User has doubleclicked on object with id ID.
+User has doubleclicked on object with id `ID`.
 
-<b><tt>quit</tt></b>
+*`quit`*
 
 User has pressed Ctrl-q
 
-<b><tt>update</tt></b>
+*`update`*
 
 Update cycle has finished. This message is sent back out by tkar once for every update command that comes into tkar. This is useful to keep the two programs, tkar and the controlling program, in sync.
 
-=== Error messages
+### Error messages
 
 Error messages are also sent back to the controlling process on the stream.
 
-=== stderr messages
+### stderr messages
 
 Tkar uses stderr as a second destination for outputs, separate from the stream used by the controlling process. This is useful for diagnostics and logging. If the -v (verbose) command-line option is given, the stderr output copies all input commands. This can be used to create a replayable record of the animation. The stderr stream also includes error messages.