Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refactor changelog to use new \ChangelogRef #15

Merged
merged 7 commits into from
Apr 9, 2020

Conversation

BryantLam
Copy link
Collaborator

@BryantLam BryantLam commented Apr 7, 2020

This PR primarily refactors the references in the changelog entries to reduce inconsistencies between entries and to make it easier to later alter its format if desired.

I highly recommend reading the changes in each commit rather than all changes together. This is because eff0264 adds new deprecation-specific labels and then applies them into the changelog — in my opinion this is the only non-trivial change to review and I don't want it to get muddied by the mostly mechanical conversion done in e3dd9d1 which are the bulk of the changes.

Notes:

  1. eff0264 tries to add references to each deprecated item. Turns out some of the older changelog entries were somewhat ambiguously phrased, so these references should definitely help disambiguate the changes in each of the affected changelog entries.
  2. e3dd9d1
    • Each \ChangelogRef ends in a % sigil as a visual reminder to not add a period.
    • As a restriction, I didn't reword any of the existing entries to make this commit as mechanical as possible.
  3. \ChangelogRef is implemented using package cleveref. By default, references are sort&compress. For our purposes, sort is fine. Compress, however, means that many-reference entries are compressed into a range instead; e.g., See Sections 1, 2, 3, 4 and 5. is converted into See Sections 1 to 5.. If this behavior is not desired, I can easily change it.
    • There's a bypass. One of the changelog entries uses double-commas ,, because it references tables and tables are spread throughout the document; its references shouldn't be compressed.
  4. cleveref doesn't use the Oxford comma (:cry:). I left it this way, but if we strongly oppose to its non-use, I can change that too.

One exceptional case involved several references to tables. This item
now uses double-commas to separate the ref entries so that `cleveref`
will not use range compression.
@BryantLam BryantLam force-pushed the refactor-changelog branch from 9fbd2d3 to e3dd9d1 Compare April 7, 2020 19:39
Copy link
Owner

@jdinan jdinan left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great -- thanks for these edits! A few minor nitpicks and also wondering whether we want to add back some changelog references that were substituted with references to the deprecation annex.

content/backmatter.tex Show resolved Hide resolved
content/backmatter.tex Outdated Show resolved Hide resolved
content/backmatter.tex Outdated Show resolved Hide resolved
content/backmatter.tex Outdated Show resolved Hide resolved
content/backmatter.tex Outdated Show resolved Hide resolved
content/backmatter.tex Show resolved Hide resolved
content/environment_variables.tex Outdated Show resolved Hide resolved
@BryantLam BryantLam requested a review from jdinan April 9, 2020 00:48
- Clarify problem with openshmem-org#66
- Change reference for deprecated (now removed) Fortran SHMEM_PUT to
  cross-reference an OpenSHMEM 1.4 section
    - Add optional text space in `\ChangelogRef`
@BryantLam BryantLam force-pushed the refactor-changelog branch from 9acc9b4 to 11337f1 Compare April 9, 2020 19:21
utils/defs.tex Show resolved Hide resolved
@jdinan jdinan merged commit 843458f into jdinan:sec/doc-edits Apr 9, 2020
@BryantLam BryantLam deleted the refactor-changelog branch April 9, 2020 21:52
jdinan pushed a commit that referenced this pull request Oct 4, 2023
Clarify barrier in shmem_malloc_hints is on SHMEM_TEAM_WORLD
jdinan pushed a commit that referenced this pull request Oct 4, 2023
jdinan pushed a commit that referenced this pull request Oct 4, 2023
Use `{ .. }` sets instead of `[ ... ]` optionals
jdinan pushed a commit that referenced this pull request Oct 4, 2023
jdinan pushed a commit that referenced this pull request Oct 11, 2024
collectives intro: add Scan to team-based list
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants