Silly newbie question - Carrot character (^)

[Mark Wooding]

Nobody <nobody at nowhere.com> writes:

> You're taking "how" too literally, so let me rephrase that:
>
>   A reference manual tells you what you need to know in order to use
>   the language. A specification tells you what you need to know in
>   order to implement it.

I still don't see those as being different.

A language reference should set out all of the details of the language
syntax and semantics.  It should answer every question of the form `what
happens if I write this?'  In so doing, it /must/ also provide enough
information for an implementer to write an new implementation.

> A tutorial provides an overview of the language, but won't necessarily
> describe every aspect (maybe not even close), and is generally
> designed to be read in order.

Agreed.

> A reference manual would describe whatever you need to know in order
> to "use" the language. It shouldn't omit anything short of the "you
> are not expected to understand this" level. IOW, any omissions
> shouldn't matter unless you are e.g. writing analysis utilities which
> need to accept /any/ valid program and interpret it correctly.

`Using' a language involves two activities: writing it, and reading it.
You're only considering one of those activities, and I think it's the
less important one.

> E.g. a reference manual would need to describe indentation, but
> details such as the interpretation of a mixture of tabs and spaces can
> be limited to "don't do this", whereas a specification would need to
> either specify the details or at least specify that it invokes
> "undefined behaviour".

I'm confronted with some code, written by someone else, and when I run
it I get an unexpected result.  The language reference should be able to
explain to me precisely why I get the result that I see.  If it can't,
it's of no value.

> I'm arguing that the reference manual reads too much like a specification.
> E.g. look at "5.2.4. List displays" and tell me whether you consider that
> it adequately /explains/ list displays to someone wishing to use them.

It doesn't adequately specify them either.  That section is just poorly
written.

> I note that the "reference manual" contains very few examples. For a
> specification, this would be quite normal, as examples can serve to
> undermine precision. For a reference manual, precision has to be traded
> for clarity, which may mean using examples where appropriate.

I disagree with both claims.  Examples cannot undermine precision: if
the normative text is correct then an example can only demonstrate an
application of the specified rules.  If the normative text is wrong then
the specification is broken and needs fixing.

But the same applies to a reference.  Either it supplies enough detail
to answer every question about how programs behave or it's broken:
precision is essential here, but is not -- and cannot -- be compromised
by adding examples.

> OTOH, a tutorial often contains little more than a sequence of examples
> along with informal explanations as to their structure and functioning. As
> a result, tutorials tend to lack precision; they provide specific cases
> which will work and some "clues" as to what else is likely to work.

Yes, I'm familiar with the `leave the reader to fill in the gaps in my
exposition for himself' approach to documentation -- and with the
unenjoyable task of fixing the reader's confused mental model
afterwards.

-- [mdw]