J3/12-126r2 To: J3 From: Malcolm Cohen Subject: More editorial changes for intrinsic procedures. Date: 2012 February 14 1. Introduction Clause 13 makes unnecessary and frequently incorrect use of the verb "to return". These should be reworded. (The incorrect uses are when referring to subroutines - these do not return any value!) In the particular case when these are in the function Descriptions, this makes the grammar wrong; a function produces a result value, therefore should always be a noun phrase - a verb clause should only be used for a procedure that performs some visible action - and "return" does not qualify for that either. The usage in the descriptions of ATOMIC_DEFINE, ATOMIC_REF and EXECUTE_COMMAND_LINE (what was it guilty of?) are proper usages. Some of the brief descriptions are unnecessarily long, resulting in poor typesetting of Table 13.1; for example "Reduce array with bitwise AND operation" splits "opera-tion" across 2 lines. Also, some reductions are "reduce by" and others are "reduce with"; "reduce by" is shorter so let's use that. As for bitwise AND, I would suggest either additionally dropping the word operation, or changing it to "by the IAND function". These descriptions are just witter, so as long as we convey the intention and avoid contradicting the full definition we are fine. Also, the subscripting is typeset wrongly in NORM2; it has $d_{\text{DIM-1}}$ where it should be $d_{\text{DIM}-1}$ like everywhere else. Note: some of the entries have more than one alternative, this leaves it up to the editor when applying the changes. Note: FINDLOC has considerable internal problems and contradictions, which are not entirely fixed by this paper. 2. Edits to 10-007r1 [319:8+4] 13.5 Standard generic intrinsic procedures, Table 13.1, entry for ACHAR, "Convert ASCII code value to character" ->"Character from ASCII code value". {It does not "convert" anything - the original is unchanged. Its value is the character corresponding to that ASCII code value, viz "from".} [319:8+7] Same table, entry for ADJUSTL, "Rotate string to remove leading blanks" -> "Left-justified string value". {The string is not rotated, the result value is the rotation. If making this one character longer breaks the typesetting, use a short version.} [319:8+8] Same table, entry for ADJUSTR, "Rotate string to remove leading blanks" -> "Right-justified string value". {The string is not rotated, the result value is the rotation. If making this one character longer breaks the typesetting, use a short version.} [319:8+11] Same table, entry for ALL, "Reduce logical array by AND operation" ->"Array reduced by .AND. operator" {The original array is unchanged, should be a noun phrase.} [319:8+12] Same table, entry for ALLOCATED, "Query allocation status", ->"Allocation status of allocatable variable". {Should be a noun phrase, this one fits.} [319:8+14] Same table, entry for ANY, "Reduce logical array with OR operation" ->"Array reduced by .OR. operator" {The original array is unchanged, should be a noun phrase; wording was inconsistent.} [319:8+17] Same table, entry for ASSOCIATED, "Query pointer association status" ->"Pointer association status inquiry" {Should be a noun phrase. It does not return the full pointer association status, thus "inquiry".} [320:top+5] Same table, entry for CHAR, "Convert code value to character" ->"Character from code value". {Noun phrase. "Character code conversion" would be ok, but is less informative.} [320:top+14] Same table, entry for CPU_TIME, "Return the processor time" -> "Processor time used". {Unnecessary verb.} [320:top+16] Same table, entry for DATE_AND_TIME, "Return date and time" -> "Date and time". {Incorrect verb.} [320:bottom-20] Same table, entry for EXTENDS_TYPE_OF, "Query dynamic type for extension" ->"Dynamic type extension inquiry". {Noun phrase.} [320:bottom-12] Same table, entry for GET_COMMAND, "Query program invocation command" ->"Get program invocation command". {If we must use a verb clause, we should use get, not high-falutin' words like query. Unless we change the name of the intrinsic to QUERY_...} [320:bottom-9-10] Same table, entry for GET_COMMAND_ARGUMENT, "Query arguments from program invocation" ->"Get program invocation argument". {If we must use a verb...} [320:bottom-8] Same table, entry for GET_ENVIRONMENT_VARIABLE, "Query environment variable" ->"Get environment variable". {Ditto.} [320:bottom-3] Same table, entry for IACHAR, "Return ASCII code ..." -> "ASCII code ...". {Unnecessary verb.} [320:bottom-1-2] Same table, entry for IALL, "Reduce array with bitwise AND operation" -> "Reduce array by IAND function". {Shorter wording gives better typesetting.} [321:top+4-5] Same table, entry for IANY, "Reduce array with bitwise OR operation" -> "Reduce array by IOR function". {Shorter wording gives better typesetting.} [321:top+9] Same table, entry for ICHAR, "Return code ..." -> "Code ...". {Unnecessary verb.} [321:top+11] Same table, entry for IMAGE_INDEX, "Convert cosubscripts to image index" ->"Image index from cosubscripts". {Grammar: This does not "convert", it's value is the image index that those cosubscripts select, viz "from" those cosubscripts.} [321:top+12] Same table, entry for INDEX, "Search for a substring" ->"Character string search". {Noun phrase.} [321:top+16-17] Same table, entry for IPARITY, "with bitwise exclusive OR operation" ->"by IEOR function". {Shorter wording gives better typesetting.} [321:top+20] Same table, entry for IS_CONTIGUOUS, "Test contiguity of an array (5.3.7)" -> "Array contiguity test (5.3.7)". {Noun phrase.} [321:top+21] Same table, entry for IS_IOSTAT_END, "Test IOSTAT value for end-of-file" -> "IOSTAT value test for end-of-file". {Noun phrase.} [321:top+22] Same table, entry for IS_IOSTAT_EOR, "Test IOSTAT value for end-of-record" -> "IOSTAT value test for end-of-record". {Noun phrase.} [321:bottom-8] Same table, entry for MERGE, "Choose between two expression values" -> "Expression value selection". {Noun phrase. Also microscopically less misleading.} [322:top+18] Same table, entry for PACK, "Pack an array into a vector" ->"Array packed into a vector". {Noun phrase.} [322:top+20] Same table, entry for PARITY, "Reduce array with .NEQV. operation" -> "Array reduced by .NEQV. operator". {Noun phrase. Correct wording. Consistency.} [322:top+24] Same table, entry for PRESENT, "Query presence of ..." -> "Presence of ...". {Noun phrase.} [322:top+25] Same table, entry for PRODUCT, "Reduce array by multiplication" -> "Array reduced by multiplication". {Noun phrase.} [322:bottom-22] Same table, entry for REPEAT, "Repeatedly concatenate a string" ->"Repetitive string concatenation". {Noun phrase.} [322:bottom-20-21] Same table, entry for RESHAPE, "Construct an array of an arbitrary shape" -> "Arbitrary shape array construction". {Noun phrase.} [322:bottom-17] Same table, entry for SAME_TYPE_AS, "Query dynamic types for equality" ->"Dynamic type equality test". {Noun phrase.} [322:bottom-15-16] Same table, entry for SCALE, "Scale real number by a power of the base" ->"Real number scaled by radix power". {Noun phrase. Wording (radix). Typesetting (shorter).} [322:bottom-14] Same table, entry for SCAN, "Search for any one of a set of characters" ->"Character set membership search". {Noun phrase.} [322-bottom-12] Same table, entry for SELECTED_CHAR_KIND, "Select a character kind" -> "Character kind selection". {Noun phrase.} [322-bottom-10] Same table, entry for SELECTED_INT_KIND, "Select an integer kind" -> "Integer kind selection". {Noun phrase.} [322-bottom-8] Same table, entry for SELECTED_REAL_KIND, "Select a real kind" -> "Real kind selection". {Noun phrase.} [322-bottom-6] Same table, entry for SET_EXPONENT, "Set floating-point exponent" -> "Real value with specified exponent". {Noun phrase - this does not set the exponent in a REAL variable.} [323:top+7] Same table, entry for SPREAD, "Form higher-rank array by replication" -> "Value replicated in a new dimension". {Noun phrase.} [323:1+-3] Same table, entry for UNPACK, "Unpack a vector into an array" -> "Vector unpacked into an array". {Noun phrase. It does not unpack a vector into an array - the array is unchanged - it unpacks the vector to form a new array value.} [323:1+-2] Same table, entry for VERIFY, "Search for a character not in a given set" -> "Character set non-membership search". {Noun phrase.} [c13 entirety] Change "Description" paragraphs to match the new wording. [323:9] 13.5p5, "results returned from" -> "values assigned by". {These are subroutines, they don't "return" values.} [323:10+2] 13.5, Note 13.8, "returns" -> "assigns". {Ditto.} [325:7-8] 13.7.1 General, p2, "returned in a subroutine argument or function result" -> "assigned to a subroutine argument or returned by a function reference". {The correct verb for assignment is "assigned (to)". The correct noun for referencing a function is "function reference".} {NOTE: Large parts of 13.7.1p2 needs to be rewritten with extreme prejudice, but that is a horse of a different colour.} [339:17-18] 13.7.42 CPU_TIME, Argument paragraph, Replace last two sentences "It ... returned" with "It is an INTENT (OUT) argument. If the processor cannot provide a meaningful value for the time, it is assigned a processor-dependent negative value; otherwise it is assigned a processor-dependent approximation to the processor time in seconds." {Correct verb. Remove contradiction between the two sentences.} [341:6] 13.7.44 DATE_AND_TIME, Arguments paragraph, "returned in" -> "assigned to". {The correct verb for "assigned to" is "assigned to".} [348:9] 13.7.61 FINDLOC, paragraph 5 (Result Value), Case (i), "the $i^{th}$ subscript returned lies" -> "the $i^{th}$ element value is". {It doesn't "return" subscripts n times, its result is an array and this specifies the element values, see line 7. And subscripts don't "lie".} [347:13] Same paragraph, Case (ii) "the $i^{th}$ subscript returned lies" -> "the $i^{th}$ element value is". {Ditto.} [347:26-29] 13.7.61, paragraph (still in Result Value!), replace with "If DIM is not present, more than one element matches VALUE, and BACK is absent or present with the value false, the value returned indicates the first such element, taken in array element order. If DIM is not present and BACK is present with the value true, the value returned indicates the last such element, taken in array element order." {The original first sentence was entirely content-free. The sentences need conditionalising on DIM being absent otherwise they contradict the definition of the function; and the result when DIM is present should be entirely specified by Case (iii) anyway.} [351:22] 13.6.67 GET_ENVIRONMENT_VARIABLE, p3 (Arguments), TRIM_NAME, "returned" -> "assigned". {Correct verb.} [352:17] 13.7.70 IACHAR, p5 (Result Value), "A processor-dependent value is returned" -> "The value of the result is processor dependent". {This one is just stylistic.} [374:32] 13.7.123 NORM2, p4 (Result Characteristics), "$d_{\text{DIM-1}}$, $d_{\text{DIM+1}}$" ->$d_{\text{DIM}-1}$, $d_{\text{DIM}+1}$". {Correct typesetting.} [380:25] 13.7.136 RANDOM_SEED, p5 (within Arguments), "may be specified or returned" ->"can be retrieved or changed". {Incorrect use of "may". Incorrect use of "specified". And "returned". But "be" and "or" are used correctly.} [380:26] "returned by" -> "assigned to". {The correct verb for "assigned" is "assigned".} [380:27] "specified by" -> "of". {Variables have values, they don't specify them.} 3. Other returns There are various other uses of "return" that are merely poor style rather than of questionable correctness. This paper does not attempt to reword those. ===END===