k3kaimu / d-manual Goto Github PK

ライセンスには、
「このページを含め、原則としてd-manualのすべての記事(ソースコードを含む)にはCC BY-NC-SAを適用します。
」とありますが、ソースコードを再利用しようとした際にこれがプロジェクトの意図しない結果になる可能性があります。
ドキュメント自体のライセンスはそのままでよいと思うのですが、ドキュメント中のソースコードはほかのソフトウェアライセンス（GPLライセンスなど）のコードと混ぜて利用することができません。このことが、GNUやクリエイティブ・コモンズジャパン、creativecommons FREQUENTLY ASKED QUESTIONS (英語)にも同じようなことが書かれています。具体的には、ソフトウェアで利用することを想定してライセンスが設計されていないので、二次利用が難しくなるということです。
そこで、ドキュメント中のソースコードはオープンソースライセンスで利用許諾することを提案します。

fumikony@e88639c#commitcomment-5242999

リンクを貼るか、どうにかして簡単に参照できるようにする必要がある。
それか、日本語を変更するか。
(修正は、遅ければ2月下旬になるかもしれません)

途中までをgistに投稿しました
https://gist.github.com/k3kaimu/5791265

現在のd-manualを閲覧する方法としては、唯一GitHub上でmarkdownを閲覧できるだけである。
GitHubにはGitHub Pagesという優れた機能があるので、これを活用すべきである。

また、PDFやEPUBなど他のフォーマットでも配布できるような態勢を作らなければいけない。
そのためには、Markdownの文法をPandocに統一し、Pandocから全て生成させる方法が良い。

結論として、文法をPandocスタイルに改め、PandocによってGFM含めた他のフォーマットへ変換したものを提供すべきである。
また、HTMLやMarkdownとして生成したものについてはGitHub Pagesで閲覧できるようにすべきである。

途中までですが、Gistに投稿しました
https://gist.github.com/k3kaimu/6018917

共用体の使用機会はほとんど無いので、少し触れる程度に書きます。

具体的には、配列の次の章として文字と文字列操作の章を構成し、関数の章の次の章としてメイン関数と入出力に関する章を書きます。

• 「文字と文字列操作」の章の追加
  • std.string
  • std.algorithm
• 「メイン関数」の章の追加
  • std.getopt.getopt
• 「ファイルと標準入出力」の章の追加
  • std.stdio
  • std.file
• readme.md, answer.mdの修正(章題, 章番号など)
• 前後の章の文章の修正(「おわりに」などの節で咬み合わない場所の修正)

途中までをGistにあげています。

https://gist.github.com/k3kaimu/5891381

書きます

https://github.com/k3kaimu/d-manual/blob/master/main.md#%E3%82%B3%E3%83%9E%E3%83%B3%E3%83%89%E3%83%A9%E3%82%A4%E3%83%B3%E5%BC%95%E6%95%B0%E3%81%A8stdgetopt

の実行例に

$ dmd io_main
$ ./io_main foo bar
[".\\test.exe", "foo", "bar"]

とありますが，./io_main の出力結果の args[0] の値は "./io_main" になると思います．
手元にWindows環境が無いため確認できていないのですが，確認できましたら修正していただければ嬉しいです．

goto文やラベル, switch文やcaseについて言及。

switch文ではfinal switchについては軽く触れるか触れないでおく。
final switchについてはenumの項で記述予定

現在のd-manualでは、特に語句についての規定はなく、例えばreturn valueを「返り値」もしくは「戻り値」のどちらで書いても良い。
しかし、その場合には読者が混乱する可能性がある。

よって、必要最低限の語句に関する規定と、訳語一覧が必要である。

boolと評価される式の以下の一文ですが

文字列型だったら、文字列の長さが0であればfalseになります。

現状は配列がif文やassertの条件式に出現する場合、真偽値はarr.ptr !is nullによって評価されるため、上記記述は正しくありません。この挙動自体は公式forumでもよく議論に上っており(最近も大きなスレッドが立ってたはずです)、将来的にはarr.length != 0に変わるかもしれませんが、今のところはこの一文は削除したほうが無難だと思われます(言語の隅をつつくようなことはこのドキュメントの目的ではないと思うので)。

記述を削除した穴を埋めるものとしては、ポインタやクラス参照の場合についてのサンプルがいいかなと思います。

例えば，hello_world.md の最初の実行例では，

$ rdmd helloworld

とファイル名から拡張子を省いたものを rdmd の引数として使っていますが，writefとwriteflnの解説部分では，

$ rdmd helloworld.d
1 : 2
2 : 4

のようにファイルを拡張子付きのまま rdmd に引数を渡しています．

どちらでも意図したとおりに動作するため間違いではないのですが，どちらかに統一したほうが混乱が少ないと思います．

/+
個人的には拡張子付きのほうが好きですが(tab でファイル名補完できる)，統一されていればどちらでもいいと思います．
+/

関数のリテラルとラムダ で、以下の様なサンプルコードが出てきていますが

void function() //f1 = {},          // これはNGみたい
                f2 = {;},           // こっちはOK
                f3 = (){};

void delegate() d1 = {},
                d2 = {;},
                d3 = (){};

NGケースを受け付けるようにするためのIssue 11661がgit-headで修正されましたので、2.065から上記コードが全て通るようになります。

• 記事内で「strong purity」の例としてあげられている bar 関数は strong pure ではなく constant pure のはずです．
  • http://qiita.com/9rnsr/items/84fca796f3826dd5b03c
  • DIP 等で weak/constant/strong pure の分類に関する記事を見つけられませんでした… 公式にまとまった記事ってありましたっけ…
• 「constやinによって書き換え不可能なことを明示しておけば、その関数は強い純粋性を示す」と「強い純粋関数が返す返り値はすべての修飾子付き型へ暗黙変換可能」という記述に従うと以下のコードが動いてしまいます．

// 引数が in で修飾されているので strong pure
const(int[]) foo(in int[] arr)
{
  return arr;
}

void main()
{
    auto ar = [1,2,3];
    immutable a = foo(ar); // 任意の修飾子を付けても大丈夫?
    ar[1] = 3; // !!
}

• 現在暗黙変換ができるのは2.063のchangelog にある，new/dup された配列だけです．

  DIP49のUnique Expressionの定義に，(まだ提案段階ですが)暗黙変換可能な式の定義があります．
  pure 関数が Unique Expression 中で重要になることは確かだと思うので，暗黙変換の例の後ろで「将来 Unique Expression で暗黙変換できるように，可能であれば関数をpure関数として定義しましょう」のような記述を追加するのがいいかもしれません．

• weak pure な関数でも，返り値を暗黙変換できるものは考えられるため，purity の種類の記述を残す場合は，ユニットテストのしやすさに関する記述を追加するのがいいと思います(weak pureな関数では返り値と引数の両方を確認する必要がありますが，constant/strong pureな関数は返り値の確認だけで十分です)．

loop.mdのforeachの箇所を修正する必要あり。