Re: Inconsistencies in our approach

[Richard Braakman <dark@xs4all.nl>]

On Thu, Aug 07, 2003 at 04:33:05PM -0500, John Goerzen wrote:
> Documentation consists of instructions primarily intended to be
> human-readable regarding the operation of something such as a program.
> 
> Programs consist of instructions primarily intended to be machine-readable
> that either contain machine language binary data or instructions designed to
> be interpreted or converted into that at runtime.  Programs will always
> contain source code or machine language code, and often both.

Why do you say "programs" here?  I thought you were talking about the
definition of "software".  If you're implicitly assuming that "software"
means "programs" then you're skipping over the point.

In any case, there are families of programming languages where programs
are _not_ instructions, but instead are descriptions of a desired effect.
That's exactly where the line between programs and documentation blurs.

In addition, many programs (the well-written ones not written in Ook!)
are primarily intended to be human-readable.  Machine readability is a
consequence of correctly using the language, not a primary goal.  Compare
this with writing in DocBook, for example.

> I will grant that these definitions are imperfect and improbable arguments
> could be lodged against them; at the same time, I believe that reasonable
> people not engaging in a Jesuit exercise to find logical needles in a
> haystack of common sense are able to tell the difference between a manpage
> and a C source file.

(Presumably you are not aware of the c2man package.)

Pointing at extremes may help to establish a distinction, but it does
not create one.  By that argument you could put "big dogs" and "little
dogs" into separate categories.  Anyone is able to tell the difference
between a chihuahua and a mastiff, but they are still both dogs.

Richard Braakman