Erica Sadun

Where technology meets something or other

Archive for the ‘Books’ Category

Overdrive, DRM, and Adobe Digital Editions

The Denver library recently migrated its ebook system. Incidentally, it wiped all my holds in the process and I have no idea what stuff I was waiting to read. So if you recced anything over the past 6 months and it was popular, chances are that I need you to remind me to read it again.

Anyway, today my first hold came in on the new system. I downloaded the ascm file as usual, double clicked, and when Adobe Digital Editions opened, I got this on my screen:

Yikes. I immediately assumed it was time to update Adobe Digital Editions. So I did that. And I tried opening it up again and I got this:

While you can see the massive UI improvements Adobe has made to its signature Mac e-reader, I was still rather stuck.

So I googled for E_ACT_NOT_READY and “IO Error on Network Request” and tried all the things that didn’t work until I found something that did work.

What didn’t work:

  • Clearing out ~/Documents/Digital Editions
  • Creating a new ~/Documents/My Digital Editions
  • Quitting and restarting the apps
  • Rebooting

What did work was reauthorizing my computer. Dunno why. I deauthorized and then reauthorized — good thing I remembered my username and password because it has been a gadzillion years since I did this last — and boom it finally worked.

(If you want to remove authorization by hand, toddle over to ~/Library/Application Support/Adobe/Digital Editions and kill the activation.dat file.)

Anyway, Scott Sigler’s “Alive” is now on my system ready for reading. I have no idea why I put this title on hold and who recommended it to me. I hope it’s good. Here’s finger’s crossed that this is a good read.

Swift Style vs ProseLint: The Smackdown

ProseLint is great. As I’m writing a book about style and linting, it’s natural to try to lint the book that lints your programming. In using this tool, I’ve encountered some amusing “lint fails” that I’d thought I’d share.

ProseLint vs Nil Coalescing: “hyperbolic.misc ‘`??`’ is hyperbolic.” Winner: Swift Style.

ProseLint vs discussion of Forced Unwwrapping: “leonard.exclamation.30ppm More than 30 ppm of exclamations. Keep them under control.” Winner: ProseLint. Any forced unwrapping, even in a discussion about forced unwrapping, is an obvious fail. Save the kittens, drop the !’s.

ProseLint vs Meaningful Variable Names: “typography.symbols.multiplication_symbol Use the multiplication symbol ×, not the letter x” Winner: Swift Style. As Freud said, sometimes an letter  “x”  is just a letter “x”. (Or was that Groucho Marx? I forget.)

ProseLint vs “Use American English Spelling” rule: “consistency.spelling Inconsistent spelling of ‘color’ (vs. ‘colour’)” Winner: Swift Style. When writing for a global audience, prefer “color” to “colour”. (See? I did it again. — B. Spears)

Winner? Forget the points. It’s ProseLint. This summary doesn’t include the great catches made and fixed, like excessive use of “very”, repeated word detection, etc. Great tool, check it out.

Buy a book: Swift Style

esswiftscaled

I’m happy to announce that Swift Style has gone into beta release at  the Pragmatic Bookshelf. My book is now ready for sale as part of their beta program. This program gives you early access to the book’s material as I work on it.

Be part of the writing process. Beta access enables you to offer feedback as I finish writing:

Before a book gets to the final, ready-to-publish state, it normally looks quite rough. It will have hundreds of typos and grammatical errors. It’s likely to have technical errors that would normally get corrected in a final read-through by reviewers. And it’ll certainly look fairly ugly—we don’t do any layout work until just prior to sending a book to the printer, so there will be widows, orphans, text split across page turns and so on.

As you find mistakes or technical errors, if want to argue for or against a style rule, or you’d like to submit an enhancement suggestion,  click the Report Erratum link on the book’s home page. If you have any in-depth feedback (either positive or negative) that goes beyond the scope of the erratum page, drop me an email. Enable notifications so you receive an email whenever the book updates.

Swift Style: Beta Book

Self-Published Books

Thank you for your support!

Writing updates and asking “Is Github my new Dropbox?”

I’m testing the waters for the first time in using Github rather than Dropbox to coordinate a private project. I’ve used private repos before for material that wasn’t meant for public consumption or to stage material that would then later be released openly but this is the first time I’m testing it out for material that’s substantially not code.

I’ve been meaning to give this a go ever since Github changed its policy to allow unlimited private repositories. I used to be limited to just five in total and I guarded those slots carefully. Under the new policy, I have repos to burn. Today was the first time that I set one up to use in this way.

It feels odd using Github instead of Dropbox as I’m so used to my Github content being primarily open, and Dropbox requiring explicit permissions. Have you tried using Github this way? And how have your experiences been?

The reason I’m testing out Github is that I’m updating iOS Drawing for Swift. I have a week or so to burn while I’m waiting on editorial feedback and tech review on my Swift Style title from Pragmatic. It will take another 4-6 weeks for Addison Wesley to release iOS Drawing rights back to me but I figured I’d get a head start writing some test chapters and get some early feedback about the project while I had some downtime.

I’ve used Dropbox for years to provide material to beta readers and gather their feedback as well as to coordinate material on multiple machines. In testing out Github, I was inspired by Pragmatic’s workflow.

Pragmatic uses a delightfully retro SVN version controlled interactions between editors and authors. (I’ve had to create an SVN/git cheatsheet to remind myself how to SVN all the things.) Pearson/AW in contrast uses Basecamp to manage projects. Basecamp offers a lot of great team features including messaging, calendars, email updates, and so forth, and I’ve been quite happy with it.

Book projects tend to be hefty, especially those with lots of illustrations and sample code but Github has generous file policies. It imposes a 1GB repo limit, 50 MB file warnings, and 100MB file limits.  These are far beyond what I’d need.

I’ve recently changed my overall personal workflow, having been inspired by conversations with editors at O’Reilly. O’Reilly has been pioneering modern, flexible content using markup source. I took my lead from them. (I’m personally using CommonMark instead of AsciiDoc and pandoc instead of Atlas, but the ideas are similar.)

Pandoc has been a pure delight. Even if CommonMark offers less nuance and control than Microsoft Word (however ugly MS Word is, it has power and all the ugly but practical features you need for professional publishing), pandoc allows me to push from manuscript to book in seconds.

I don’t have to use Calibre to build epub, pdf, and mobi output. My code examples are readable and my tables of contents are perfect. I’ve written a bunch of command-line utilities that automate the process of building the ebooks, zipping up archives, and storing copies in a Dropbox beta folder. I still use Dropbox to provide early reader access.

I built Swift Style‘s first draft using this workflow, writing in MacDown, an open source macOS Markdown editor. I like MacDown’s side-by-side display but, to be honest, for material of any size, it has no way to keep the text and output in sync, especially once you introduce illustrations.

If I find some time, I’ll probably try to mess with the source to add this functionality because once you drop the ability to see your edits as you add them, the utility loses a lot of its charm but that’s a project for another day.

In the meantime, I’m just getting settled into Github for this project. A lot of my work steps are similar: I start by pulling and wrap up by pushing but now it’s to the repo, and not to Dropbox. Github offers more version control than Dropbox’s undelete functionality and I don’t have the same worries about filling up my quota.

I’m curious: Are you using Github for non-coding projects? And how has that worked out for you? Did the DNS incident a few days ago make you rethink? Or are you committed to this kind of collaborative tool? Let me know. Thanks!

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.