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
[SR-3281] Update swift man page #10241
Conversation
Thank you for picking this up! 💖 You should notify swift-dev and maybe swift-evolution about this. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks great, thank you!
docs/tools/swift.pod
Outdated
=head1 NAME | ||
|
||
swift - the amazingly new programming language | ||
swift - General purpose programming language by Apple Inc. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's drop the "Apple Inc" part.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"General purpose programming language" is super vague though...
Anyone else has other suggestions?
Another suggestion to also remove " by Apple Inc." with good reasons and so it will be removed.
|
||
B<swift> | ||
|
||
=back |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe also add:
To execute a swift program:
swift program.swift -- <args>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Great improvement, bravo for taking the time to put this together. I've gone into editor mode and made some nitpicky comments.
docs/tools/swift.pod
Outdated
=head1 NAME | ||
|
||
swift - the amazingly new programming language | ||
swift - General purpose programming language |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Below, the spelling is "general-purpose"; here, it is "general purpose"--you'll need to pick one.
May I also suggest following the example of Python, Ruby, LLDB, and others in using two-dashes (i.e., "swift -- General-purpose programming language")?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks 👍
docs/tools/swift.pod
Outdated
|
||
=back | ||
|
||
To invoke the Swift Compiler: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Although "Swift Package Manager" is capitalized throughout, here it's just "Swift compiler" without a capital C (as evidenced by the style used in swift -help
and swift package -help
).
docs/tools/swift.pod
Outdated
|
||
=back | ||
|
||
The list of supported options is available through the "-help" option: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm being very nitpicky, but:
The original text was: "The full list of supported options..." If you're going to drop "full," then probably best if it's simply "A list of supported options..." (or, restore the original).
The goal of the Swift project is to create the best available language for uses | ||
ranging from systems programming, to mobile and desktop apps, scaling up to | ||
cloud services. Most importantly, Swift is designed to make writing and | ||
maintaining I<correct> programs easier for the developer. To achieve this goal, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I wonder if the text from "To achieve this goal..." to the end of this section is really doing much for the man page. I don't see other examples where this level of detail as to design intent is recorded in the "Description" section of other man pages.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Indeed, debatable.
Ruby does something quite different, however. It describes what the language is (e.g., garbage collected). This text here describes what the language should/must/will be (e.g., should be safe, will feel strict, must be comparable). It is a description of the Swift project, but not really a description of the Swift language.
safety, performance, and software design patterns. | ||
|
||
The goal of the Swift project is to create the best available language for uses | ||
ranging from systems programming, to mobile and desktop apps, scaling up to |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nit here: That comma between "programming" and "to mobile" shouldn't be there. I know you've transposed this text from elsewhere, but nonetheless it's an extraneous comma.
docs/tools/swift.pod
Outdated
=head1 BUGS | ||
|
||
Reporting bugs is a great way for anyone to help improve Swift. The open source | ||
Swift project uses Jira for tracking bugs. Our Jira instance is located at |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think the fact that Swift uses Jira might be relatively less relevant information for a man page. Can I suggest:
"Reporting bugs is a great way for anyone to help improve Swift. The bug tracker for the open-source project is located at Lhttps://bugs.swift.org."
docs/tools/swift.pod
Outdated
|
||
=head1 SEE ALSO | ||
|
||
More information and resources are available online. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I wonder if the non-link text in this section could be either made more informative or removed.
For instance, "More information and resources" is a longer way of saying "See also" and "are available online" is immediately self-evident from the links that follow. Likewise, the "developer.apple.com" link is clearly to an Apple Developer resource, and the "github.com" links are clearly to GitHub. Perhaps the links could be accompanied by some concise description of what's there, or alternatively if that seems redundant, just the links can stand alone.
on Tue Jun 13 2017, nate <notifications-AT-github.com> wrote:
contraultra commented on this pull request.
> =head1 NAME
-swift - the amazingly new programming language
+swift - General purpose programming language by Apple Inc.
"General purpose programming language" is super vague though...
Anyone else has other suggestions?
In typical fashion I'll suggest starting with simply “programming
language” and then asking if there's anything more you actually want to
express about it.
…--
-Dave
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just some straggling follow-on comments.
docs/tools/swift.pod
Outdated
maintaining I<correct> programs easier for the developer. To achieve this goal, | ||
we believe that the most obvious way to write Swift code must also be: | ||
|
||
=head2 SAFE |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Are these best as headings, or as @CodaFi experimented with, might they work better as bolded text? After comparing the two, I'm inclined to think the latter. In part, I think it's because these don't fit in with the other headings (Synopsis, Description, Bugs, See Also, Home Page...Expressive (huh?)).
docs/tools/swift.pod
Outdated
|
||
L<https://swift.org> | ||
|
||
=head2 APPLE DEVELOPER |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is there any info on the Apple Developer Swift page that a user should "see also" not adequately covered elsewhere? If not, this link might be dispensable, being vendor-specific and all.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Personally, I find the Swift - Resources - Apple Developer page linked in https://developer.apple.com/swift/ very useful. Any further thoughts?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@contraultra Wow, yes, that's very useful! It's unlikely that any but the most thorough reader would find that link, though, from the page currently linked to. How would you feel about linking to that page instead and titling this "Apple Developer Resources"?
docs/tools/swift.pod
Outdated
|
||
L<https://developer.apple.com/swift> | ||
|
||
=head2 GITHUB |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd suggest "Code Repositories" or "Git Repositories" here. Clearly, these are links to GitHub. A person who doesn't know what GitHub is can't benefit from the current heading; a person who does know what GitHub is won't benefit from any heading.
docs/tools/swift.pod
Outdated
maintaining I<correct> programs easier for the developer. To achieve this goal, | ||
we believe that the most obvious way to write Swift code must also be: | ||
|
||
B<SAFE.> The most obvious way to write code should also behave in a safe manner. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Last nit, I promise: Probably best if not both bold and all-caps? Anyway, this is awesome, and thanks for humoring me.
The feedback period for this pull request attempt has ended. Thank you to those who participated in the feedback. Based on the feedback received, I have included most suggestions and this is the final draft. Please review. |
docs/tools/swift.pod
Outdated
|
||
If a bug can be reproduced only within an Xcode project or a playground, or if | ||
the bug is associated with an Apple NDA, please file a report to Apple’s | ||
bug reporter at bugreport.apple.com instead. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is there a technical reason for this not to be a fully-qualified link, e.g.: https://bugreport.apple.com ?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
no
Pinging @DougGregor, @CodaFi, or @adrian-prantl to review. |
docs/tools/swift.pod
Outdated
=head1 NAME | ||
|
||
swift - the amazingly new programming language | ||
swift -- General-purpose programming language |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You should address Dave's comment about this description.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How's "high-performance system programming language" from the first line of the README instead?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
high-performance system programming language
The second half of that description contradicts the rest of this document.
docs/tools/swift.pod
Outdated
|
||
=head2 APPLE DEVELOPER RESOURCES | ||
|
||
developer.apple.com/swift/resources |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This should be qualified with an L<>
or formatted like @adrian-prantl said.
For future reference, please refer to the following man pages: - PERLDOC(1) - PERLPODSPEC(1) - PODCHECKER(1)
@CodaFi, I've made changes based on your feedback. Instead of
it's now
|
Beautiful. I think this is light years ahead of what was here before. ⛵️ @swift-ci please smoke test and merge |
Attempt at SR-3281. (cc @CodaFi 😃)
DESCRIPTION
section is from Swift.org - About Swift.BUGS
section is from Swift.org - Contributing.Feedback is welcome.