Simplify the introduction #694
Open
+53
−148
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The changes in this commit aim to simplify the introduction, by: - Simplifying complex sentences; - Removing (most) statements that do not apply to all implementations; - Consolidating references to C++, OpenCL, etc to avoid repetition; and - Highlighting the key features of SYCL with shorter bullet points. The result is a significantly shorter introduction (300 words vs 1200 words) that succinctly summarizes what SYCL is and why developers should use it.
|
I think this is a very nice simplification. It is clear and to the point. |
|
Quick review on this please. |
nliber
approved these changes
Jan 23, 2025
tomdeakin
reviewed
Jan 23, 2025
| // How does SYCL relate to C++? | ||
| SYCL is designed to be as close to standard {cpp} as possible, and some | ||
| implementations of SYCL may be able to use a standard {cpp} compiler to target | ||
| CPU architectures. |
There was a problem hiding this comment.
Suggested change
| CPU architectures. | |
| CPU devices. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The changes in this commit aim to simplify the introduction, by:
The result is a significantly shorter introduction (300 words vs 1200 words) that succinctly summarizes what SYCL is and why developers should use it.
Some of the changes I've made here might be a little bit contentious, so I want to provide a little more insight into how I decided what to cut and what to keep.
First, I wrote out a list of questions that I think a reader would hope to be able to answer by reading the introduction. (You can see these questions as comments in the AsciiDoc). Then I reordered all the paragraphs in the existing introduction under those headings, and it became apparent that there was quite a lot of repetition around alignment with C++, access to low-level OpenCL features, etc. So I tried to collapse all of that together.
Second, I took out (almost) everything that described how SYCL implementations work. I convinced myself a lot of this was outdated and probably didn't apply to most implementations. For example, there were claims that it is always possible to use SYCL with arbitrary host compilers and/or without special linkers. I made an exception for a statement that SYCL implementations could choose to be implemented on top of nothing but standard C++, because I think that highlights an interesting aspect of SYCL's design philosophy.
Third, I tried to boil everything down to the really important points, inspired by the introduction to the OpenCL specification. We've got the rest of the specification to explain how features like buffers work, and I think it makes more sense to just point interested readers to the relevant sections.