Archive for the ‘Books’ Category

Swift Style Update

coverscaled250

I finished the first draft today. It’s about 160 pages long, which is a bit longer than I expected. I’ll be revising and tweaking coverage next. If there are any specific style issues you want me to research and/or address please let me know now.

Also, if you’ve purchased any of my self-published titles, please make sure you have the latest versions. The current revision is always listed in the first section with the legal stuff and “Distributed worldwide by Erica Sadun”. The current versions are:

  • Swift Two to Three: 1.0.2
  • Swift Documentation Markup: 2.0
  • Playground Secrets and Power Tips: 3.5

If you do not have the right version, check for available downloads in iTunes or download the latest version from Leanpub.

Here’s the current Table of Contents for the book. If you noticed, I’m using a brand new toolchain for writing so I’ve got a much better ToC than I have had in the previous “Swift. Slowly.” titles:

 

My terrible no good horrible updating day

Good news: There should be an updated version of Playground Secrets awaiting iBooks customers. Apple is looking into why my updates over the summer did not get relayed to customers. This issue does not affect anyone who bought from LeanPub.

Expect another Playground Secrets update soon beyond this. I’m still tweaking to the final Xcode/Swift 3 release. Look for revision 3.5 to debut shortly. It will have¬†“Swift 3, Xcode 8” at the very top.

Good news: I’m also¬†updating Documentation Markup. A preview of some of the changes I address is here.¬†I’m probably going to include at least some of the points I made in my essay about past you and future you.

Good news: The response to the Swift Celebration Bundle has been so strong that I’m extending the sale until at least the end of this week. Thank you everyone!

Bad news: Some nice Xcode features have gone away. Remember this, which picked up information from the structured markup?

screen-shot-2016-09-19-at-2-48-51-pm

It’s now gone. Xcode no longer shows the abstract for the selected match.

Badder news: Xcode fuzzy completion is so relaxed and shows so much stuff that it can be really hard to find the API you actually want. There can be literally dozens of pages of completions for certain APIs.

Good news: After months of going back and forth with Bluehost technical support, they seem to have finally found something slowing down responsiveness. Hopefully this site will be slightly zippier. Not promising great responsive time but there should be fewer 504 errors and database errors and timeouts.

Helpful non-news: Make sure you check your iTunes Connect account to review your old applications. Not all notices are getting sent about the 30-day “you must update this old app” period. If you have some older titles, take some time to check on them.

Helpful extremely non-news: For whatever reasons, you must adhere to standard iTunes Connect dimensions when uploading Book screenshots. The books side of things won’t tell you what they are, but they are:¬†1024×768, 1024×748, 768×1024, 768×1004, 2048×1536, 2048×1496, 1536×2048, 1536×2008.

Xcode 8 Document Coding Enhancements

Now that I’ve gotten Swift 2 to 3 ready and out, I’ve turned my attention to Swift Documentation Markup. I’m updating the book¬†with both Swift 3 examples and markup enhancements. Xcode has added some great¬†new features although as you’ll see¬†there’s still work left to be done.

Xcode’s automatic doc-comment skeleton command is super¬†handy. Move the cursor to any¬†symbol and select Editor > Structure > Add Documentation (Command-Option-/).¬†Xcode scans the symbol you’ve chosen and adds a doc-comment outline including named parameters and return types if they exist.

screen-shot-2016-09-16-at-10-46-30-am

You may want to add further comment features like notes, warnings, authorship, dates, and complexity details, but the basics provided by Xcode form a great place to get started.

One Xcode feature that’s just launching¬†is support for treating closure parameters as first-class documentation elements. Xcode’s default documentation doesn’t include closure parameters, as you see in the screenshot that follows.

screen-shot-2016-09-16-at-11-06-41-am

Swift’s new “no ¬†labels for function types” means that many developers will not include the internal declaration arguments that I use in this example for the action¬†parameter.

By adding¬†internal arguments like (_ line: String), you can extend your documentation. Xcode picks up and formats that information into a special closure parameter box, subordinate to the closure that uses that parameter. Here’s an example that extends¬†the code documentation you just saw:

screen-shot-2016-09-16-at-11-09-13-am

Swift’s native¬†comment schema suggests that Xcode could potentially add further support. The schema includes nesting parameters, return values, and throws document comments, as promised in this commit:

screen-shot-2016-09-16-at-11-15-05-am

As far as I can tell, the only feature that is currently supported by Xcode is the named closure parameters, demonstrated above. Here’s what the schema looks like from Swift’s point of view:

<!-- In general, template parameters with whitespace 
   discussion should not be emitted, unless direction 
   is explicitly specified. Schema might be more strict here. -->
  <choice>
    <element name="ClosureParameter">
      <optional>
        <ref name="Abstract" />
      </optional>
      <optional>
        <ref name="Parameters" />
      </optional>
      <optional>
        <ref name="ResultDiscussion" />
      </optional>
      <optional>
        <ref name="ThrowsDiscussion" />
      </optional>
      <optional>
        <ref name="Discussion" />
      </optional>
    </element>
    <element name="Discussion">
      <ref name="BlockContent" />
    </element>
  </choice>

Unadopted Swift enhancements don’t end there. There’s further work to be done to support changes provided by Swift but not picked up on by Xcode. Here are examples from the Swift language¬†change log and from Swift proposal SE-0111:

  • Three new doc comment fields, namely¬†- keyword:,¬†- recommended:¬†and¬†- recommendedover:, allow Swift users to cooperate with code completion engine to deliver more effective code completion results. The¬†- keyword:¬†field specifies concepts that are not fully manifested in declaration names.¬†- recommended:¬†indicates other declarations are preferred to the one decorated; to the contrary,¬†- recommendedover:¬†indicates the decorated declaration is preferred to those declarations whose names are specified.
  • This proposal introduces two new document comment fields,¬†MutatingCounterpart¬†and¬†NonmutatingCounterpart. These replace the roles of the former¬†mutable_variant¬†and¬†message¬†arguments. Under this scheme,¬†@discardableResultwill not use arguments. Documentation comment fields will, instead, supply usage recommendations in both directions.

Swift From Two to Three on iTunes and Leanpub

screen-shot-2016-09-15-at-9-06-29-am

Swift 3 is a major, breaking language change. Are you ready to make the jump? Let “Swift from Two to Three” help you along the way. From migrating your code, updating your style, and adopting new Swift features, this book ushers you into the newly refreshed language. Learn what changed, why it changed, and how you can update your code using this hands-on guide that covers all the major difference with plenty of examples and insight.

Now available from iTunes and Leanpub. Buy all three and save 30%.

Sending a sincere thank you to everyone who helps support my blogging and independent writing by purchasing books.

Finishing up Swift From Two to Three

twothreescaled

I’m getting close to wrapping up my latest little self-published Swift book. Like Playground Secrets and Documentation Markup, the book will be available on iTunes and LeanPub. It’s written¬†for anyone who has stayed in Swift 2.3 so they could keep shipping code but who now is looking to move towards Swift 3.

Here are some sample pages to give you a feel for what’s coming up.

As always, if you have any feedback or requests, please let me know. Does this sound like a book you might purchase? I’d love to hear from you.

Thanks again for all the support you give me, my blog, and my books. It’s appreciated beyond measure.

Review: Man, I hate Cursive by Jim Benton

Screen Shot 2016-08-21 at 7scaled.58.09 PM

If you like good, stupid, subversive humor (and who among us does not?), consider pre-ordering Jim Benton‘s “Man, I Hate Cursive”.

Due out this October, this cartoon collection for “People and Advanced Bears” is silly, witty, and laugh-out-loud fun. It offers¬†a collection of Benton’s more popular strips from Reddit, “shining a light on talking animals, relationships, fart jokes, and death” according to the book’s promo copy.

I liked it a lot. Admittedly, some of the humor leans¬†off-color: it’s the kind of book you gift¬†a friend, a fellow programmer, a geek, but not maybe your mom unless your mom is a friendly programmer geek, in which case, she’ll enjoy the laughs.

You’ll probably like it too, in which case, it’s excellent for leaving around on coffee tables if you’re a little uptight or¬†in bathrooms, where its¬†humor might¬†be more appreciated during those deeply ¬†philosophical times when you forget your iPad and don’t subscribe to the Ikea catalog.

Screen Shot 2016-08-21 at 7.57.05 PM

At just under a hundred pages, the book¬†ended way too soon for me. ¬†“Man, I Hate Cursive” is available for pre-order on Amazon ($11.07 paperback, $9.99) and will be published on October 18, 2016.

NetGalley provided me with a free copy of the book for this review.

Swift Developer’s Cookbook Content Update #1 is live

I’m pleased to announce that the Swift Developer’s Cookbook content update has gone live. My editor writes:

Hi Erica,
The Web Edition has been updated and is live (I just registered my book and checked it). To access the Web Edition, anyone who purchases the book can just register it at Informit.com. After doing so, the Web Edition will show up on the Account page.
You can feel free to post a blog entry, tweet, et cetera that the first update is live.
Thanks,
Trina

Pearson’s¬†Content Update Program is brand new. It has experienced¬†significant challenges over the past months: floods in Chennai followed by a massive downsizing at Pearson, which caught the CUP point people in the layoffs. With luck, further updates will not take so long. It’s a very weird time to be in the technical writing business.

If you’ve purchased a copy of the book from any vendor, you should be able to register it with InformIT and receive access to the refreshed material. If you have any difficulties, ping @InformIT on Twitter.

Book Review: Post this Book

cover86411-medium

Sometimes there is such a thing as too many memes and kitten gifs. David Sinden and Nikalas Catlow breathe fresh air into social media feeds with #Post This Book  (Sourcebooks, $9.99, complete with built-in hashtag). This sweet inspirational book is suitable for tweens, teens, and even college students. It offers 150+ pages of ideas for tweeting, tumbling, facebooking, vine filming, and instagramming.

It’s not a book you read. Each page offers¬†one or two ideas along with quick descriptions. You turn pages, you get inspired, you go out and express yourself using¬†those ideas. Everything is simple, but well tweaked to connect with an audience and inspire a conversation.

Screen Shot 2016-06-26 at 7.56.15 PM

With kids and social media, there’s¬†always tension between privacy and free expression, appropriateness and creativity. I’m pleased to say that in the¬†time I spent flicking through pages in this book and showing examples to my kids, that I didn’t find anything objectionable or problematic.

The ideas in this book allow kids involve¬†themselves in public fora (using anonymous nicks and handles, of course, because, you know, reality). At the same time they’re¬†exploring their imaginations, they’re not crossing¬†inappropriate lines that are so prevalent on Tumblr and beyond.

Screen Shot 2016-06-26 at 8.17.05 PM

This book’s projects offer positive ways to test the waters of social media.¬†Whether brainstorming how to “zombify something unlikely”, videoing time lapsed “tidying up”, or creating “a tabletop obstacle course”, all the projects I read through were inspirational and fun.

#Post This Book¬†goes on sale on July 1st from Sourcebooks. It’s a perfect “gift” book — for just 10 bucks, you can probably buy a small tin of colored pencils or markers to pair with it without breaking the bank.

I was given early access to the manuscript for this review courtesy of NetGalley and Sourcebooks.

Playgrounds Part III

Screen Shot 2016-06-14 at 2.49.47 PM

I have to call it a day, but I’m really happy with what I’ve learned about authoring Playground Books for iOS today. (I’m less happy learning about how to completely reset Xcode — either reboot your system or hop into terminal, do a ps -ax and grep for Xcode and then kill anything with the name in it.) I thought I’d share a few lessons.

If you are going to author for iOS, start with a new playground created from scratch in Xcode 8 rather than modifying an existing one. If you cannot import PlaygroundSupport,¬†reboot your computer. If it doesn’t show up and you’re still using XCPlayground (now deprecated), you’re doing it wrong.

Understand that the Swift snapshot on iOS 10 is older than the Swift snapshot in Xcode so don’t expect to use really recent evolution implementations:

Screen Shot 2016-06-14 at 2.37.05 PM

I ended up implementing my own sequence functions to make my code work.

The easiest way to get started is just to AirDrop a normal playground.

Screen Shot 2016-06-14 at 3.09.40 PM

It will open automagically in Playgrounds for you. When you transfer books, you have to choose “open in Playgrounds” from the AirDrop menu.

If you want to author a Playgrounds Book before tomorrow’s session, just customize¬†a blank¬†document (download¬†at your own risk). My blank book is a one-pager, and you can tweak the Contents.swift file in¬†Blank.playgroundbook/Contents/Chapters/Document1.playgroundchapter/Pages/Blank.playgroundpage.¬†There are manifests at every point along the way, try not to mess them up otherwise the book won’t open.

When authoring pages, either in a normal playground or playground book, you can annotate them to omit details that would otherwise clutter the interaction space or should not be visible to the reader. In my Spirograph playground (download at your own risk), I use special mix of normal playground markup (I have a couple of books that cover this markup format: my Doc Markup book and my Playgrounds book) and these new keywords:

  • Use #-hidden-code¬†and #-end-hidden-code¬†to exclude code from the reader’s view.
  • Mark editable areas with #-editable-code¬†and #-end-editable-code, and if you like you can add a note to the opening tag.
  • To simplify code completion, you can globally omit code completion #-code-completion(everything, hide)¬†and then choose which selectors to present, as I do in the following sample. You see this in the above screenshot, which offers one-tap access to just¬†three customization points for my spirograph.
/*:
 **Spirograph:** Play around.
 
 - Note: The default values are:
 * minor: -3.0
 * offset: 130.0
 * color: .black()
 
 */
//#-hidden-code
import UIKit
import PlaygroundSupport

public var color = UIColor.black()
public var minor = -2.0
public var offset = 130.0

public func setMinor(_ value: Double) { minor = value }
public func setColor(_ value: UIColor) { color = value }
public func setOffset(_ value: Double) { offset = value }
//#-end-hidden-code
//#-code-completion(everything, hide)
//#-code-completion(identifier, show, setColor(_:), setMinor(_:), setOffset(_:))
//#-editable-code Tap to enter code
setMinor(-3.0)
setColor(.black())
setOffset(130.0)
//#-end-editable-code

//#-hidden-code
let liveView = UIImageView(600, 600, backgroundColor: .white())
PlaygroundPage.current.liveView = liveView
liveView.image = spiroImage(
 size: CGSize(width: 600.0, height: 600.0),
 samples: 4096, minor: minor, offset: offset, color: color)
//#-end-hidden-code