interface samples

[Jan Skibinski]

	I produced two samples of "long interface", extracted by
	module Extractor and formatted by my new module
	InterfacePrinter.
	Both samples interface to the latter. One is an unformatted
	ascii version (yyy.txt) and the other (yyy.html) is html
	formatted. The latter is intentionally link-free, but
	the cross references can be produced with ease if needed,
	since Extractor produces well structured data representing
	the module.

	Both samples can be found in
	http://www.numeric-quest.com/haskell/.

	I edited the html version a bit, adding few items for
	completness (exports, imports, classes, instances).
	The reason for this is that those edited items are temporarily
	treated as strings, and not structured as yet by Extractor.
	But the rest has been automatically generated and
	-- aside from the edited part -- both versions are factually
	identical.

	I wish to make the following points:

	1. No heavy formatting information is stored in the source file
	from which the interface has been extracted. However, there
	are three hints for html beautifier from InterfacePrinter
	module.
	
	a. Those words in function comments which are intentionally
	embedded in single quotes, refer to function arguments. The
	printer uses this hint to produce italic emphases for html
	version. This hint is also used to prettyfy module comment
	(top of the page) as well, in order to emphasize certain keywords.

	b. Similarly, double quotes could be used as hints to produce
	bold emphases. However, I do not use it so far.

	c. The last hint signifies headers of groups of functions,
	which I call "categories". The hint is a comment that
	starts with "--: ". All other delimiters are stripped off.

	As an example, the banner:
	---------------------------------
	--: interface listings - exported
	---------------------------------
	will be replaced by a single line of this category header:
	"category: interface listing - exported".

	This line will be printed in bold when using html format.

	In summary, the formatting information embedded in the
	sources is very lightweight and does not compromise
	readability of sources. I would even argue that this
	helps to write well structured comments. The cycle:
	write and document a module, extract its interface,
	try to decide whether such interface is able to stand
	on its own and represents readable piece, go back
	and edit your comments again ... should certainly
	produce well structured and readable documentation.

	2. Ascii version has its own merits too. For example,
	by typing in Hugs

	Prelude> f "someFunction" "someSource" shortList Ascii

	you should see the interface of function "someFunction"
	extracted from "someSource".
	This includes the function signature and comments.
	Similarly, you can browse the full listing of this
	function by specifying: codeList instead of shortList.
	Isn't that neat?
	But this is just a side effect. Function 'f' has been
	designed for random testing of module Extractor.

	Variety of interface types can be produced, once
	both modules are ready. I list them in the footnotes
	of yyy.txt or yyy.html. So far, the "long interface"
	(all entities, including private ones) is roughly defined.

	Regards,
	Jan