perl6 の pod


20160105

直ぐに修正が入りそうな挙動もあるので注意。特に、`Declarator blocks` の部分とか。

http://design.perl6.org/S26.html

- `perldoc MODULE` は、 `p6doc MODULE` に。
- `perldoc CODE.pl` は、 `perl6 --doc CODE.pl` でも[^1]。
- `__DATA__` トークンは、 `=finish` に。
- 記載方法は以下の4つの方法に。
	1. Delimited blocks
	2. Paragraph blocks
	3. Abbreviated blocks
	4. Declarator blocks
		- `#|` は、 `Smart::Comments` の一部機能的使用方法を想定しているのか？
		- それにしちゃあ、ブロック毎って訳でもないし、、、
- コードは、 `UTF-8` 想定との事で、日本語プリントさせても大丈夫（？）
	- `utf8flag` に絡んだ一連の問題とかは無い？

[^1]: `p6doc` でも閲覧可能。こっちは強制改行が入ったり、テーブルが崩れたりする。

##### バージョン
```
$ perl6 -v 
This is Rakudo version 2015.12 built on MoarVM version 2015.12
implementing Perl 6.c.
```

##### p6doc に関して

`rakudobrew` でのインストールした `perl6` 環境下[^2]。

[^2]: インストール自体の説明は割愛。

私の場合。

```
$ which panda
${HOME}/.rakudobrew/bin/panda
$ panda install p6doc
$ ln -s ${HOME}/.rakudobrew/moar-2015.12/install/share/perl6/site/bin/p6doc ${HOME}/.rakudobrew/bin
$ ${HOME}/.rakudobrew/moar-2015.12/install/share/perl6/site/bin/p6doc-index build
$ p6doc Type::Hash    # 見られるか確認
$ p6doc -f push       # 検索出来るか確認
```

環境変数を飛ばすまでもなく、`pod` は閲覧出来たが、場合によっては、`$RAKUDOLIB`　もしくは `$PERL6LIB` にパスを通す必要があるかも知れない[^3]。

[^3]: `$RAKUDOLIB` は、現在のバージョンでも公式にサポートしているのだろうか？


## code

```perl:perl6.pl
use v6 ;

=begin pod

=head1 first perl6 document

初めてのperl6でのドキュメント
=head1 一つ目の方法:

perl5 like pod.

"Delimited blocks" って紹介されてる。
=end pod

say "1: =begin pod (perl5 pod like)." ;

=begin comment

コメントも、この通り。
=end comment

say "2: =begin comment (perl5 pod like)." ;

=for head1
二つ目の方法:
"Paragraph blocks"
段落末まで自動的に、pod に渡されて、
終了指示を出す必要が無い。

say "3: =for head1 paragraph." ;

=for comment
コメントパラグラフは
コメントとして扱われる。
--doc では現われない。

say "4: =for comment paragraph." ;

=head1 三つめの方法: "Abbreviated blocks" ま、for を省略して一行に書くって感じ？

say "5: =head1." ;

=comment コメントも、、、

say "6: =comment." ;

=begin pod
=head1 四つめの方法:

Declarator blocks

http://design.perl6.org/S26.html

では言及されていないけど、#`{} もこれの一種だろう。
流し読みしただけだけど、`#|` のみが .WHY 対応？

=end pod

say '7: ' ~ #|{
  7: これもコメント
} '#|{.' ;

# 何げにヤダヤダ実装してんの？ それともrange？
# sub foo { ... }
# ↑これをアンコメントすると
#    1. `perl6 perl6.pl` で、 #2. が効かなくなる。
#    2. `perl6 --doc perl6.pl` で、#1.のコメント部分がプリントされる。
#    3. `perl6 --doc perl6.pl` で、`sub foo()` とプリントされる 
#       その代り、`class Foo` とプリントされない。
# 3は意図せぬ挙動だろうな、、、

say '8: ' ~ #={
  8: これもコメント
} '#={.' ;                    #1.

say '9: ' ~ #`{
  9: これもコメント
} '#`{.' ;

class Foo {
    say '10: Foo class.' ;
}

say Foo.WHY.contents;         #2.

say $=finish ;

say $=pod[0].contents[1].contents;

# say $=pod[1].contents[1].contents;
# はダメっぽい。

=finish
11: __DATA__ は、=finish に。
```

## 通常実行

```
$ perl6 perl6.pl
1: =begin pod (perl5 pod like).
2: =begin comment (perl5 pod like).
3: =for head1 paragraph.
4: =for comment paragraph.
5: =head1.
6: =comment.
7: #|{.
8: #={.
9: #`{.
10: Foo class.
[7: これもコメント]
11: __DATA__ は、=finish に。
[初めてのperl6でのドキュメント]
```

## ドキュメント読むとき

```
$ perl6 --doc perl6.pl
first perl6 document

初めてのperl6でのドキュメント

一つ目の方法:

perl5 like pod.

"Delimited blocks" って紹介されてる。



二つ目の方法: "Paragraph blocks" 段落末まで自動的に、pod に渡されて、 終了指示を出す必要が無い。



三つめの方法: "Abbreviated blocks" ま、for を省略して一行に書くって感じ？



四つめの方法:

Declarator blocks

http://design.perl6.org/S26.html

では言及されていないけど、#`{} もこれの一種だろう。 流し読みしただけだけど、`#|` のみが .WHY 対応？

class Foo
7: これもコメント
```


### 上記以外のメモ。

- インデント可能
- テーブルとかコードとか。

```test.txt
=for table :caption('DNA')
    rep      means
    ==       =======
    A        adenine
    C        cytosine
    G        guanine
    T        thymine

    =for code
$ perl6 perl6.pl
```

```
$ perl6 --doc test.txt
'DNA'
rep  means     
A    adenine   
C    cytosine  
G    guanine   
T    thymine   


    $ perl6 perl6.pl 
```