J3/14-166 To: J3/WG5 From: Malcolm Cohen Subject: Editor's report for 14-007r1/N2014 Date: 2014 June 02 1. Introduction I edited 14-007r1 with a pretty heavy hand. Some matters deserve review. 2. Edits not associated with any paper - Removed the ISO-sounding PDF disclaimer from the frontmatter. - In COMMAND_ARGUMENT_COUNT, changed result characteristics from "Scalar default integer" (only used here) to "Default integer scalar" (used 14 other places). - Changed all the "may" in the Introduction to "can". The Introduction is not allowed to contain any requirements. 3. New j3 LaTeX macros (for information) New j3 LaTeX commands \defkw/\defkw* and \refkw/\refkw*, these act like \mindexd/\mindexd* and \mindex/\mindex*, but with added hyperlinking. Note not like \kwd and \kw* because for some reason \kwd does not embolden the index entry. Additional LaTeX commands are \linkkw to hyperlink without indexing, \defkwd, \refkwd and \linkkwd for "duplicate" keywords e.g. ONLY which is defined for 2 statements, USE and IMPORT. Note: We ought to change our pre-existing keywords to use these new commands so that they get hyperlinked too. Macros \inputstmt{} and \outputstmt{}; these produce the words "input statement" and "output statement" respectively, and index as "data transfer statement". Having as macros not only makes it easier to get consistent, it makes it easy to change the terminology (or the indexing) later if we don't like the results of this. 4. Papers incorporated into 14-007r1 14-106r1 There were no edits in this paper. 14-108r1 Done. 14-114r1 Done; UTI002 deleted. 14-115r2 Done with changes: "shall be a designator" -> "shall be a \si{designator}", (since we are requiring it to have a particular syntax, using the syntax term seems most appropriate). UTI001 deleted. COMMENT: I also think I would have preferred "(R737) The " -> "An that is a ", but I did not make that change. 14-117r2 Section 4 done with changes: [179:28] should have been [179:18]. [179:18] sorry guys, but there is no such thing as an allocation status of "deallocated"; it is "unallocated". See 2.4.9. My wording retained. [211:36-38] Dehyphenated "processor dependent" (we don't hyphenate this term when used in this position in a sentence). [232:15-16] I forgot to include an edit to address my comment: Also "may" should be one of "do", "can", or "might", depending on whether we want to express actuality, capability, or possibility. 14-120r1 Did not index/hyperlink within examples. Indexed as definition as follows: ASSIGNMENT definition is . ONLY definition is USE ONLY, duplicate definition is IMPORT ONLY. OPERATOR definition is . PASS is already indexed as the PASS attribute; I did some indexing under the PASS attribute (it only appears outside of examples in c04 anyway). Indexed NOPASS attribute as "see PASS attribute". Hyperlinked NOPASS keywords (in constraints etc.) to the PASS attribute. Many attribute definitions did not use \defattr (which makes the occurrence a definition), just \label; changed them all to \defattr. ADDITIONAL EDITS arising from 14-120r1: Deleted keyword-indexing of "INCLUDE", which resulted in INCLUDE being indexed twice (I mean as two separate items) plus "INCLUDE line" being indexed. Left just the "INCLUDE line" index entry (indexed as a keyword so I could hyperlink it easily). BIND(C) was only indexed in two places, nearly everywhere it was indexed as the BIND attribute (which is correct). Deleted indexing of BIND(C), replacing with "BIND(C) see BIND attribute", and changed those occurrences to index the BIND attribute instead (as they should have done in the first place). NOTE: One "BIND(C) attribute" item was missed, will fix next time. Indexed STAT= as a proper specifier instead of as a keyword + kludges. (Still a bit kludgy since there are two places where STAT= is defined; perhaps the c08 one could be merged into the c06 one? Maybe not.) Indexed ERRMSG= as a proper specifier. Fixed some specifier indexing glitches (as "statement!specifier="). Indexed IOMSG= as a proper specifier. Improved indexing of ADVANCE=. Indexed ASYNCHRONOUS= as a proper specifier. Indexed BLANK= as a proper specifier. Indexed DECIMAL= as a proper specifier. Did additional indexing of DELIM= occurrences. Indexed ENCODING= as a proper specifier. Indexed FMT=. Indexed FORM=. Indexed RECL=. Indexed ROUND=. Improved indexing of PAD=. Indexed SIGN=. J3 ACTION: Review keyword indexing; if any seem to be non-useful, they can be changed to hyperlink without indexing (\linkkw vs. \refkw). COMMENT: More specifiers could be properly indexed, e.g. SOURCE=. Also, type specifiers (INTEGER, CLASS(*), DOUBLE PRECISION) are not indexed. Perhaps index as e.g. "DOUBLE PRECISION type specifier"? 14-121r1 Done with changes: [201:6] Did at [201:4] instead, i.e. immediately after the other two sentences talking about what statements are permitted to refer to what file kinds. Also inserted "input/output" in front of "statement" for consistency with the first sentence. [207:21-22] changed first "may", second one was changed "also may" -> "are also permitted to" instead (grammar). [207:22] Inserted "input/output" before "statement". [208:27] Indexed "wait operation" and "asynchronous input/output". [213:1] Also inserted a comma before "is permitted", to aid readability. LATER EDITOR ACTION: Did not add UTIs for the (worthy) issues raised in section 3 of 14-121r1, instead there will be a paper for action at the next meeting. 14-122 Done with changes: [c13-c15] Also changed C_NULL_PTR to use defkw-refkw (to get hyperlinking from the mention in 15.2.1 to the defining subclause). C_NULL_FUNPTR ditto. Yes it's only a page later, but still. Got carried away and properly hyperlinked and indexed C_PTR and C_FUNPTR (these had partial linking/indexing before). [313:29-31] Can I just say that with all the hyperlinking, indexing and typesetting commands in the LaTeX source, it is a little counterproductive to tell me to change one huge sentence (5 lines long) to another very similar sentence (in fact the first half was identical, and all the words in the second half were already there); either I have to work out the actual textual changes, or re-hyperlink/index/typeset afterwards. Anyway, the sentence this edit would have made was still problematic: - a "name" cannot be a "dummy argument", so at the very least the current wording needs "name of a" inserted between "is also a" and "dummy argument"; - consider SF(X)=ABS(A=X); ENTRY E(A); obviously A "appears" in the expression of the statement function, but is not referring to the dummy argument; I would not want to take this too far, but the current wording does seem a bit hard to interpret. Possible rewrites: (1) Similar wording to sentence 2 of this paragraph: "A dummy argument specified by a \si{dummy-arg} in an ENTRY statement shall not appear in the expression of a statement function that precedes the first \si{dummy-arg} with that name." (2) Completely new wording: "In a subprogram, a statement function shall not refer to a dummy argument of a procedure defined by an ENTRY statement unless the name of that dummy argument appears in a preceding FUNCTION, SUBROUTINE, or ENTRY statement." (3) Combining, and using the first part of the first sentence in p7, "In a subprogram, a dummy argument specified in an ENTRY statement shall not appear in the expression of a statement function that precedes the first \si{dummy-arg} with that name in the subprogram." I went with version (3); this is shorter than the one in 14-122 and seems less problematic. [328:4-6] Why not just say to insert ", or in many other situations"? Anyway, that is what I did. [328:6+] Rejected. With "many other" added, the list is no longer misleading. If someone wants to make it longer (me, I'd delete everything except the "actual argument" limitation and not even attempt to make it comprehensive - someone who wants to know can probably just search for "Table 13.3", no? Repeating that info here is not notably future-proof. [448] Rejected. No technical issue has been exposed. Since I can no longer remember what I thought the problem might have been, and no-one else could see a problem, the conclusion must be that I was mistaken and there is no problem. [35:21+] "Termination of Execution" -> "Termination of execution". ADDITIONAL: Changed several refs to "Execution sequence" to here, e.g. for error termination, in c06, c08, c09 and c13 (a few still refer to "Execution sequence"). [178:22] Also removed redundant unnecessary BNF refs on C817 and C818. ALSO: The hyperlinking of "named constants" in places was not including the "s" in the hyperlink which looked strange, fixed. (Used \termupl instead of \termu with appended 's'.) 14-123r2 REJECTED. Editor declines to insert a UTI. If there are "deeper problems", it is probably an interp. Actually I don't think there are deeper problems anyway, i.e. the text is fine (if clunky) as is. The final paragraph of the UTI is asking about what happens with a non-conforming program. This is not UTI material, this is "the paper ignored my email message pointing out the existing text in the standard that said this was not allowed". 14-124 REJECTED. This is an interp or nothing. It's not a UTI. The previously-existing text was not apparently causing problems, even after the (broken) fixup from the unnecessary interp it is still, as far as we know, not causing problems. If problems are being caused, it is an interp. If problems are not being caused, fixing it does not rise to the level of a UTI. Suggestions for editorial improvement will be considered on their merits. 14-125r1 REJECTED. This is an interp or nothing. It looks like nothing. 14-126r1 REJECTED. This is text resulting from an interp, it is therefore far from clear that the interp process is not the appropriate process for resolving this issue. Furthermore, there does not appear to be any confusion about what we really mean (even though it seems we don't know how to say it). Consideration will be given to editorial fixes; if none are forthcoming, perhaps we should reconsider whether to use the interp process to resolve issues created by the interp process. 14-127 Seems to have already been done in some other paper. 14-129r1 Done with changes: [31:23,43] Also moved to the end of their rules, because we did that for computed GOTO. Actually we did not do that consistently, so I moved a few other obsolescent things to the ends of their rules. I hope I moved them to the ends of the right rules... [141:7] This sentence is bad - it directly contradicts both the previous ones. And for WHERE and FORALL there is no "statement that is conditionally executed", the contained statement is unconditionally executed with a mask! Completely rewrote the whole paragraph from scratch to avoid contradictions and make sense. Used "subsidiary" to describe the "contained" statement ("contained" works perfectly well in the normal English sense, but maybe subsidiary is better for avoiding confusion between this situation and the CONTAINS statement). J3 ACTION: Review new wording for correctness. [166:31-167:4] moved to immediate precede the BNF for do-block instead. ACTION FOR SOMEONE: There is no longer any need for do-block and the "range of the DO" subclause. Propose its deletion. [167:17-26] Did not "replace", I moved the text to c08 before inserting the new text. Moved lines 27-28 along with the rest. [167:30-167:2+] Moved instead of simply replacing it. [166:8-170:16] Deleted NOTE 7.52 instead of obs-fonting it, as we don't usually have examples of obsolescent features. Replaced NOTE 7.54 with a single explanatory sentence. Deleted NOTEs 7.55-7.57 ditto. NOTE: If we really want some of these examples, which I sincerely doubt, they can be buried in Annex C. Along with the bodies. [317:1-] The edit instruction seemed a bit garbled, but I think I did the right thing. Note this sentence uses "such as", so we explicitly disavow completeness. ADDITIONAL EDIT: NOTE 12.54, obs-fonted "and to allow ... assignments". [448ish] Since some of these edits were breaking up "FORALL and DO CONCURRENT constructs" into "FORALL constructs and DO CONCURRENT constructs", I broke up some more of them. And ordered them so that DO CONCURRENT comes first i.e. the obsolescent things are the afterthought, not the non-obsolescent thing. J3 ACTION: Review. [472:26+] "statements and constructs" -> "construct and statement". [474:20+] "loop" -> "construct". [488:32-492:1] Deleted these instead of obs-fonting them. We do not need Annex C detailed explanations of obsolescent stuff. 14-117r2 Section 5 (terminology change). "input/output statement" when only meaning data transfer -> "data transfer statement" "data transfer input statement", "READ statement" -> "input statement" "data transfer output statement" -> "output statement" "data transfer input/output statement" -> "data transfer statement" Plus "input statement" index as "data transfer statement" and "output statement" index as "data transfer statement" plus index entry for "input statement" says "see data transfer statement" and similarly for "output statement". Note: left alone "[non]advancing input/output statement", "[un]formatted input/output statement", "list-directed input/output statement", "namelist input/output statement". But: We already (mostly) used "[non]child data transfer statement" and "[a]synchronous data transfer statement". Did change "direct access" and "sequential access"... "namelist formatted data transfer statement" -> "namelist data transfer statement". "namelist formatted data transfer input statement" -> "namelist input statement". Left alone "When a parent XYZ is active," paras, as they need more careful tweaking (are they correct as is? They look dubious). For IOSTAT_EOR and IOSTAT_END, "input/output" -> "input". N1942. Done with many many changes. 9.2 Did different edits to the Introduction: we don't need any advertising-speak, and we are a standard not the TS. Also changed "dummy variable" to "dummy data object" throughout. COMMENT: I hyperlinked "character length" to "length type parameter" but perhaps it should be linked to CHARACTER type (4.4.3)? 9.3 "assumed rank" and "assumed type" - I dislike the practice of randomly hyphenating and not hyphenating a term (e.g. "assumed type" and "assumed-type"). This leads to endless confusion and griping. Only the adjectival form is needed, we can say "is assumed-type" instead of "has assumed type" or "is of assumed type". 9.3 Proposed term definition of "assumed rank" is defectively worded; assumed-rank dummies also assume the shape and size. It is nearly universally used hyphenated, but is defined without. Instead, defined "assumed-rank dummy data object". 9.3 Proposed term definition of "assumed type" is defectively worded; either it should describe the syntax or semantics, but not syntax with partial semantics linked with "therefore". The semantics are approximately "unlimited polymorphic without the ability to do type query" the syntax is "declared with a of TYPE(*)" or, avoiding the parens at the end (confusing with refs), "declared with a TYPE(*) " or "declared with a TYPE(*) type specifier" Perhaps "unlimited polymorphic object declared with ... TYPE(*)" might be ok, but it might be a bit confusing so I've gone for the syntax-only version since that is completely definitive. Omitted the unnecessary term qualification (). 9.3 "C descriptor": if ISO_Fortran_binding.h is a "header", then it must be #included as , the form #include "ISO_Fortran_binding.h" includes a source file. That's according to the C standard. All our examples use quotes. Therefore, "header" -> "source file". Perhaps 15.4 C descriptors should be a subclause of 15.5, but since it is not, I added it to the cross-references. 9.3 Omitted the 1.6.1a insertion as it is done correctly already. 9.4 "are of assumed type" -> "are assumed-type". "has assumed type" -> "is assumed-type". "associated effective" -> "effective". Deleted "(4.3.1.3)" since it is the very next subclause. "variable" -> "data object". Added Oxford comma between "POINTER" and "or VALUE". Deleted "any of". Split the intrinsic functions away from C_LOC, added text to say which intrinsic module it came from (not a nonstandard one), using our macros for consistent wording & hyperlinking. 9.5 Omitted the first reference to 15.6.4 because we don't want a reference in this sentence. The second one (just 3 lines down) is where the reference belongs, left that one there. C530 "have assumed rank" -> "an assumed-rank dummy data object". 5.3.7p1 I note that this is copying the previous (defective) wording for assumed-shape. "or that an assumed-rank dummy data object is contiguous". This is a TECHNICAL CHANGE, but since the old wording is copying the mistake in F2008 ... either assumed-rank should act the same as we intended or we need a UTI. J3 ACTION: Confirm or deny technical change. Note that with assumed-rank either the actual is contiguous (and we therefore need make no copy and thus need not to know the size), or the shape and size of the actual are known (and therefore we can make a contiguous copy, just like the assumed-shape case). p2 item (3); instead, inserted new item \item an \termii{assumed-rank}{dummy data object} whose \termi{effective argument} is contiguous, 5.3.8.1p1 "has assumed rank or is" -> "is assumed-rank or". "entity" -> "dummy data object", "rank and shape" -> "rank, shape and size", "associated actual" -> "effective". (have to assume the size if we are to handle assumed-size actual arguments). 5.3.8.7 "dummy variable" -> "dummy data object", (twice), "rank may be zero" -> "rank can be zero" (capability not permission), "corresponding to" -> "that corresponds to" (grammar), "the argument" -> "the dummy argument" (we're still in the "corresponds to" clause, right? if not we are in a big can of worms...), "the C_LOC function in the ISO_C_BINDING intrinsic module" ->"the function C_LOC from the intrinsic module ISO_C_BINDING (15.2.3.6)" (consistency, and I think the ref is a good idea), "the first argument in a reference to" -> "the first dummy argument of" (we HAVE to be talking about dummy, in which case reference is nonsense), "corresponding" -> "that corresponds" (again), 6.7.3.2p6 "When" -> "If" (either both sentences should be When or both should be If ... I think "If" is fine), "reference of" -> "reference to" (grammar). 12.3.2.2 I think we don't really need to insert "(unless it is assumed-rank)", but it also does not hurt, so I did it. 12.4.2.2 inserted before (2)(c) instead, since assumed-rank is more like assumed-shape than like coarrayness. "has assumed rank" -> "is assumed-rank". 12.4.3.4.5 Insert grumble about "replace whole paragraph" for an edit that looks like inserting a few words at the end. COMMENT: This text is perversely misreadable. Would welcome suggestions for improvement, but if none forthcoming, ok as is I think. 12.5.2.4p2 "of assumed type" -> "assumed-type". 12.5.2.4p3 Edit is WRONG since this would make the scalar case of actual length > dummy length non-conforming! Instead, "not assumed shape" -> "not assumed-shape or assumed-rank". 12.5.2.4p4 This one would be ok, but I did the same edit as p3 anyway for consistency. 12.5.2.4p9 Apart from being ugly the text is wrong since it is missing the "not CONTIGUOUS attribute" condition on assumed-rank; Instead, "is a scalar or an assumed-shape array that does not have the CONTIGUOUS attribute" -> "is scalar, assumed-rank, or assumed-shape, and does not have the CONTIGUOUS attribute" COMMENT: Making this 2-item list into a 3-item one has made this ugly paragraph even worse. In fact it is really terrible. Why did we ever agree to permitting this? 12.5.2.4p10 Did not insert "that is associated with an array actual argument", since then assumed-rank CONTIGUOUS that is associated with a scalar actual argument would not be standard-conforming for the purposes of this paragraph. 12.5.2.4p14+ "assumed size" -> "assumed-size". C1239 Text to be replaced does not exist and has never existed!!! Did something anyway. ACTION: Interop subgroup should check what they intended and check 14-007r1 to see whether it has been achieved. C1240 "assumed-rank array" -> "assumed-rank entity". COMMENT: I think that "without CONTIGUOUS" should apply to the array pointer case too... it is certainly non-conforming otherwise... ...but that is a horse of a different colour. 12.5.2.13p1(3,4)b The replacement text is wrong (dummy args are not associated with actual args) and it would make the overly-complicated sentence even worse. Rewrote entire item(s) from scratch. C1255 et al. Deleted the unnecessary and confusing refs to R1230. "each dummy argument" -> "each of its dummy arguments" (otherwise what are we talking about) hyphenated assumed-shape and assumed-rank and assumed-type; "of assumed character length" ->"of type CHARACTER with assumed length"; "or has the ..." -> "or that has the ..." (still ugh, but marginally easier to read). Split off the function result into a separate constraint. C1255a "A dummy" -> "A variable that is a dummy" (just for consistency with C1255b) C1255b "of interoperable type of assumed type" ->"assumed-type or of interoperable type". COMMENT: These constraints are a mess. The assumed-type in C1255 is only necessary because of the type requirements on "interoperable", but the type requirements are applied to all the other items in the list by C1255b. I think these could be refactored to make them easier to follow. 13.7.86p3 "an array or an assumed-rank object" ->"assumed-rank or an array". 13.7.90p3 "an array or assumed-rank object of any type" ->"assumed-rank or an array" (It is problematic to append "any type" since that could be misleading as to only the assumed-rank object [or only the array] can be of "any type" and that there is some prescription somewhere. Since "of any type" conveys no information, delete it.) Actually on reflection, "of any type" could be perversely misread as prohibiting CLASS(*) and TYPE(*) which don't have any declared type! So deleting it sounds good anyway. Inserted the note at the end of the subclause where it belongs, not in the middle of the specification. "an assumed-rank object of rank zero" ->"assumed-rank and has rank zero", appended "since it cannot satisfy the requirement 1<=DIM<=0" (otherwise problematic since the prohibition against DIM being present is not explicit). 13.7.137a "The result is" -> "The value of the result is". I was going to do "declared with" -> "declared by the statement", typeset the statement on a separate line, etc etc, but (a) NOTHING is "argument associated with an actual argument", (b) we don't need all these statements, therefore reworded the whole thing from scratch. COMMENT: "of any type" in the argument para is unnecessary. 13.7.149 SHAPE: It is not really acceptable to drop a blob of Fortran code and say that this is the definition, especially one which uses unbound variables. Rewrote. 13.7.156p3 "an array or assumed-rank object of any type" ->"assumed-rank or an array". Did not insert a Note into the middle of the definition but at the end of the subclause. Reworded the note. ditto p5 Again, a Fortran blob with an unbound variable; and I don't think we have ever done array constructors in definitions before. Also, the existing words are easier to understand so I retained them except for the irregular assumed-size case where I gave up trying to describe this monstrosity and inserted a (simple) blob. UBOUND: similar changes to LBOUND except that the Result Value subclause was completely rewritten (because the text had already changed substantially by other edits to the standard). COMMENT: That 1<=DIM<=0 means DIM cannot be present is not such an interesting observation that we need to say it 3 times! In my opinion, not saying it at all would be fine. Or maybe just once in 13.2.1. 15.1 Too many with's: second "with" -> "that has". Moved "dummy data object" to the beginning, and reordered so it ends with "or is of type character with an assumed length", "requirements" -> "requirement" (number disagreement!) COMMENT: Why do the procedures in c15 not have proper examples like the ones in c13 and c14? We should improve that sometime. COMMENT New text in 15.2.3.3 says "If the value of CPTR is the C address of a storage sequence, FPTR becomes associated with that storage sequence." One might very well ask whether this is a C storage sequence or a Fortran storage sequence. Perhaps this should be worded more appropriately (C address of a C object?). But more seriously, if CPTR is the C address of a C storage sequence such as float[100], and FPTR is REAL(C_FLOAT),POINTER scalar, surely FPTR is only associated with float[0] not the entire 100 elements. Otherwise when FPTR becomes undefined, all associated entities become undefined and that would be ludicrous. 15.2.3.5 Rewrote arg X desc to simplify it. COMMENT: The 15.3.2 and 15.2.3.5 edits were out of order. I don't think I applied any edits to the wrong place though. 15.2.3.4 "or the result" -> ", or the result". "to C_FUNLOC with a noninteroperable argument" ->"to the function C_FUNLOC the intrinsic module ISO_C_BINDING" (even though we are describing ISO_C_BINDING, we're not inside the C_FUNLOC definition so we need to say which one we mean); ("with a noninteroperable argument" does not seem to be doing any work here i.e. it looks completely unnecessary). ". Otherwise" -> "; otherwise" (better structure). 15.3.7 "with assumed length" -> "with assumed character length", "and corresponds to a formal parameter of the prototype that is" ->"and the formal parameter is" (throughout the insertion), used a bullet list rather than an enumerated one 15.3.7 end... this goes before the notes and examples, not after. COMMENT: These notes and examples need more work. They might not be actually broken, but they could use improvement. "the corresponding formal parameter is interpreted as the address of a C descriptor for" is meaningless. In fact this whole paragraph is without meaning because e.g. the attribute member IN THE PROTOTYPE does not and can not have any value whatsoever. UTI 004. I really did not want to do this, but this needs a complete rewrite. UTI 005. An effective argument is not ever "an address". UTI 006. Probably could have rewritten this to mean what I think it is trying to say, but since I've already given up on the previous two paragraphs and am short of time, I'll just put in another UTI. Sorry. COMMENT: Should CFI_cdesc_t be in code font? We code-font C keywords... so "int" and "void *" are code font, and the TS has code-fonted member names but usually not the typedef names. That does not look very consistent to me. Not a big deal though? Insert 8.2: Put CFI_cdesc_t into code font. Indexed CFI_cdesc_t and ISO_Fortran_binding.h. "defined in the file" -> "defined in the source file" for consistency with the definition. Macros don't "specify type codes", they have a value which is that of a type code, and IIUC this specifies a type. Changed table title to "ISO_Fortran_binding.h macros for type codes". COMMENT: The inserted text has a lot of usage of "specify" that should be "is" and "type" that should be "type code", and "is" that should be "specify". I tried to fix the most obvious misstatements, but this really needs more thorough review. ACTION: Someone (/EDIT?) needs to review the wording throughout this inserted text and suggest improvements. COMMENT: I think that the section "C descriptors" should probably be a subsection of the ISO_Fortran_binding.h section; it seems very short and trivial to appear this high in the subclause hierarchy. Subclause entitled "ISO_Fortran_binding.h": Changed subclause title by inserting "The source file" in front. "Summary of contents": "ISO_Fortran_binding.h header file" -> "source file ..." (for consistency with ourselves and the C standard). "interpret a C descriptor and allocate and ..." ->"intepret and manipulate a C descriptor". (this is all just waffle anyway, but now more grammatical). Also, "typedef definitions"->"typedef declarations" (that is what C calls them). UTI 009: "shall contain" ... ", macro definitions that expand to integer constants, " ... with no indication as to what macro definitions we are talking about, so this requires actually nothing (if zero is accepted as plural) or maybe it is satisfied entirely by #define CFI_ONE 1 #define CFI_TWO 2 Who knows. COMMENT: "These provide a means" ... how many times do we have to say it? This is more advertising than normative! We already said it normatively 3 subclauses ago... copied the wording I used earlier so at least it's the same. But we ought not to be saying it again... Several places insert "The source file" before "ISO_Fortran...". After "CFI_dim_t is a", "named C structure type defined by a typedef" ->"typedef name for a C structure". (use correct C terminology). COMMENT: "All names ... defined in the header begin with ..." Well that is a nice pious hope. Did someone intend to make a requirement? (Yes, this really should be a UTI, or maybe I should have just gone ahead and inserted "shall", but I only noticed on the proofread. Anyway, I'd want to reword entirely due to the "or are defined by a standard C header" bit... and is the processor really free to include *ALL* standard C headers into ISO_Fortran_binding.h? Sounds a bit OTT...) ACTION: Someone should review what is supposed to be a requirement (shall), what is a consequence of some other requirement (statement of fact ok here, but might warrant explanation if not a trivial consequence), and what is merely a pious hope (delete). COMMENT: There were a lot of hardcoded subclause numbers in the LaTeX source of the TS, instead of \label and \ref, I *think* I spotted all of them but... "number of elements along" -> "number of elements in". "the value -1" -> (maths format)"-1" ("the value is equal to the value" is singleplus ungood). "memory stride for a dimension. The value is" ->"memory stride for a dimension; this is" ("The value is... The value is..." in successive sentences ++ug). "distances ... beginnings of" -> "differences ... addresses of". Another "along" -> "in". After "CFI_cdesc_t", "named C structure type defined by a typedef" ->"typedef name for a C structure". (use correct C terminology). ", containing" -> ", which contains" "the list following this paragraph" -> "this subclause". (+++ug) "the following properties" ->"the properties described in this subclause". (This sentence not, in fact, being followed by any plausible description of any properties.) ", with the other members after version and before dim in any order" ->". All other members shall be between version and dim, in any order." COMMENT: All these subclause names are a bit ugly, perhaps "The type CFI_dim_t" et al would be better... Deleted reference "(6.5.3.2 of \Fortranstandard{})". (No reference is needed anyway IMO.) COMMENT: "...that defined the format and meaning..." ++UG. ACTION: Someone should suggest an improvement to this ++UG text. ". If the object is a scalar, the value is zero" ->"; if the object is scalar, the value is zero". COMMENT: All the usage of "type specifier" is wrong. Left unfixed. ACTION: This needs to be reviewed and fixed, probably together with the "specify" vs. "is" review mention above. "nor components that have the ALLOCATABLE or POINTER attributes" ->"allocatable components, or pointer components," Deleted "or correspond to CFI_type_other". COMMENT: This sentence is a nonportable mess. "The specifiers for two intrinsic types can have the same value." ...has problems, (1) CFI_type_int and CFI_type_int32 are the same Fortran type not different ones (and we must be talking about Fortran types since "intrinsic"). Secondly, whatever something it is talking about should be "different" somethings not "two" somethings. And these are macros not specifiers in the usual sense of the word... ->"The values for different C types can be the same; for ..." ACTION: Did I get this to make sense? Is it right? Check... "Error conditions other than those listed in this subclause should be indicated by [different] error codes ..." Even though "should" is in accordance with the ISO guidelines, I felt it was more obvious as "It is recommended that ...", so that is what I inserted. "The error codes that indicate the following error conditions are named by the associated macro name." is ++UG. Changed to "The values of the macros in Table x.y indicate the error condition described." and changed the "Error" heading in the table to "Error condition". ... Functions / General / p1 ... and now we have Yet Another Advertisement for the facilities. This really is too much. Deleted p1. The subclause "Functions" is somewhat uninformative, so I renamed it to "Functions declared in ISO_Fortran_binding.h" and "General"->"Arguments and results of the functions". Similarly renamed "Macros ...", COMMENT: ...actually, I see "Macros and typedefs" is badly named, since it does not include CFI_dim_t nor CFI_cdesc_t. Perhaps this should be "Other macros and typedefs in ISO_Fortran_binding.h"? ACTION: Review subclause headings, especially this one which probably should have "Macros"->"Other macros". "A list .. is supplied in 8.3.4." ->"Table x.y lists standard error conditions and macro names for their corresponding error codes." (8.3.4 as was lists a lot more than that!) COMMENT: "A processor is permitted to detect other error conditions." This processor dependency is not described in Annex A. ACTION: Add this processor dependency to Annex A. "the following subclauses of 8.3.5" -> "8.3.5" (there is in fact no list of subclauses of 8.3.5 following this statement). COMMENT: CFI_ERROR_OUT_OF_BOUNDS. What does "A reference is out of bounds" actually mean? (Yes this should have been a UTI...). ACTION: Please reword so that someone can understand it, or explain to me what it is supposed to mean so I can try to reword it. CFI_address, Description, "Compute the C address of ..." -> "C address of ..." (this is a function not a subroutine). ..., Formal Parameters, "a subscripts array" -> "an array of subscript values". but this whole description is wrong - there are few requirements, mostly pious statements of hope. Rewrote as requirements! COMMENT: The text seems to want to disallow a pointer to a scalar of CFI_index_t (when subscripting a vector), that seems rather un-C-like but I left it as is. Contradictory (normative) "is ignored" vs. (informative) "may be a null pointer or a valid pointer value". I guessed that the informative text better reflected the intent of the TS; and it is forbidden to give permission in a note so the informative text has to be deleted (did that), and inserted the previously-informative text as the normative requirement. ACTION: Review. We usually use "n" for the rank of an array. "r" -> "n". (Not just here either, many places.) There is nothing that says how subscripts[i] map to the dimensions of the array object. Added something. ..., Example, "the following code returns" -> "the following code calculates" (it does not return anything). CFI_allocate Apparently this function allocates memory for an object and then throws the address away. It does not assign it to dv->base_addr! Appended ", and assigns the address of that memory to dv->base_addr". "On entry, the" -> "The". ", and the ... length for the type unless the type is ..." ->". If the type is not ..., the ... length". (The run-on sentence has nothing to do with the first part.) After "The attribute member" deleted "of the C descriptor" (context is sufficiently established already). "is the address of a lower bounds array" forsooth - is this not intended to be some kind of requirement? Anyway, the stuff about the semantics is explained in the action para later, nothing needs to be here, so I deleted it. "greater than or equal to the rank specified in the C descriptor" ->"at least \cf{dv->rank}". elem_len description is schizoid re "type specified in the C descriptor is a character type" and "the object is of Fortran character type". Settled on the former. COMMENT: It is not really acceptable for the action taken by a function to appear in the "Formal Parameters" section as paragraphs not related to any particular formal parameter. Yes, we already did this one for an intrinsic, but that was a mistake we should not be repeating. The C standard does actions with its "Description" section; for intrinsics we already used that for the one-line description, but these are C functions so we don't need to follow that convention... Reformatted all of the C function descriptions to more closely follow how the C standard does it, in particular added a Synopsis section to cover both the one-line-description and the prototype definition (having the prototype definition in the subclause heading is a Really Bad Idea; those do not establish normative requirements!). COMMENT: "The result is an error indicator." This is the ***FIRST TIME*** that the phrase "error indicator" has appeared, and there are no defined semantics for it. Grr. Went back and added a definition, and indexed it. Rewrote the text about detecting error conditions to be more accurate and less misleading. ACTION: Review. COMMENT: "If an error is detected..." this is ok, but it would be better to talk about error conditions rather than errors. Removed unnecessary "dummy" from the example. CFI_deallocate .. made the "becomes a null pointer" a run-on sentence so there cannot be any perceived contradiction with the next sentence. "{elem_len} is ignored unless {type} is CFI_type_struct" ->"... unless {type} is equal to ..." (sigh). "If the type is"->"If {type} is equal to" (++sigh). The description is thoroughly broken anyway as it mixes macro names with "a character type" (a semantic concept, not a value or macro name) and "a Fortran character type" (ditto and also inconsistent with the preceding). ++UG. Rewrote. "specifies the rank."->"specifies the rank of the object.". Rewrote this one too. "if the {rank} is zero" -> "{rank} is equal to zero", "with r elements specifying the corresponding extents..."... GB. Rewrote. "described array"->"object". CFI_establish "dv shall be the address of a C object" ok then, what's a "C object". This term is not defined. Furthermore, if int cdesc[10000] = { 0 }; is big enough and is allowed to be used for this, why would INTEGER(C_INT),BIND(C,NAME='cdesc') :: x(10000) = 0 not be allowed? HOW CAN YOU TELL? "C object"->"data object". COMMENT: Loads of other places permit larger array arguments than necessary, why not this one? "determined to be contiguous"->"contiguous" (contiguous is already processor-dependent, what is "determined" supposed to mean? that the processor may replace CFI_is_contiguous with the constant 0? or processor-dependently not give the right answer on Tuesdays?) The note is ++UG, as it sounds like it is the complete definition of whether the array is contiguous (but it is not even close). Rewrote from scratch. COMMENT: The one-line description of CFI_section is meaningless. (Something like "Performs an array sectioning operation on a C descriptor" would be more understandable, or if we want to be a bit more rigorous, "Make a C descriptor describe an array section using section subscripts".) But maybe it's harmless waffle ... left as is. ACTION: Review. Can this be improved? "The corresponding values of the \cf{elem_len} and \cf{type} members shall be the same in the C descriptors with the addresses \cf{source} and \cf{result}." ->"The \cf{elem_len} and \cf{type} members of \cf{source} shall have the same values as those members of \cf{result}." or ->"The \cf{elem_len} and \cf{type} members of \cf{source} shall have the same values as the corresponding members of \cf{result}." or ->"The values of \cf{source->elem_len} and \cf{source->type} shall be the same as those of \cf{result->elem_len} and \cf{result->type}, respectively." ??? I did the second variation. ACTION: Review. Deleted cross-reference for Fortran array element order. COMMENT: I don't know how we can require an array to be "specifying the subscripts". It seems to me that we can require an array with constraints on its values etc., but "specifying the subscripts" is how we are going to interpret it, it is not something we can require of the program - unless the processor can do ESP on the coder. ACTION: I rewrote all of this from scratch to try to require the right things and interpret the right things... Review. COMMENT: "If it is a null pointer, the subscripts of the first element of the array described by the C descriptor with the address \cf{source} are used". How are they used? As a dessert topping? To clean the floor? This is hopelessly vague... Actually, the entire function CFI_section is hopelessly vague. Rewrote from scratch. COMMENT: The one-line description of CFI_select_part is terrible. "The type member of the C descriptor shall specify the type of the array section." Really? This is a requirement on the program? But how do you know the type of the array section other than with result->type? If result->type is the type of the array section, which would certainly appear to be the case, we would seem to have been led into tautology. ... changed this to "specifies the type". ACTION: Review; if there is meant to be a requirement here, it should be more clearly stated what it is. ADDED A NEW REQUIREMENT: displacement+result->elem_len<=source->elem_len. "unless \cf{type} is a character type" but there is no argument "type", this should be \cf{result->type}. Furthermore, it cannot "be" a character type but it can "specify" a character type. Even Furthermore, if "the array section is a Fortran character type" [note this is not the same as "character type" so we already have a potential hole] "the value of elem_len shall be the storage size in bytes of an element of the object" [note not the array section but the object, which must mean the parent array]. This requirement narrows it down to a single unique value. Then we go on with an unqualified requirement (which it is being "ignored" or not, so a contradiction there) for it to lie in a particular range, 1 <= elem_len <= source->elem_len (size of the whole type). Well, just consider TYPE T1 INTEGER(int64) x CHARACTER(0) y(100) END TYPE Making a section for something%y therefore requires 1 <= 0 <= 8 which looks a bit tricky to achieve. Even more obviously, TYPE T2 INTEGER(2) X CHARACTER(1000,SELECTED_CHAR_KIND('ISO_10646')) Y(0) END TYPE can require 1 <= 4000 <= 2, which looks even more difficult. Look, if you've already required it to be the size of a single array element of the right type, why are you trying to say what numerical value you think that might have? Deleted this apparently-bogus requirement. ACTION: Review. COMMENT: How is CFI_select_part supposed to know whether elem_len should be ignored? (In some situations that ends up as how is the user supposed to know whether he needs to pass this in or not.) That would seem to require coding outside the standard... The paragraph "Successful execution of CFI_select_part updates the \cf{base_addr}, \cf{dim}, and \cf{elem_len} members of the C descriptor with the address \cf{result} for an array section for which each element is a part of the corresponding element of the array described by the C descriptor with the address \cf{source}." is rather vague and could be rewritten to say what actually gets assigned. ACTION: Review new Description and suggest improvements. "The part may be a component ..." ->"The part shall be a component ..." (Ok, maybe we cannot detect this easily at runtime, but we should require it. I cannot imagine why we need to *give permission*.) ACTION: Review requirement. ...Example "A(:)%Y" -> "A%Y". COMMENT: Ok, these examples are meant to be simple so we omit the necessary error handling, but really I cannot accept "ind = ...; ind = ...;" Just throwing away the error indication in a particularly evil fashion. Changed to "(void)...;" to at least look as if we know what we are doing. CFI_setpointer: "Successful execution of CFI_setpointer updates the base_addr and dim members of the C descriptor with address result with information in the C descriptor with the address source and in lower_bounds." No it does not. source and lower_bounds are both permitted to be null pointers, in which case the standard just dumped core by dereferencing one of them. And we already stated this with correct wording in the "result" paragraph. "... with information..." -> "... as follows:" plus joined the next paragraph to this one otherwise it could be read as unconditionally describing the effect, rather than just the successful execution effect, and made it a list. Deleted "and causes the allocation status of any associated allocatable variable to change accordingly (ref)", since this is an unnecessarily redundant duplication of existing text that already appears in the standard. The phrase "a BIND(C) interface" is not acceptable shorthand for "an interface [for a procedure] with the BIND attribute"; changed to "an interface with the BIND attribute". UTI 007. Lifetimes subclause para 1 is unrepairable nonsense. "If a Fortran pointer becomes associated with a C object, the association status of the Fortran pointer becomes undefined when the lifetime of the C object ends." must be wrong, consider a Fortran pointer that is argument-associated with a C descriptor, on return from the C procedure the Fortran pointer does not become undefined. Anyway, as I wrote before, what's a "C object"? Changed to: "If a Fortran pointer is pointer-associated with a data object defined by C, And why the sudden fuss in the TS over a Fortran pointer becoming associated with a "C object [sic]"? This already happened in F2003! "C object"->"data object defined by C", "lifetime of the C object"->"lifetime of that data object". But I think we simply need to define "lifetime" of a Fortran data object (extracting this from various parts of c16, esp. "events that cause variables to become undefined"), and then we need say nothing extra here. COMMENT: "illustrates how a C descriptor becomes undefined" ... No it does not. Not at all. Since this is just introductory nonsensical waffle, left along for now. "Before Cfun is invoked"->"Before or during the invocation of", "the processor creates"->"the processor will create", "the C descriptor"->"that C descriptor", "all C pointers whose values were"->"a C pointer whose value was", "become"->"will become". (grammar). 15.5.1p4 "a a function" -> "a function". 15.5.1p6+ "be declared"->"be declared to have the type". COMMENT(15.10.4) I really don't see why this belongs in "Interoperation with C functions" since it is talking about variables. Left as is, but should probably be in 15.4 which at least is talking about variables (and take "global" out of the title of 15.4). ACTION: Review placement. 16.5.2.4 REJECTED. This is not, repeat NOT, an event which causes the pointer to become disassociated. ... but I did add it to 16.5.2.5 Events that cause the association status of pointers to become undefined, with appropriate rewording e.g. "C object"->"data object defined by the companion processor". Annex A: These were all unacceptable as they are missing the required cross-reference to the normative text; but I tried to find and insert the correct cross-references. ACTION: Review cross-references. "the file"->"the source file" many times. "functions specified" -> "functions declared". "base address of a zero-sized array" ->"base address of an object with zero size Annex C: "array of assumed size" forsooth. "The examples A.1.2 and A.1.3..." deleted. "x and y are passed by address"; this is a bold statement that is not supported by normative text. Deleted. They are passed with sequence association and that is about as much as you can say. "pass by address" is another name for "call by reference". This is not required by the example code at all. The Fortran processor can use a number of different argument passing conventions. Ending up with an address on the "C side" does not mean it was call-by-reference: call by value-result and call-by-name are all possible and none of them are ruled out by the Fortran standard. Deleted all the "pass by address" assertions. In fact, deleted those column-passing examples as they are completely uninteresting (after deleting the mis-statements). "commonly called a ``fat binding''": I've never heard it called that. Deleted uninteresting snippet of regional dialectic computerspeak. "In this implementation"->"With this method". "However, the following call from Fortran is not allowed:" I just went ahead and deleted this claim and the allegedly erroneous example, as I could not see what is allegedly wrong with it. Without any such explanation, this is completely UNinformative. Anyway, it looks fine to me... ACTION: If there is something wrong, and this example would actually help someone somewhere to understand the feature, reinstate with explanation of what it is that is wrong with it. "The wrapper routine implemented in C reads" ->"The wrapper routine can be written in C as follows." I tried to make these examples look more stylistically similar to the others in Annex C, but doubtless failed. It might be a good idea to spend some time polishing these and other examples... Deleted the subheading in A.1.4, as that is all this talks about. "might" -> "could possibly". (unstated "but not on a compiler which supports more than 2 real kinds"). Some other wording tidying-up. Fixed nonstandard KIND number usage. Really! COMMENT: New C.11.6-C.11.14 all missing required cross-ref in subclause title. ACTION: Look up and insert appropriate cross-references. ===END===