J3/01-328r1

Date:     22 Aug 2001
To:       J3
From:     Richard Maine
Subject:  Reorg of c13

A lot of the "fluff" is now out of the early part of c13.  Most of the
remaining material is actually useful.  It could still use some
organizational simplification, which is easier now.  As follows

  The title of 13.1 is pretty uninformative and there is too little
  content in 13.2 to merit a section at that high a level  Suggest

  [271:8] "Intrinsic functions" -> "Classes of intrinsic procedures"
  [271:27] Delete section heading.

  [271:9-10] Delete first sentence of the section.  It repeats what
  was said 2 paras earlier.

  Sections 13.4 and 13.5 are more about the models than the intrinsics.

  [272:14] Change title to "Bit models"
  [272:34] Change title to "Numeric models"

  The body of 13.6 says nothing (I'd guess it to be filler just so that
  the section isn't empty), and the subsections of 13.6 are both about
  arguments (they even say so in their titles) and thus fit under 13.3.

  [273:24-27] Delete
  [273:28 - 274:1] Move to 272:14-, renumbering the sections.

  Section 13.7 has no parallel for functions.  And about half of its body
  doesn't say anything useful anyway.  The first sentence duplicates
  what is said in 2.5.7 (if it really needed to be repeated in c13, it
  should be said about functions as well).  The section xrefs are not
  useful.  The second sentence says nothing that isn't a given, except
  for the part of it that is wrong (a rename could have been used);
  otherwise, an intrinsic subroutine is a subroutine.  We didn't feel
  it necessary to say that intrinsic functions are invoked just like
  other functions.  The 4th sentence also says nothing.  Thus

  [274:2-11]  Delete the section title and the 1st through 4th sentences
  of the section.  Move the remainder to [271:20-]

  [271:18-19] Delete note 13.1.  Now that we've moved the other material,
  including the former note 13.6 up here, this one looks redundant.

  [271:20] Change the first occurance of "function" to procedure; leave
  the 2nd one alone.  (We are about to make 13.8 cover both functions
  and subroutines).

  The separation between 13.8 and 13.9 doesn't seem appropriate at that
  level.  For example, all of the material in 13.8.0 applies equally
  to 13.9 (it even says "procedures" instead of "functions").
  Further, 13.8 has too many subsections with distinctions
  that often aren't useful.

  [274:12] "functions" -> "procedures"

  [278:9] Lower heading level by 1 (becomes 13.8.x).

  Ought to re-organize the 13.8-13.9 subsections.  There are too many
  subsections with too liitle useful categorization.  The substantial
  number of subsections with only one procedure is particularly
  telling.  That a procedure is itself isn't a categorization worth
  making.  The edits below are one hack at it.  There are certainly
  other alternatives - I'm not deeply committed to this one - but I
  think it is an improvement over the current state.

  Perhaps pull together all the inquiry functions.  That's actually
  an important categorization (one that we feel important enough to
  mention in the first sentence of c13).  We have the inquiry functions
  spread out in 9 separate subsections here, 4 of them being subsections
  of one function.  Perhaps 3 subsections of inquiry functions: "numeric
  inquiry functions", "array inquiry functions" (because there are
  citations of that), and "other inquiry functions".  With 9 of the
  numerics, that does seem enough to be worth grouping.  I suppose
  leave kind where it is - it does seem to be in a useful grouping.
  Thus:

  [277:16-20] Move 13.8.15 to [276:17+]

  [274:26-27], [275:41-42], [276:18-19], [277:39-41], [278:2],
  [278:4-6] - Move the whole bodies of 13.8.1, 13.8.5, 13.8.9,
  13.8.20, 13.8.22, plus just the associated intrinsic from 13.8.21,
  to a new section at [276:17++] named "Other inquiry functions"
  (after the insertion above).  Alphabetize them.  Delete the headers
  for the now-empty sections.

  Combine 13.8.7 and 13.8.11 as "Other type conversion functions".
  I was thinking about pulling together all type conversion stuff,
  but the numeric and character ones do seem grouped pretty well
  as is.

  [276:4] Change title to "Other type conversion functions"
  [276:32-33] Move to [276:5+]
  [276:31] Delete heading of now-empty section.

  Combine 13.8.16-18.  The distinctions seem artificial, particularly
  the whole separate section for reshape.

  [277:22-33] Delete section headings 13.8.17 and 13.8.18.
  Then alphabetize the combined bodies.

  Mvbits belongs with the other bit manipulation stuff.  That's a
  far more useful categorization than function vs subroutine.

  [278:19-20] Move to 276:29+]

  [276:20] "functions" -> "procedures"

  Likewise, command_argument_count belongs with the other command-line
  stuff.

  [278:8] Move to [278:9+]
  [278:7] Delete header of now empty section.
  [278:9] Change title to "System environment procedures"
          (we already lowered its heading level approipriately).

  Ok, the random number stuff probably doesn't count as a system
  environment, so make a section for it.

  [278:21-23] Move to a new section titled "Random number subroutines"
  at [278:8+]

  We are now down op only one 1-item subsection here.  I suppose
  null is unusual enough to merit such segregation; it does have
  lots of ways that it is like nothing else.  But it is also now
  more than just a pointer function, so the section title is
  bad.

  [278:1] Change section title to "Null function".

  And make null's description lie less.  The one at 315:4-6 is way
  too long to go here.  Perhaps

  [278:3] Change description to
    "Returns disassociated, unallocated, or deferred result"