To: J3 J3/21-171 From: Malcolm Cohen Subject: Editor's report for 21-007r2 Date: 2021-August-30 1. Introduction This is the editor's report for 21-007r2. It consists of three additional sections: 2 - initial edits 3 - papers applied to the draft 4 - additional edits afterwards 2. Initial edits - turned WGWD off (it is not a WG5 document this time). - 007r1 -> 007r2 - set target date as 0821 - Index NON_INTRINSIC as "NON_INTRINSIC module nature", instead of just the keyword. - Index INTRINSIC module nature - Index NON_RECURSIVE as attribute only, not also as the keyword - Fix typo "generic type bound procedure" -> "generic type-bound procedure". 3. Papers in order of application 21-141. Done. 21-145. DIFFERENT [184:1] Instead of the suggested "EXIT statement or CYCLE statement that belongs...", made "EXIT or CYCLE statement that belongs..." which is shorter and less ambiguous. Done. 21-143r1. [380:14-15] Also hyperlinked (no indexing) the intrinsic functions, and converted some text pluses to maths pluses. EXTRA [380:16-17] noticed that two of the ellipses in Case (ii) had four dots instead of three, fixed. Done. 21-142r2. Done. 21-158. Done. 21-161. Hyperlinked all the new "effective item"s, and some pre-existing ones, usually without indexing. EXTRA [31:16] Changed "A value of 0" to "A value of zero". EXTRA [243:14-16] "a" -> "an" before first replacement. "specified in the list in component order" -> "specified in component order" as since we're talking about effective items, we're not in the list any more. Anyway, the array case says the elements are "specified in array element order" without saying in the list, so this makes the wording more consistent. DIFFERENT: [244:2] replace "the list" with "the corresponding list item" It does not make sense to say "specified in the corresponding list item" especially since there is now no established list item. Instead delete "in the list" so it now says "...that effective item is treated as if all the components of the effective item were specified in component order; ..." This is like the previous (EXTRA) edit for the unformatted case. PLEASE: Subgroup please review this, and come up with better wording if this is not good enough. If better wording is needed here, it is likely also needed for the unformatted case and the array case. DISAGREE [250:...] no changes [250:29-31] 12.6.4.8.3 Executing defined input/output data transfers, has "If... effective item... that item... the derived-type list item." I believe the last is simply wrong, so "that item" -> "that effective item" (consistency) "the derived-type list item" -> "the effective item". {The other "no changes" on this particular page look ok at first glance.} DIFFERENT [266:40] said to replace "input list items or namelist group objects in the statement that initiated the transfer" with "effective items resulting from the expansion of list items in the statement that initiated the transfer" BUT this wording does not seem to cover namelists, as there is no list item in the statement then (the old wording was bad too, as there are no namelist group objects in the statement). INSTEAD replaced with "effective items resulting from the expansion of list items or the namelist group in the statement..." COMMENT [267:12] no change BUT Case (a) uses "effective item", why not here? [273:4] The edit had "than" instead of "that", but I did what was intended. EXTRA EDIT [276:11-12] 13.7.2.3.1 General (in 13.7.2.3 Real and complex editing), p1, input/output list item" -> "effective item". DIFF [282:19] replace "output list item" with "output effective item" - I didn't like "output effective item", so replaced with "effective item [of type character] in an output statement". (An alternative would be "is used for output editing of an effective item of type character". DIFF [282:25] replace "input/output list item" with "input effective item" Just "effective item" is sufficient here. DIFF [282:26] replace "input item" with "input effective item" Do not like this term. Used "effective item on input". DIFF [282:29] replace "output item" with "output effective item" Replaced with "effective item on output". DIFF [282:33-35] replace "output list item" with "output effective item" 3 times There is no need for the word "output" to precede "effective item", it is just as clear without. DIFF [288:22+] In note 2; replace "list items" with "effective items" "no list items are" -> "no effective item is". (improve grammar - zero/no is not plural) COMMENT [290:6] (which was: replace "additional items" with "additional effective items") I suggest deleting "in the input list", as it sounds confusing, as technically not all effective items are literally in the input list. DIFF [290:8] replace "input items" with "effective items" "input list items" -> "effective items" DISAGREE [294:5] no change EXTRA [294:5] "corresponding list item" -> "corresponding effective item" (it has to be this as it refers to the effective item right at the start of the sentence, so what's it doing suddenly switching to list item?) COMMENT: Maybe this sentence would be improved by changing "the corresponding effective item" to "that effective item", to avoid giving the impression that there is more than one effective item in the discussion. DIFF [294:22] replace "list item" with "effective item" "input list item" -> "effective item" (we're only talking about input here, no need to keep spelling it out) YES, BUT [296:5-6] no change needed COMMENT: p1 says "same namelist group item" p2 says "each namelist group object list item" I think these are talking about the same things, and therefore should be using the same term. (If they are not talking about the same things, I am confused! Explain!!!) Adobe Reader claims "namelist group item" only appears here, so presumably that is the one that is wrong. DISAGREE [328:13] no change needed If a component in the middle of a list item of derived type is processed by defined i/o, that would say that completion of the defined i/o proc would terminate the whole list item. Yes, we can quibble that this means "the expanded list", but it does not say that. I think that "input or output list item" -> "effective item" (hyperlinked) would be an improvement... but I did not change it at this time. SUBGROUP PLEASE REVISIT THIS. REALLY??? [548:11] no change needed COMMENT If some part of an input list item is processed by defined input, the item is expanded into effective items just like formatted input (except only one level). So I think this should probably be changed too, but I wasn't confident enough to just do that. SUBGROUP PLEASE REVIEW EXTRA [555:26-27] "list items" -> "effective items". DIFF [579:5] replace "list item" with "effective item" YES, and joined p6 to p5 since it is a continuation thereof. COMMENT "in the input list" seems harmless but superfluous. EXTRA: [579:7-8] C.8.2 Nonadvancing input/output (12.3.4.2), p7, "during a nonadvancing data transfer statement" -> "in nonadvancing input". {"during a statement" is nonsense. And it does not apply to output, which is a common confusion, so be up front about it being for input!} DIFF [579:8] replace "list item" with "effective item" "input list item" -> "effective item" (having been honest in the first sentence in the paragraph, we don't have to keep hammering home the fact that this is for input). DIFF [579:10] replace "list item" with "effective item" "the input list item completed successfully" is unmitigated nonsense; instead "input of the effective item completed successfully" Done. 21-107r2. REJECT: Nearly everything. These examples are overly complicated with much time setting up or explaining things not related to the actual procedure they are supposed to be examples of. For functions, examples should preferably just say what the result is (see all the intrinsic functions!). For subroutines, they should say what the result is. Injecting irrelevant complexity (qsort forsooth) is distracting and thus counter-productive (if someone wants an example of how to use qsort from Fortran, they should just write a book). In principle, examples in the subclauses for intrinsic procedures et al need to be really simple, unless there is a really strong reason for the complication. Also, explanations should be prose, not comments in the program. Separating these makes things a lot more readable. I appreciate that the goodness of an example is quite subjective. DIFF 18.2.3.2 C_ASSOCIATED [496:12+] - Too messy. - Initially I did a substantial rewrite preserving the structure, but on review I concluded that it was still too long and unnecessarily complicated by irrelevancies. Replaced by simple statements about the value of the function (even that is pushing it, as the Result Value clause is very explicit about the result for a null pointer!). Here is my original verbose adaptation. +\examples{} +\begin{incase} + +\item + +If the variable P is not changed between the assignment of \linkkw{C_NULL_PTR} and the IF construct, +the block of the IF construct will be executed: + +\begin{inlinett} + Interface + Function address_of_x() Bind(C) + Use Iso_C_Binding + Type(\linktypex{C_PTR}{C_ptr}) address_of_x + End Function + End Interface + Type(\linktypex{C_PTR}{C_ptr}) :: p + p = \linkkwx{C_NULL_PTR}{C_null_ptr} + \textrm{\ldots} + If (.Not. C_Associated (p)) Then + p = address_of_x () + End If +\end{inlinett} + +\item +If the C function \cf{address_of_x} in the previous example is as follows: + +\begin{inlinett} + extern double c_x; + void *address_of_x (void) + \{ + return &c_x; + \} +\end{inlinett} + +And the global C variable \cf{c_x} is bound to a Fortran module variable by the declaration + +\begin{inlinett} + Real(C_double), Target, Bind(C, Name='c_x') :: x +\end{inlinett} + +\begin{inlinepara} +then the following IF construct's block +\end{inlinepara} + +\begin{inlinett} + If (C_Associated (p, \funcinxux{C_LOC}{C_loc} (x))) Then + \textrm{\ldots} + End If +\end{inlinett} + +\begin{inlinepara} +will be executed if the construct is placed after the statements of the previous example. +\end{inlinepara} +\end{incase} REJECT In 18.2.3.3 C_F_POINTER [498:7] delete "Case (iv)" and unindent [498:7-14] by one level. - there is no doubt that case (iv) is another example. The fact that it has witter to explain it while the other three do not is a fault in the other three, not a fault in case (iv). - But the code in the example was excessively indented, so I fixed that. COMMENT: Perhaps it might be useful to append a sentence to Case (iv), something like "Note that this also works when the character length of C1 is specified by a nonconstant expression." COMMENT: It really would be nice if the first three examples had text explaining what they are for. (Not doing it myself right now as I am trying to get the rest of this paper done better.) DIFF In 18.2.3.4 C_F_PROCPOINTER after [498:26] add a new para 4 - programming "style" fixes: Missing "void" in the definition of "dispatch", Missing ampersand retrieving the address of cbrt. Changed IMPORT to USE so we don't need to assume anything. - Changed C_FUNPTR usage to uppercase; I could add a macro to hyperlink with different text if we really want mixed-case here, but it didn't seem to me like the case really mattered. - Interoperates with dispatch in code font, and without the parens as it doesn't interoperate with the result of invoking the function. - Turned all the embedded comments into witter, added more explanation. COMMENT This example is rather complicated. REJECT In 18.2.3.5 C_F_STRPOINTER after [499:12] add a new para 5 - These should be two examples, not one. - You cannot have C prototypes with ellipses: they have a specific meaning in C (and are not interoperable). - get_current_dir_name() is a GNU extension, not a C library function. - For that matter, even getcwd is a Posix function, not C library. - There are no C library functions that malloc their result (well, apart from malloc itself), but using "free" is not a requirement for an example anyway. DIFFERENT Instead, I did the following. - Simplified the first example to print a C string to a Fortran unit. - For the second, I chose to use the simplest C library function that returns a string (or null pointer): getenv. Yes, it's redundant with our own GET_ENVIRONMENT_VARIABLE, but that's not a problem for an example. REJECT In 18.2.3.6 C_FUNLOC after [499:24] add a new para 7 - This is way too complicated. This spends more time explaining how to use qsort instead of on how to use C_FUNLOC. - Example should have used TYPE(C_PTR) instead of TYPE(*) anyway, as that would have been simpler (the example is missing code, presumably because it was so ugly!). DIFFERENT Instead... - Result Value paragraph was broken - merged the two paras into one. - Added very much simpler example using atexit (maybe not much shorter, but it is complete and much simpler). REJECT In 18.2.3.7 C_LOC after [500:3] add a new para 10 - I think this is an example of poor programming practice. The purpose of C_LOC is for passing pointers to C, NOT for sidestepping Fortran rules. Yes, we now have a duplicate mechanism for that, but. - If the procedure is for calling from C, why would it not use TYPE(C_PTR) arguments instead of TYPE(*)? Then it wouldn't need to use C_LOC. - "type cast" is not acceptable language, and further encourages breaking the rules. - The main use of C_PTR/C_LOC now, instead of TYPE(*), is for components and function results. An example using components or functions would thus be less contrived. DIFFERENT - Fixed the Result Value paragraph vomit into cases. - I made a very simple example using a function. REJECT In 18.2.3.8 C_SIZEOF after [500:15] add a new para 7 - too much inconsequential witter. - broken: %li is not a portable edit descriptor for size_t, - programs are not equivalent - they produce different output. - NOTE 1 is not particularly interesting IMO, and the wording was dodgy. - NOTE 2 is less than uninteresting, as the same is true of derived types in general, and the claim that this is because of alignment "imposed by the companion" is in general untrue. INSTEAD (and this is completely from scratch) - Fixed Result Value to have two cases since it does, instead of having an unrelated paragraph. - Inserted very simple example. DIFF In 18.2.3.9 F_C_STRING after [500:29] add a new para - Combined paragraphs 5-6 into a single paragraph like it should be. - Moved para 7 to the STRING argument which is a better place than "Result Value", appended as a sentence, not a separate paragraph. COMMENT This is an example of suboptimal typesetting previously. The format for describing intrinsic procedures and procedures in intrinsic modules inherently has bold subtitles on every paragraph, but we (or I) have been a bit sloppy in places. - Some of the commentary was unacceptable (in Fortran, '\0' is not a character), and it is very suboptimal to have explanation as comments in the example instead of textual explanation. - Thus rewrote the example from scratch. Avoided the complication of reallocating assignment by simply saying what the function result is in each case; shortened value. Done. 21-166. EXTRA EDIT while checking the hyperlinks, I noticed that the definition of "pointer association" was wrong - it only applied to variables the way it was written (procedures do not have the TARGET attribute), thus [4:35] 3.7.7 pointer association, "an entity" -> "a procedure or a variable" making the whole definition read "association between a pointer and a procedure or a variable with the TARGET attribute (19.5.2)" Done. 21-162r1. [xiii] COMMENT Hyperlinked "Conditional expressions" to "Evaluation of operations" which is where the semantics are... but perhaps it would be better linked to the syntax? and hyperlinked "Conditional arguments" to "Conditional argument correspondence". DIFF [150:1-] Before 10.1.2.3 Level-1 expressions, insert new subclause - "sub-expression" -> "subexpression" (we don't hyphenate words like this). - "TOL" -> "TOLERANCE" (makes the example more readable). (hyperlinked the intrinsic functions in the example). COMMENT [47:10] hyperlinked .NIL. to where it appears in the syntax. Indexed. COMMENT I wonder whether we should attempt to mark disambiguating constraints as such? Unfortunately the existing ones are not marked in any way, so even if we reviewed them we might miss one... DIFF "any in a has the allocatable or pointer attribute, each expr" -> "any of a has the ALLOCATABLE or POINTER attribute, each consequent-arg". COMMENT It turns out "consequent" is slightly too long a word for typesetting the syntax on one line. It looks ok on two, so I did that (three lines might be better, to make the final consequent separate?). [316:7+] After the last constraint in this subclause (C1537), insert new BNF and constraints. DIFF - Added missing ": .NIL." in the example. [318:1-] Immediately before 15.5.2.3 Argument association, insert subclause "15.5.2.2a Conditional argument correspondence Done. 4. Additional edits 4.1 Changed inappropriate "master" terminology in Annex C to "main" or "controlling". 4.2 Changed some literal "1"s in prose to "one". ===END===