このテキストは、Scala初学者がScalaを学ぶためのテキストである。ドワンゴの新入社員Scala研修のために作成されたものが、日本のScalaコミュニティに寄贈されたものとなる。
このテキストのコンパイル済み成果物は次の場所から入手可能である。
- HTML版:https://scala-text.github.io/scala_text/
- PDF版:https://scala-text.github.io/scala_text_pdf/scala_text.pdf
- EPUB版:https://scala-text.github.io/scala_text/scala_text.epub
Scalaの初学者にScalaを習得してもらうために利用してもらうことを想定。
Scalaの初学者で、少なくとも1つのプログラミング言語に触れた経験があることを前提としている。
Markdownで記述し、HonKitで静的サイトにしてGitHub Pages上に公開。原稿ファイルは src/
以下に配置。
以下のコマンドで初期設定を行うことが可能。
git clone https://github.com/scala-text/scala_text
cd scala_text
npm install
原稿のビルドは以下のように行う。
ビルドされたページはhonkit/_book/index.html
から見ることができる。
sbt textBuildHtml
その他にも、テキストの校正、リンク切れの確認などを行うコマンドが定義してある。 コマンドには全てtextというprefixが付いているので、どのようなコマンドがあるかは補完から知ることができる。
# 日本語の校正
sbt textLint src/introduction.md
# リンク切れ確認
sbt textLinkTest
# mdocのビルド
sbt textBuildHtml
# 全ての検査を実行した後にビルド
sbt textBuildAllWithCheck
mdocという、Scalaコードを書くと、そのコードのチェックや 元のソースとなるmarkdownファイルから、実行後の出力を付け加えたmarkdownに変換してくれるツールを使用している。 Scalaのコード例をテキスト中に書く場合は、使用可能な箇所では出来る限りmdocを使うこと。 mdoc自体の具体的な使用方法は、mdocのREADMEなどを参照すること。
book.jsonで記述されているreadme, summaryはhonkitのビルド時に特別視される。 具体的には以下のような構成になっている。
- readme: Introductionとして本の先頭ページに配置される
- summary: 本のページ遷移情報に利用される
summaryを更新しないとページを追加しても本に反映されないので注意が必要。
textlintでルールを設定し原則としてこれに従う。 ルールの一例を以下に挙げる(自動でチェックされない項目は適宜レビューなどで修正を行う)。
この文書では次のように見出しを運用する。
- 記事のタイトルを
h1
として、タイトル以外では使わない - 見出しレベル(
#
)は1つずつ増加させる- 例
h2
の後にh4
がきてはならない
- 例
地の文に現われる括弧は原則全角にする。 また、括弧の使用は例などなるべく短かいものにとどめ、 長くなる場合は脚注を使用する。
強調などで半角の"
を使うことがあるが、この記事では原則全角の“
と”
を用いる。
ファイル名やディレクトリ名は原則_イタリック_にする。
「〜でした。」
のように、句点をカギ括弧の終端で使わず、「〜でした」
とする- 括弧を文章の終端で用いる場合、
〜です。(〜)
ではなく〜です(〜)。
- 文章の最後が括弧になる場合、脚注を検討する
- 括弧内の終端では句点を打たない
- 括弧内で句読点を使うような文章になる場合、括弧ではなく脚注を検討する
- 三点リーダには
…
を用いて、原則2つ続けて使う - 原則として、中黒
・
を三点リーダの用途で使ってはならない
HonKitではEPUB形式にもビルドすることが出来る。
依存ライブラリとしてCalibreが必要なのでインストールする必要がある。
またcalibreの中のebook-convert
やnpmライブラリであるsvgexport
にPATHが通っている必要があるので注意。
Macでのインストールは例えば以下のようになる。
brew cask install calibre
ビルドは以下のように行うことが出来る。
# svgexportにPATHが通っている必要がある(PATHを変更したくない場合はnpm install -g svgexportでも可)
PATH=node_modules/.bin:$PATH
sbt textBuildEpub
- scala_textのissue欄およびpull requestへ
- scala_textのissue欄へ
本文書は、CC BY-NC-SA 3.0
の元で配布されています。ただし、直接の利益を得ることを目的としない研修などに利用することは可能とします。 直接の利益というのは、研修自体を実費以上の金額で提供する行為を指します。社内でのScala研修などは一般的に 直接の利益を得ることを目的としないので、断りなく使っていただいて構いません。