ISO/IEC JTC 1/SC22/WG5 N1871 Changes to N1866 to create N1869 (the PDTR Ballot Draft) based on comments submitted with votes on the N1867 ballot. Bill Long 29 July 2011 This paper details the disposition of changes to N1866 proposed in comments make in N1867 ballot responses as well as additional edits needed to create N1869, the PDTR Ballot Draft for TR 20113. The paper is divided into these parts: 1) Global formatting changes. 2) Proposed changes that were accepted. 3) Proposed changes that were accepted with modification. 4) Proposed changes that were not accepted. Editorial commentary is appended to some changes, enclosed in { }. All of the items in Part 4 have such comments. The edit citations all refer to N1866. Within each of arts 2-4 the edits are listed in order by page:line number in N1866. Some ballot comments were general in nature, with no suggested edits. Unless the issue was already covered by a specific change from a different ballot, I did not attempt to address these general observations, and they are not mentioned in Part 4. Their omission should not be necessarily interpreted as indicating disagreement, but rather that they are out of scope for this paper. Part 1: Global formatting changes. ---------------------------------- 1. Modify /Title and /Subject fields. Changed to Title: Further Interoperability of Fortran with C Subject: TR 29113 Draft Author: JTC 1/SC22/WG5 2. Line numbers should be turned off. {Done.} 3. Paragraph numbers really don't work throughout clause 6. Either paragraph numbering could be turned off entirely for the whole document, or the following changes made: {Turned off para numbers.} 4. Page size should be A4. {Done.} 5. The Introduction is not supposed have a subtitle: after "Introduction", delete subtitle "Technical ... C". {Done.} Part 2: Proposed changes that were accepted. -------------------------------------------- [v:p6] Change "Procedure" to "Procedures". [1:1-2] Replace the title with "Information technology - Programming languages - Fortran - Further Interoperability of Fortran with C". I think that there should not be a trailing "-" (yes, the standard itself got that wrong!). Also please ensure more significant space between the title and "1 Overview", e.g. with \vspace{1cm} (blank line before and after that). You might need to push 1.4 off onto the next page to avoid a widow. {Ed: Unfortunately, the \vspace{} has no effect here, however inserting {~}\\ did work.} [1:20,23] Delete angle brackets around "dummy variable" twice, to get the definition into the form required by ISO (it is supposed to be a drop-in replacement, which for a noun is a noun phrase not an adjectival one). [1:23] The definition of assumed-type object is defective, as it makes CLASS(*) assumed-type. The only obvious safe fix is to replace it with "dummy variable declared with the TYPE(*) type specifier", unsatisfactory though that seems. [1:26] The definition of C descriptor is a bit too terse, I recommend "C structure of type CFI_cdesc_t". In fact it would probably be good to change most or maybe all of the "struct" usage in text to "C structure" (unless the letter C is absolutely positively definitely redundant and it cannot be misinterpreted even by a perverse reading). {Made additional changes in clause 5 and in the corresponding edit in clause 6.} [1:26+] in Note 1.1 change "an object" to "a Fortran object" {since the sentence ends "no exact analog in C".} [3:20+] NOTE 2.1 says "is passed as a simple pointer to the first address of the object" this is confusing and possibly wrong (C allows fat pointers UIUI). Anyway, a pointer *is* an address, it doesn't "point to" an address (unless it is a pointer to a pointer). And what is the "first address" of an object? Replace with "is intended to be passed as the C address of the object". Following that, change "there is insufficient" to "there would be insufficient". [4:15+] in Note 2.3 line 4 change "component" to "member". [7:12] Change "value" to "values". [9:9] Change "Arguments" to "Argument". [11:15-16] Force a line break before final "CFI_". [11:25] Before "CFI_" insert "with". [12:12] Change "equals" to "is equal to". [12:13] After "character type" insert " and kind". [12:14] Change "equals" to "is equal to". [12:16] Change the first "descriptor" to "C descriptor". [12:33] Change the first "descriptor" to "C descriptor". [12:34] Change the second "descriptor" to "C descriptor". [12:34] Change "shall be zero" to "is zero". {Overlooked edit. The user no longer sets the lower bound values for an assumed-shape array.} [12:40] Change "descriptor" to "C descriptor". [13:7+] In Note 5.3 change "descriptor" to "C descriptor" twice. [13:7+] In Note 5.3 add a ref after CFI_deallocate. [13:11+] In Note 5.4 change "descriptor" to "C descriptor". [16:19, 26, 28, 31] Insert "C" before "address". [17:8] Change "descriptor" to "C descriptor". [17:10] Change "descriptor" to "C descriptor". [17:11] Change "descriptor" to "C descriptor". [17:13] After "character type" add " and kind". [17:27] Add " = 0" after "dummy" to avoid undefined ref at line 30. [18:28], [21:30] Insert "and kind" after "scalar of the character type" [18:34] after "contiguous array" add "; if the attribute argument has the value CFI_attribute_pointer, the lower bounds of the object described by /dv/ are set to zero" [19:1+] in Note 5.7 change "the descriptor" to "a C descriptor". [19:1++] in Note 5.8 change "descriptor" to "C descriptor" twice. [19:1+++] in Note 5.9 change "descriptor" to "C descriptor". [19:16] Change "descriptor" to "C descriptor". [20:2+] In Note 5.10 change "or CFI_attribute_allocatable" to ", or which describes an allocated allocatable variable". [21:5] Change "source->dim[0].upper_bound" to "source->dim[0]lower_bound+source->dim[0].extent-1". {dim[] does not have an upper_bound member.} [22:2] Change "complex" to "_Complex". {Overlooked edit.} [22:9] Change "CFI_type_double_complex" to "CFI_type_double_Complex". [22:14] Insert "to" before "be". [22:20] Change "in same" to "the same". [22:35] Change "this" to "the same array". [23:4] Change "descriptor" to "C descriptor". [23:6+] in Note 5.11 change "descriptor" to "C descriptor" and the final "descriptors" to "C descriptors". [28:11] Insert "of" before "assumed type". [29:10] Change "Note that if" to "If". [29:30] Change "Note that if" to "If". [30:11] Change "Note that if" to "If". [31:11] Delete "two". [31:29] after "15.5.8" insert ", with the existing 15.5 to be renumbered 15.6 and its subclauses to be renumbered accordingly". Then, insert "Insert subclause 2.4.2 of this Technical Report at the very end of clause 15 where it will become 15.6.4.". [31:30] Delete [39:43] Change "descriptor" to "C descriptor" twice. [41:37] Change "descriptor" to "C descriptor" twice. Part 3: Proposed changes that were accepted with modification. -------------------------------------------------------------- [9:Table 5.3] Table 5.3 contains two error code macros, CFI_INVALID_EXTENT and CFI_INVALID_SM which appear to be superfluous because no arguments of type CFI_dim_t appear in the API any more. I therefore suggest to delete these two error codes, and correct the description of CFI_ERROR_OUT_OF_BOUNDS by replacing the text "A reference is out of bounds" by "A function argument is causing out-of-bounds references" Quite generally, the description of the error codes refers to the C descriptor instead of the function argument; this appears inappropriate or at least incomplete for some of them. {Agree with deleting CFI_INVALID_SM from the table since no function argument specifies sm values. Did not delete CFI_INVALID_EXTENT since extend values are arguments to CFI_establish and a user could specify invalid values (-100, for example). For elem_len, rank, type, attribute, and extent, I changed "value of" to "value supplied for" to reflect the focus on a bad argument being passed. Did not agree with "is causing out-of-bounds references" since that would, in fact, not happen, but rather the function returns an error without making the out-of-bounds reference. Decided to leave this on as is.} [13:7+] Looking at NOTE 5.3 I find I dislike it. It should, if present at all, rather point out what the general procedure on usage of the macro is. Here is a suggested replacement text: "NOTE 5.3 The CFI_CDESC_T macro is provided to support management of objects suitable for use in Fortran within C, in particular by providing the memory needed for the C descriptor itself. The address of an entity declared using the macro is not usable as an actual argument corresponding to a formal parameter of type *CFI_cdesc_t without an explicit cast." {Instead, I shortened the first replacement sentence, and then changed the beginning of the existing text from "The following code" to "For example, the following code".} [16:7] Change "this subclause" to "5.3.5". {Follow the form at [16:11].} [16:21,22] After "allocatable" and "pointer" respectively, add "variable". {Added "variable" only after allocatable, but not after pointer. Pointers are associated, not pointer variables.} [20:2+] In Note 5.10 change "or CFI_attribute_allocatable" to ", or which describes an allocated allocatable variable". {Changed the last word to "array" since allocatable scalars are allowed.} [25:4] Instead of removing the blank before the full stop, changed "{}" in the LaTex source to "\{\}" so the braces actually display. [28:8+] Insert new edit delimited by horizontal line "{Replace paragraph 2 of 12.4.3.4.5 with}" and then the contents from [12:12-15] of the TR, not including NOTE 2.3. {Ed: I assume the instructions should have been to use the contents of [4:12-15].} [34:22,24] It seems inappropriate to introduce paragraphs 6 and 7 at all in the places they are now. Suggestion: keep the whole section in para 5, and have para 6 start at [34:25]. {This is a quirk of the automatic paragraph numbering scheme. I agree it is odd to start a "paragraph" in the middle of a sentence. These are really more like block numbers than paragraph numbers. Solved by turning para numbers off.} Part 4: Proposed changes that were not accepted. ------------------------------------------------ [4:4] Make "An assumed-rank object may have the CONTIGUOUS attribute." a Note. {Not changed - the objects that are allowed to have the CONTIGUOUS attribute are spelled out in the base standard in normative text. This sentence modifies that set of objects. See edits at [26:32-33].} [4:17-18] Delete "The ALLOCATABLE, OPTIONAL, and POINTER attributes may be specified for a dummy argument in a procedure interface that has the BIND attribute." {Not changed - this sentence states a core feature of the TR - see [v:p4]. It provides an explanation of the otherwise cryptic constraint changes that follow.} [9:3], [16:11], [16:13], [16:14] add "subclause" before a subclause number in a cross reference. {These edits are contrary to the ISO rules for references - see 6.6.7 of the ISO guidelines.} [12:40] Replace "In a descriptor ... array" by "In a C descriptor whose attribute member has the value CFI_attribute_unknown_size," {Not changed: The current text is the same structure as [12:33-35] and avoids the forward reference to the attribute code.} [16:5] Replace "accessed" by "referenced". {In [16:4] we are using "modified" instead of "defined", to the pattern here is to use English words rather than defined terms. Should be consistent. Opted to not make a change.} [16:30+] A note would be illuminating: "NOTE 5.6a This is equivalent to the Fortran statement ALLOCATE (A(100,100), STAT=IND ) " {I assume A(100,1000). But even then, the could be read to imply that the IND returned by stat= and the function error codes have the same values. Since this suggestion is not correcting an error in the draft, opting to not make the edit.} [18:10+] A note would be illuminating: "NOTE 5.6a This is equivalent to the Fortran statement DEALLOCATE ( A, STAT=IND ) " {Not changed - same argument as for [16:30+].} [18:19], [21:24-5] Replace "base" by "C" or insert "C" before "base". {Not changed - what we mean by "base address" is more complicated; see the text at [12:9-11].} [20:14, 18, 24] Insert either "Fortran" or "C" before "subscripts" ([21:5] suggests "C"). {Subscripts are always relative to the stated lower bounds if the lower bounds are specified, and may be ordered in the Fortran order or the C order as indicated. In this case, the subscript is relative to the already specified lower bound in the source descriptor, so there is no Fortran or C issue involved. Later the sentence explicitly says the order is the Fortran order. So I do not see any ambiguity, and the proposed change could add confusion.} [20:17, 21, 25] Replace "be" by "not be less than" or "be greater than or equal to". {It seems simpler in this context to require that the lower and upper bounds arrays have the right size. I agree with the point that this is not consistent with CFI_allocate and CFI_address, but an equally compelling argument could be made for changing those instead. Need committee input on this issue.} [22:23] Insert "Fortran subscripts for the" or "C subscripts for the" before "lower bounds". {Similar to [20:14], we are setting the lower bounds here. Whether a default value for a lower bound is a Fortran (1) or a C (0) thing is a meaningful distinction. When we are specifying the value of the lower bound, future subscripts are relative to that lower bound value. This is not a C versus Fortran issue.} [22:41], [23:12], [23:14], [27:29] relate to whether "call" is a good term to use in the C context. {Searching the C standard for "call" gets hits on 198 pages. An example is the first sentence in 7.20.3. "The order and contiguity of storage allocated by successive calls to the calloc, malloc, and realloc functions is unspecified." No changes made.} [26:2] Does this need a caveat concerning RANK, or does 1539-1:2010:1.6.1p1 cover it? {This paragraph is a clone of 1.6.2 in the base standard. This is a discussion for the base standard, not the TR.} [26:15] Replace "intrinsic and" by "intrinsic or". {This text is a copy of the text at [3:16] and should be consistent.} [28:5-6] It is also a characteristic that these rank, shape, size, type, or type parameters are not assumed. The sentence ought to be "Whether a rank, shape, size, type, or type parameter is assumed or deferred is a characteristic." {Clause 6 lists the "required" changes to F08. The proposed change is intended to correct a bug in the base standard and is out of scope here.}