Positional cues or not

[Jan Skibinski]

On 13 Feb 2001, Marcin 'Qrczak' Kowalczyk wrote:

> > 	Should the documention standard respect the module
> > 	authors' wishes and provide at least some sort of support
> > 	for 'categories'? I think, it should.
> 
> I agree. Sections of a module could be separated by "lots of dashes"
> with a section title together with them (either on the same line or
> on the next).

	Most of what you suggest seems acceptable. Few minor
	points though:

----------------------------------------------------
---- Subsection blah
----------------------------------------------------
	The first and the third line are just visual ASCII hints but they
	have no real meaning. A formatter will use its own means
	of presentation, so they could be safely stripped off. My
	extractor currently arbitrarily ignores any top level sequence of
	8 dashes or more.

> A remaining thing is hyperlinks to different entities or modules (or
> fully qualified entities). It's easy to have SEE as a keyword, but
> we also want to mark an identifier used as a part of a sentence, e.g.
> 
>   To clarify, @doesDirectoryExist@ returns True if a file system object
>   exist, and it's a directory. @doesFileExist@ returns True if the file
>   system object exist, but it's not a directory (i.e., for every other
>   file system object that is not a directory.)

	OK, I see your point about the SEE business. But the second
	part of my previous suggestion can be rephrased using your
	caps idea:

	To clarify, FUNCTION doesDirectoryExist returns True ...
	or
	To clarify, FUNCTION 'doesDirectoryExist' returns True ...

	The first version carries the semantics only, while the
	second one has an additional formatting information
	-- which can be nevertheless considered redundant. 

	BTW, I see Malcolm's point about single quote; but (') just 
	looks lighter in plain ascii and it maybe worthwhile supporting
	it by a careful parsing. Alternatively, a simple rule: "Double
	the single quote, or escape it (\'), if you want it printed"
	would do. Smalltalk uses the doubling rule (their strings
	are in single quotes, and double quotes signify comments), and its
	users are happy enough with it.
	Underscores are fine, but they are also ambiguous since
	some of the function names use them as well. And I bet
	that some of us dislike Hungarian notation and use underscores
	aboundantly. But the same doubling or escape rules could
	be applied here as well. 

	Jan