[SR-3281] Update swift man page · Pull Request #10241 · swiftlang/swift

ghost · 2017-06-14T04:13:50Z

Attempt at SR-3281. (cc @CodaFi 😃)

DESCRIPTION section is from Swift.org - About Swift.
BUGS section is from Swift.org - Contributing.

Feedback is welcome.

NAME
    swift -- Safe, fast, and expressive general-purpose programming language

SYNOPSIS
    To invoke the Swift REPL (Read-Eval-Print-Loop):

        swift

    To execute a Swift program:

        swift program.swift -- <arguments>

    To work with the Swift Package Manager:

        swift build|package|run|test [options] <inputs>

    To invoke the Swift compiler:

        swiftc [options] <inputs>

    A list of supported options is available through the "-help" option:

        swift -help

        swift build -help

        swiftc -help

DESCRIPTION
    Swift is a general-purpose programming language built using a modern
    approach to 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 cloud services. Most importantly, Swift is designed to
    make writing and maintaining *correct* programs easier for the
    developer. To achieve this goal, we believe that the most obvious way to
    write Swift code must also be:

    Safe. The most obvious way to write code should also behave in a safe
    manner. Undefined behavior is the enemy of safety, and developer
    mistakes should be caught before software is in production. Opting for
    safety sometimes means Swift will feel strict, but we believe that
    clarity saves time in the long run.

    Fast. Swift is intended as a replacement for C-based languages (C, C++,
    and Objective-C). As such, Swift must be comparable to those languages
    in performance for most tasks. Performance must also be predictable and
    consistent, not just fast in short bursts that require clean-up later.
    There are lots of languages with novel features — being fast is rare.

    Expressive. Swift benefits from decades of advancement in computer
    science to offer syntax that is a joy to use, with modern features
    developers expect. But Swift is never done. We will monitor language
    advancements and embrace what works, continually evolving to make Swift
    even better.

BUGS
    Reporting bugs is a great way for anyone to help improve Swift. The bug
    tracker for Swift, an open-source project, is located at
    <https://bugs.swift.org>.

    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 <https://bugreport.apple.com> instead.

SEE ALSO
  HOME PAGE
    <https://swift.org>

  APPLE DEVELOPER RESOURCES
    <https://developer.apple.com/swift/resources>

  CODE REPOSITORIES
    Swift Programming Language at <https://github.com/apple/swift>

    Swift Package Manager at
    <https://github.com/apple/swift-package-manager>

CodaFi · 2017-06-14T04:38:39Z

Thank you for picking this up! 💖

You should notify swift-dev and maybe swift-evolution about this.

DougGregor

Looks great, thank you!

DougGregor · 2017-06-14T05:52:45Z

docs/tools/swift.pod

Let's drop the "Apple Inc" part.

"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.

DougGregor · 2017-06-14T05:53:30Z

docs/tools/swift.pod

Maybe also add:

To execute a swift program:

swift program.swift -- <args>

xwu

Great improvement, bravo for taking the time to put this together. I've gone into editor mode and made some nitpicky comments.

xwu · 2017-06-14T08:34:51Z

docs/tools/swift.pod

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")?

Thanks 👍

xwu · 2017-06-14T08:39:09Z

docs/tools/swift.pod

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).

xwu · 2017-06-14T08:41:02Z

docs/tools/swift.pod

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).

xwu · 2017-06-14T08:44:47Z

docs/tools/swift.pod

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.

see RUBY(1) as an example. debatable, and based off @CodaFi's ideas.

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.

xwu · 2017-06-14T08:46:06Z

docs/tools/swift.pod

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.

xwu · 2017-06-14T08:49:06Z

docs/tools/swift.pod

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."

xwu · 2017-06-14T08:56:37Z

docs/tools/swift.pod

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.

dabrahams · 2017-06-14T14:14:42Z

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

xwu

Just some straggling follow-on comments.

xwu · 2017-06-14T16:32:25Z

docs/tools/swift.pod

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?)).

xwu · 2017-06-14T16:33:29Z

docs/tools/swift.pod

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.

Personally, I find the Swift - Resources - Apple Developer page linked in https://developer.apple.com/swift/ very useful. Any further thoughts?

@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"?

xwu · 2017-06-14T16:37:10Z

docs/tools/swift.pod

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.

xwu · 2017-06-14T17:56:49Z

docs/tools/swift.pod

Last nit, I promise: Probably best if not both bold and all-caps? Anyway, this is awesome, and thanks for humoring me.

ghost · 2017-06-16T15:25:57Z

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.

adrian-prantl · 2017-06-20T22:02:27Z

docs/tools/swift.pod

Is there a technical reason for this not to be a fully-qualified link, e.g.: https://bugreport.apple.com ?

ghost · 2017-06-27T14:56:25Z

Pinging @DougGregor, @CodaFi, or @adrian-prantl to review.
I hope this doesn't get buried...

CodaFi · 2017-06-27T15:46:01Z

docs/tools/swift.pod

You should address Dave's comment about this description.

How's "high-performance system programming language" from the first line of the README instead?

high-performance system programming language

The second half of that description contradicts the rest of this document.

CodaFi · 2017-06-27T16:41:47Z

docs/tools/swift.pod

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)

ghost · 2017-06-27T17:58:46Z

@CodaFi, I've made changes based on your feedback.

Instead of

general-purpose programming language,

it's now

Safe, fast, and expressive general-purpose programming language.

CodaFi · 2017-06-27T18:39:59Z

Beautiful.

I think this is light years ahead of what was here before.

⛵️

@swift-ci please smoke test and merge

DougGregor reviewed Jun 14, 2017

View reviewed changes

xwu reviewed Jun 14, 2017

View reviewed changes

adrian-prantl reviewed Jun 20, 2017

View reviewed changes

CodaFi reviewed Jun 27, 2017

View reviewed changes

docs/tools/swift.pod Outdated

Copy link
Copy Markdown

Contributor

CodaFi Jun 27, 2017

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.

garricn mentioned this pull request Jun 27, 2017

[76] Issue #76 - June 29, 2017 SwiftWeekly/swiftweekly.github.io#280

Closed

[SR-3281] Update swift man page

c3c53e4

For future reference, please refer to the following man pages: - PERLDOC(1) - PERLPODSPEC(1) - PODCHECKER(1)

swift-ci merged commit 6bf18ea into swiftlang:master Jun 27, 2017

ghost deleted the SR-3281 branch June 27, 2017 19:24

Conversation

ghost commented Jun 14, 2017 • edited by ghost Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CodaFi commented Jun 14, 2017

Uh oh!

DougGregor left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ghost Jun 14, 2017 • edited by ghost Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xwu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dabrahams commented Jun 14, 2017 via email

Uh oh!

xwu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ghost commented Jun 16, 2017 • edited by ghost Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ghost commented Jun 27, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CodaFi Jun 27, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ghost commented Jun 27, 2017

Uh oh!

CodaFi commented Jun 27, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

ghost commented Jun 14, 2017 •

edited by ghost

Loading

ghost Jun 14, 2017 •

edited by ghost

Loading

ghost commented Jun 16, 2017 •

edited by ghost

Loading

CodaFi Jun 27, 2017 •

edited

Loading

CodaFi commented Jun 27, 2017 •

edited

Loading