Re: [Tcllib-devel] Support for pictures (screenshots) in man pages?

[Andreas K. <and...@ac...>]

> Hello,

> I am thinking of writing a tutorial for Plotchart. Because
> Plotchart is all about the graphical presentation of data,
> I was wondering how I can include screenshots in that
> document. I would use the doctools to mark up the text
> of course, hence my question.

Currently doctools has no official support for images. There is only a
sort-of indirect support through the [uri] command which allows the
embedding of urls in a document.

However even in HTML this is formatted as an <a> tag, not as an <img>, i.e.
a link to the image, instead of an image embedded in the document.

The other formats are worse, as they can only embed the text of the url in
the output instead of the image itself.

Ok, that is the current state. Now what can we do about it ?

The only format in the Tcl world I am aware of which is similar (Text input,
multiple backends) is the TIP format. This format is described in
http://tip.tcl.tk/3 and actually handles images. It does so by having the
user specify a symbolic name and then letting the backend decide on the
actual name of the image file and how to embed it in the output document.
The relevant part of the TIP format specification is

	If the paragraph consists of the sequence "#image:"
	followed by some text, then it is a request to insert
	an image. The first word of the following text is a
	reference to the image, and the other words are an
	optional caption for the image (in plain text.) Image
	references that consist of just letters, numbers,
	hyphens and underscores are handled specially by the
	current implementation, which can map them to the
	correct media type for its current output format
	(assuming it has a suitable image in its repository.)

In essence you say

	#image: foo

and the backends then look for foo.png/gif/txt/ps/eps etc. and do the proper
embedding, i.e. direct insert, <img>-link, etc.

This is something I can see that we can add to doctools with relatively
little work.

Even so, if there are other ideas floating around I am interested in hearing
about them.


--
	Andreas Kupries <and...@Ac...>
	Developer @ http://www.ActiveState.com
	Tel: +1 778-786-1122