crystal-jp / introducing-crystal Goto Github PK

若干個人的なものなのですがどこかにまとめておかないと忘れそうなのでここに書いておきます。

• 文章内に直接書かれたコードがコンパイルできるものがある気がするので修正する。
• 各著者の紹介ページを作る
• あとがきを作る
• 公開用のWebページを作る

動作確認や make test で使うのも含め、現時点の最新バージョンの 0.24.1 で統一する方針でよいですか？

本で使われているバージョンに関する記載が第1章の項目に入る予定です。

この本がどのバージョンのCrystalを前提にしているかもここに入る。

技術書典4では「Crystalの入門書」のようなものを頒布したいと考えています。
これは、今までの本は実質的にCrystalのtips集のようになっていたのですが、そもそもCrystalのことをよく知らないのにtips集を最初から買っていく人はなかなかいないだろう、ということを技術書典3やコミケへの参加で感じたためです。
もちろん部数を捌くことが重要なのではなく、即売会を通じてCrystalの知名度を高めることが参加の目的だとは思っているのですが、手元に置いてもらえた方が強く記憶に残せるはずです。
また、本の内容も三回も続けると各著者のネタが枯渇してきて、初回・二回目と比較すると全体的な分量が少なくなっています。なので、一度まとまった内容の本を作ることで知識を整理できるのではないかと思います。

このissueでは次のことを議論・確認したいと思います。

• 本の内容は「Crystalの入門書」で良いか？
• 本の大まかな見出しと、その内容を決める。
• 執筆者の募集。
• どの部分を担当するかを決める。

また、参加する人はまずこのissueのコメントで宣言してください。
その際にどの部分が書けそうかも一緒に教えてもらえるとありがたいです。

(この辺りからは適宜更新します。)

今のところ考えている目次です。

1. はじめに(10ページくらい？)
   • Crystalとはどのような言語か(「Ruby並に書きやすくてC並に速い」など)の説明。
   • LLVM, Rubyとかも少し説明が入るといいかも。
   • この本がどのバージョンのCrystalを前提にしているかもここに入る。
   • Crystalの情報を知るためのリンク集。
     • Crystalの公式サイトの説明。
     • gitterとか、crystal-jpのSlackとか。
     • shardまとめたサイトとか。
2. インストール(10ページくらい？)
   • Crystalのインストール方法。
     • Macでの方法とUbuntuでの方法、Bash on Ubuntu on Windowsを使えることも説明したい。
   • エディタなどの紹介もここでする。
3. 構文(20ページくらい？)
   • Crystalの構文をRubyとかと比較しながら説明していく。
   • 基本的なプログラミングの知識は仮定してOK。(クラスとは？　オブジェクト指向とは？　みたいな説明はいらない)
   • 各構文についてサンプルコードを一つくらいの粒度。
   • 後置whileはRubyにはあるけどCrystalにはないねー、みたいな。
4. shards(10ページくらい？)
   • shardsの基本的な使い方、パッケージの作り方など。
   • fizzbuzzパッケージでも作る？←fizzbuzzだと依存が無くて微妙‥‥
   • テストの書き方もここで説明する。
5. ツール(5ページくらい？)
   • crystal tool formatとかcrystal tool expand辺り。
   • エディタとの統合も説明してほしい。
6. Web開発(20ページくらい？)
   • 最初にいくつかWebフレームワークを紹介。
   • それから、どれかのフレームワークで簡単なWebアプリケーションを実装。
     • ルーター、DBアクセス、テストなど込み込みがいいです。
7. CLI開発(20ページくらい？)
   • 簡単なCLIアプリケーションの作り方を‥‥。
   • Crystal標準のoption_parserパッケージとか、その他のサードパーティーのライブラリの使い方を説明するとか。
   • あまり考えてない。
8. 歴史(3ページくらい？)
   • @nob-suz さんに丸投げする感じにしたい。

全体で100ページくらいのつもりです。

また、他に次のようなことを考えています。

• Crystalのバージョンが上がってもコードが壊れていないか確認できる仕組みを作りたい。
  • 具体的には、コードと記事を分離して、記事からはコードをincludeする形にする。
  • コードのコンパイルや、コードに対してテストを書いておいて、CIを回す。
  • この辺の仕組みはボクが色々考えます。
• ↑の都合で、今のところ記事のフォーマットを何にするかは決めていません。pandocとかasciidocとか色々試していきたいと思います。

/cc @at-grandpa @msky026 @arcage @karupanerura @5t111111 @TobiasGSMollett @nob-suz

CLI ビルダーの
https://github.com/mrrooijen/commander
をinstallしているのですが、crystal tool format をすると、

Error: '/path/to/techbookfest4/08-cli-development/projects/myecho_commander/lib/commander/spec/commander_spec.cr' has syntax errors

と落ちてしまいます。libディレクトリ配下は format の対象にしないほうが良さそうですね。

ちょっと対策考えます。パッチ思いつく方は大歓迎です！

今はこのリポジトリはtechbookfest4という名前ですが、作ろうとしてる本は技術書典に限らず、Crystalをこれから始める人にとって役に立つものになると思います。

そこで

• リポジトリ名を「crystal-introduction」とか「crystal-for-beginners」みたいな感じにする
• 本の内容をWebページとして公開し、自由に見れるようにする
• 内容のメンテナンスを続けていく・内容を加筆していく

ことができたらいいな、と思っているのですが、どうでしょうか？

shard のインストールには現状 shard install と crystal deps の2パターンが利用できます。

Shards の章では後者を選択しましたが，それぞれの章で shard install と crystal deps が混在していると読者の混乱を招きそうです。

可能であればどちらかに統一すべきではないかと思いますがいかがでしょう？
また，もし統一するとしたらどちらを採用しますか？

ちなみに，私が後者を選択したのは

• 読者に提示するコマンドの数は少ない方が良いのではないか
  crystal コマンドはどうしても出てくるので

• Crystal コンパイラのサブコマンドとして実行できることで，標準のパッケージマネージャである点が強調されるのではないか

といった辺りが理由でした。

@crystal-jp/introducing-crystal

著者紹介のページを作りたいので、このissueに下記の内容をコメントしてもらいたいです。

• 本に載せたい名前
• GitHubのアカウント名
• Twitterのアカウント名
• 自己紹介(100字くらい？)

よろしくお願いします。

Related: crystal-lang/crystal#6942

次バージョンのCrystalで、crystal initした際のテンプレートが一部変更されたので記事中で参照しているプロジェクトもそれに合わせて更新したいです。

合わせて、単にshardsコマンドで依存関係をインストールするように指示していたのがshards installコマンドを使うように変わったので、記事でもそちらに揃えようかと思っています。

/cc @at-grandpa @msky026 @arcage

「Crystal」の表記ついて、下記が考えられますがいかがでしょうか？

• Crystal
  • 一番一般的。READMEやdocs等もこの表記であり、説明に出てくる他の言語の名前（Rubyなど）もこの表記。
• crystal
  • 次にありそうなのがこれかと。
• CRYSTAL
  • 公式ロゴは全て大文字。

個人的には、「読み物としては Crystal ですよね」なんですが、一応認識を合わせたほうが良いと思ったのでissueたてました！

実際に困ってるのは (, ) 半角括弧を InvalidSymbol が許容してくれないので、文中に foo(arg) みたいな記述をしたいとき引っかかるってやつ。

シンボル設定をしてしまうと多分それはちょっと違うので、例外を設定したりすることはできないだろうか？？