[Doc-SIG] Compatibility with Stretch/comments

[Tony J Ibbs (Tibs)]

Me:
> Part of this is just that I think a comment (if used) should be
> explicitly identified as such, but mostly it's for compatibility
> with Stretch

David:
> What's "Stretch"? Link?

Interestingly, it doesn't seem to be in the Jargon file (at least, not
under C or S).

OK. The Stretch computer was an IBM machine. IBM were very keen on
keeping later machines compatible with earlier machines. Sometimes this
was a bit silly.

Having done some searching myself:

See http://www.computer.org/history/looking/r30006.htm
and note the text:

	Werner Buchholz (1990) was a member of the IBM 701
	design team and prolific documenter of those early
	designs, including the later Stretch computer
	(a.k.a. the IBM 7030).

(the name isn't relevant here, but the computer name and the tag "early"
are), and:

	Bob O. Evans (1991) was an influential IBM manager
	committed to compatibility, a concept that led to
	the IBM System/360 family of machines.

I caught the phrase off other computer programmers, around the Cambridge
University labs, so it has a (shall we say) venerable history (i.e.,
it's quite old). Basically, as I understand it, it means "compatible
with earlier things, even if that's going a bit far" - the implication
being that "for compatibility with Stretch" was being used as a reason
for keeping features long after any chance of code that had worked on
Stretch still being around, and long after the feature was out-of-date.

In the place I used it, I was just trying to imply that decisions we
make now can have an impact on usage a very long way down the line, and
what seems like a harmless decision now (oh, let's make "explicit
markup" we don't recognise be comments) might be awkward a long way off,
whereas labelling something EXPLICITLY as a comment both does what it
says (heh! it's a comment! it says so!) and is guaranteed *not* to have
such future effects.

It also solves the "when does a comment end" problem (it ends when it
ends by the normal rules for directive text, of course).

As to whether a comment is allowed in a particular place or not - well,
I think they'er a marginal construct at best, so don't much care. But I
bet the question of whether a *directive* is allowed is much more
interesting, and *will* need solving, so by my scheme that will also
solve your comment worry.

(gosh, is that a good enough summary? you did ask for more arguments -
the above is almost lucid!).

As to single colons after directives - I'd like to back off on that.

I think that we should be able to say, instead:

	- explicit markup (hmm - not *quite* sure about
	  this term, but at least it's a form of words)
	  that goes::

	    .. _<something>: text

	  is some form of link target

	- explicit markup that goes::

	    .. <something>:: <maybe optional text>

	  is a directive.

	- explicit markup that does something else
	  is undefined.

Put like that, I think that the difference between ``_something:`` and
``something::`` *is* a useful distinction, so I'd now vote (a) to keep
the double colons, but (b) to require a colon after a footnote ``]`` as
well (as I think I said in another email).

Hmm - work beckons - Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Well we're safe now....thank God we're in a bowling alley.
- Big Bob (J.T. Walsh) in "Pleasantville"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)