Update man pages to clarify MPI-4 error handlers #11015
Conversation
|
@hppritcha is this what you were looking for from #10783 ? |
| @@ -0,0 +1,49 @@ | |||
| Almost all MPI routines return an error value; C routines as the return result | |||
There was a problem hiding this comment.
Is there a reason not to put the "ERRORS" section title in this file, too?
There was a problem hiding this comment.
I didn't think of putting the ERRORS header in this file.
But, as I was going thru the individual manpage files, I noticed some pages had headings included ERRORS in all caps and some as Errors.
If I put the ERRORS heading in this file, then I think it's going to look odd when all the other headings are mixed case on a page.
I can change it if you want it changed anyway.
There was a problem hiding this comment.
The man pages were written over a long period of time, by different people. It's possible (likely!) that there are inconsistencies like this (ERRORS vs. Errors).
Let's make new text as consistent as possible (and potentially fix old inconsistencies). I.e., make the Errors subsection follow whatever the convention is for that level of subsection. Are there other titles of the same level of subsection that are inconsistent?
There was a problem hiding this comment.
I'm not sure what you're asking to do about the inconsistency regarding ERRORS vs Errors. If I move that into the ERRORS.rst file, then I guess I would use ERRORS there since that is a section heading. But then do I find the other section headings in every man page including the ones I have not yet touched and change all of those to uppercase?
I agree overall formatting consistency is desirable, but I also think consistency within a page is more important than overall consistency.
Should I be changing all section headings in this pull request? That feels a bit out of scope for the intent of this pull request.
There was a problem hiding this comment.
Yes, I'm suggesting moving the subsection title into ERRORS.rst. I'm further suggesting make the capitalization of the subsection title in ERRORS.rst be consistent with whatever we do for other subsection titles at the same level in other man pages.
That being said, if we have more than just "ERRORS" vs. "Errors" inconsistencies in capitalization of subsection titles, we should probably make them all consistent. That would satisfy both overall formatting consistency and within-one-man-page consistency. I agree that this should probably be either a separate PR, or a standalone commit on this PR. It probably wouldn't be too hard to hack up a script or two to help automate making the pages' subsection titles be consistent (vs. editing all bazillion of our man pages manually). It might be worth looking at other popular man pages to see what their conventions are -- e.g., some GNU man pages like binutils or coreutils or something.
There was a problem hiding this comment.
@jsquyres I prefer to handle all the man page section headings changes, which I think can be scripted, as a separate pull request in order to keep that change from being tangled in more changes directly related to this pull request reviews. I also prefer to keep the ERRORS heading in each man page since there are some man pages with text about error handling which is different than what's described in ERRORS.rst. So I think keeping the ERRORS heading in each man page is more consistent and avoids getting anyone confused about where that heading went when ERRORS.rst is included.
There was a problem hiding this comment.
Per discussion - this will happen in a separate PR after this PR is merged
All man pages use a common text file to describe error handling with additional text for some MPI_Test*, MPI_Wait, and MPI_Grequest* pages. Fix review comments Signed-off-by: David Wootton <[email protected]>
|
/azp run |
|
Azure Pipelines successfully started running 1 pipeline(s). |
|
@drwootton Please PR to v5. We'll also want to include the section headers PR that you are working on. They can come over to v5 together or separately, just as long as we don't forget. Thanks! |
This pull request is to update MPI man pages to describe MPI-4 error handling, as described in section 9.3 of the MPI-4 standard, to resolve issue #10783
I'm placing this text in an ERRORS.rst file with the intent that this file be included in any man page where MPI function call error handling needs to be described.
Currently this is just the text I propose, with markup to be added later.
@hppritcha At this point I am looking for comments on this text.
This text might be a bit long. Maybe one way to shorten it is to just name the three predefined error handlers and anyone interested can read the detail in the MPI standard.
Signed-off-by: David Wootton [email protected]