Tutorial articles

[hoylen]

Here are several tutorial articles.

Hopefully, it will help satisfy some of the demand for documentation (e.g. #190).

They are in the tutorials subdirectory instead of the "docs" subdirectory (as suggested in

130). The name "docs" is too easily confused with "doc" used by dartdoc, and people will be forever trying to remember which is which.

I've also updated the README to discuss using the registry separate from which import approach to use, since they are related but orthogonal topics. In the "Registry vs without registry" section, I've kept the paragraph from the original README.

At the bottom of README are links to the tutorials. I don't know how to make hyperlinks to Markdown files work properly in all contexts (e.g. on GithHub master head, when viewing a different version/branch on GitHub, when checked-out locally dartdoc generated locally,, on pub.dart, and with older releases on pub.dart). So I've simply hard coded the URLs to the latest version on the GitHub master branch. That's not ideal, but I don't know of a better way.

[richardheap]

These look great. One very minor issue throughout is one of Dart style to stay under the 80 character line wrap. Dart's redundant trailing comma is used frequently to force formal params into a column. For example, from the RSA sample:

  if (rsaVerify(
    rsaPair.publicKey,
    tamperWithData(bytesToSign),
    signatureBytes, // this extra comma here helps the formatter
  )) {
    print('fail: signature verifies when data was modified');
  }

[hoylen]

Thanks Richard, that redundant-comma trick is useful to know.

For the time being, I don't think this affects any of the code in the MarkDown articles -- so let's leave it the way it is. That example is only in the test code under the examples directory, which aren't supposed to be a normative part of the tutorials.

_It would be nicer if dartfmt can automatically do this, rather than requiring the programmer to manually insert redundant-commas (and to remember to manually remove them if the code changes to be under 80 characters and they are no longer needed)._

[richardheap]

Indeed - nothing to change right now. Just a heads up for the future.

Actually, you find you start leaving the redundant commas in as the parameter column style has been popularized by Flutter - particularly with named parameters - so is very common throughout the Dart corpus.

Thanks for these awesome tutorials.

[hoylen]

I would appreciate it if someone who understands Pointy Castle checked them for correctness, before including them.

I've never used Bouncy Castle before and have pieced the articles together from experimentation and resorting to looking through the Pointy Castle source code. The aim is to save myself and others from ever having to do that again.

[stevenroose]

This is amazing work!! Very much appreciated! I skimmed over it, but I haven't really used PC in many years myself either, so I'd have to go check the source code for everything myself too. I'm personally inclined to merge this as is and if small errors come up, they can be fixed. These are very valuable resources!

Also, given that we're in the process of moving this repo to the Bouncy Castle project, @dghgit do you prefer we wait with this until the move?

[bcgit]

Do the merge now, it will probably be smoother for @hoylen if you do. I've had to write again about setting up the mirror, so we haven't published anything yet. @hoylen May I assume you do not have any issues with this project being migrated over to the Bouncy Castle license?

[hoylen]

Correct. I don't have any issues with the project migrating over to the Bouncy Castle license.