TODO

このページには、doc.tir.ne.jpをメンテする上で必要な各種の残り作業を列挙します。

作業が完了したりTODOを諦めたりしたら、後で確認する意味があるものは「終了したTODO」に移動させ、そうでないものはそのまま消していきます。

優先TODO

gitit.conf内の情報を参照できるHSTMPTransformプラグイン作成

  • これを行わないと、docとintraのテンプレ統合ができない為。
  • 書式(prefix等)を考える必要がある。もしくは書式を考えずに、直に「repository-type$repository-type$」のように反映してもよい(既存のStringTemplate変数と衝突がない場合のみ)
    • StringTemplateの書式を見て考える事→サンプル
    • https://sites.google.com/site/klovelab/Home/hstringtemplate を見ながら、代数データ型変数($config.hoge$書式)とする方針とする
    • なんか意外と面倒なようなので、他の情報(path等)から判別する方向に変更。とにかくdocとintraの区別をStringTemplate変数からできればokなので。

これが完了次第、次のTODOも行う事

docとintraのテンプレートの統合

  • 上記の通りだが、StringTemplateでは「変数が定義されている/されていない」以上の論理処理はできない為、少し工夫がいる
    • 具体的には、プラグインを少し書き足して、プラグイン内にてgitit.confのportやwiki-titleを見て「docなのかintraなのか」を判定した上で「$is-intra$」等の新しい名前のフラグ変数を設定するようにすればよい(変数名についてはもう少し考える必要あり)
  • ついでに後述のplugins, static等も統合する事

githubにテンプレート類を保存する

  • 具体的に保存する対象は、plugins, static, templates、それから /etc/init.d/gitit-daemon あたり。これらは現状docとintraでバラバラなので先に統合する必要がある

本番環境であるdocのsitenav.stにも、簡易リンクメニューをつける

  • 内容を考える事

必要な成果物ページを作成

  • 「いわゆる人工知能(仮)」を完成させる為に必要な各モジュールの一覧、および、それのプロトタイプ成果物とかを木構造で示したり具体的にどんなの作るのかの概要とか書いたりするページを作る事。
    • とりあえず、androidアプリとしてワールドシミュレータをまず作る予定なので、その成果物ページと、開発環境構築手順ページは必要。

用語/文献指示記法プラグイン作成

  • まず先に、用語ページ文献ページをそれなりに進めましょう
    • 子ページのwikinameの命名ルールを考える必要がある。というのは、これら「用語」「文献名」は日本語になるのは間違いないが、ここでのwikinameの命名ルールは「なるべくurl encodeされない文字を使う」というものだった為。
    • 「正式な用語名/文献名を、メタ情報のtitleのところに入れる」という仕様とする。
  • doc.tir.ne.jp に文書を追加していく上で、これらの子ページにリンクを貼る事は多くなる為、簡単にリンクにできる記法を考え、それを実現するプラグインを作成する。
    • あとで記法を考える事。
  • プラグインの実装について
    • 上記の通り、実際の用語/文献名は日本語だが、wikinameはそうでない為、このプラグインは、指定された日本語名から実際のwikinameを解決してリンクを貼る必要がある。
      • これは線形検索して探しても別にいいと思う。これによる負荷が問題になるなら、キャッシュを有効にすればよい

仕訳帳インターフェースを作成する

  • 仕訳帳を書く必要がある!!!
    • 経費の算出および将来に作業時のコスト見積りの為に
  • コストを金額および時間として記入する
    • これらの情報はページのメタ情報欄に入れておき(cost: および benefit: )、あとで合計したりできるようにする
    • 単位は円でいいのか?
      • 可能なら金額の単位は通貨以外の何かにしたいが、現在のところ候補なし
      • 今のところ、なんとなく「円なら単位なし」「ドルや時間の場合は単位付き」というルールになっている。本当にこのルールで続けて良いかどうかは考える必要あり
        • なんでこうなったかというと、要は「円」だけマルチバイト文字なので抵抗があるから(「\」はフォントによってバックスラッシュになるので微妙)
          • 「10000 yen」とかでいいのでは。どうせ時間は「2 hours」とかだし。ドルも「100 dollars」でいいと思う
            • ドルが複数形だと円も「1000 yens」になる気もするが…
              • どうやら「yenは、複数形もyen」という理屈らしい
    • 利益として得た分の記入方法も考える事
  • 手軽に記入できる必要がある
    • コマンドラインから、および、メール経由、がベスト
  • gititの1ページになるようにする
    • wikinameの形式は「/journal/2012/08/28/14:29」みたいにする(仮)
    • これに伴い、「カテゴリ一覧ページを逆順にするプラグイン」を作る事も考える
  • plugins/PigLatin.hs を参考に、costを合計するプラグインも作る事
  • 以下の仕様を追加/変更する事を考える
    • 支出/収入の種別(現金、カード、銀行、等々)
      • これはメタ情報のところにも追加する必要あり
  • メタ情報のラベルを変更するかも
    • 会社的/会計的な意味での「利益」は「profit」らしい
    • 会社的/会計的な意味での「支出」は別に「cost」で問題なさそう
  • 「支出」から「投資」を別枠にすべきか考える
    • 「investment」らしい

メタTODO

全般的なTODO

さくらインターネットへのサーバ代金支払いを仕訳帳に書く

  • 10月から課金再開との事なので

残りページ/項目作成

「rssについて」ページ

  • 現状のrssがあまり役に立たない為、何らかの解説文が必要に思える
    • 単体のページにせずに、どこかのページにちょろっと書くだけでもいいと思う
  • 以下の内容を書く
    • 現状では「フィード購読(全)」は特定タイミングにまとめて大量に流れるので購読はおすすめしない、興味のあるページだけ単独で「フィード購読(単)」するのをすすめる
    • その他一般的なatomフィードについての解説など

「doc.tir.ne.jpのドキュメントのライセンス」ページ

  • あと「無保証です」「EULAっぽいもの」とかのページも必要

「doc.tir.ne.jpのドキュメント作成ルール」ページ

  • 以下のルールを決定し、仕様化する必要がある
    • 仕訳帳ルール
      • 「journalのwikinameの日時はJSTです」とかもここに書く
    • カテゴリルール
      • カテゴリ命名基準の考え直し
        • 現在のところ、カテゴリはなんとなく「英小文字のみ」のルールにしているが、これ別に日本語とかでもいいと思うので考え直す
        • しかし ParentLink.hs の現在の仕様では、カテゴリの各ページは、「/categoryName」みたいなリンク判定になる。これを利用したいなら、wikinameと同じルールにするのがいいと思う
      • 以下の件のメモ書き
        • 今は、「技情研ネット関連のコンテンツ」は/tir.ne.jp/配下に設置する、というルールでやっているが、これはカテゴリの方がいいかどうか考える → とりあえずこれに限っては、カテゴリでない方がいい、という事になった
          • 一覧を見た時に畳み込まれて、ちらかる事がない、という理由
          • 他の技術情報(/gitit)とかもディレクトリ掘るべきかも
    • wikiname命名基準の確定
      • wikinameは可能な限り、URL encodeされない文字だけで構成する、とか
      • wikinameに「'」を使ってはいけない、等
    • タグルール(案)
      • 元々、pandoc変数(「$hoge$」のようなタグ)に利用可能な文字は「英数」「`-`」「`_`」との事。よって追加するタグもこれに準拠する。 - pandocが標準で提供しているpandoc変数は英小文字のみで構成されたものばかりとなっている。 - gititが標準で提供しているpandoc変数も、ほとんど英小文字のみで構成されているが、例外が一つだけあり、何故か「\$pageUrl$」だけlowerCamelCaseになっている。
      • writerマクロ(012-09-01 22:23:37.168512 JSTのように、本文内に書くと別の文字列に置換されてから保存されるマクロ)は、全て「英大文字」のタグとする。これによって上記のpandoc変数と区別する。
      • readerマクロ(通常のpandoc変数同様、表示時に別の文字列に置換される)は、上記のpandoc変数と同じく、英小文字はじまりのタグとする。英大文字は使わない(lowerCamelCase等にはしない)方針とする。記号もなるべく使わないようにする。
      • TODO: 上記で「pandoc変数」と呼んでいるものの名称を考えなおす(大元の由来はHStringTemplateなため)
    • その他、ページ記入上でのルール
      • コミットログルール
        • 「追記」「added」だけではあまりに意味がなさすぎるので、せめて「○○(セクション名)に追記」「added to XXX」と、いじった場所名ぐらいは書く事
          • 特に、mediawiki等にある部分編集機能がgititにはないので、これを書く事でかなりコミットログが分かりやすくなると思う

「山田のロードマップ」ページ

  • 「収入に余裕が出てきたら、新しい山田のノートPCを買う」「新しい椅子か座椅子を買う」とかをどこかに書きたい
  • 最初はロードマップページに書く事を考えていたが、それはよくないだろう
  • かといって、単独でページを作る程でもないとも思う
  • /tir.ne.jp/members/yamada の子項目もしくは子ページでいい

「スポンサー/パートナー募集」ページ

  • 「スポンサー」は、金銭(あるいはそれ以外の資本でも可)による支援をしてくれる個人/団体
    • 可能なら、技情研ネットの方針に口を出さない人が望ましい(つまり「株主」的な立ち位置ではない)
  • 「パートナー」は、技情研ネットが技術/サービス/労働/情報/権利を無償もしくは低価格で提供する代わりに、技情研ネット側も相手の技術/サービス/労働/情報/権利を無償もしくは低価格で提供してもらう、という約束/契約をした相手
    • 本来なら「技情研ネットのこれと、あなたのこれが等価です」みたいな前提条件でしっかり契約をすべきだが、現状ではそこまではできないので、「今回はこの労働をこれだけ安くしますから、将来なにかあった時そちらも何か安くしてください」みたいな口約束レベルにならざるをえない、が、現状ではそれでよいものとする
  • 「これを読んでもあまり募集する気がなさそうに見えるかもしれませんが、それは山田が人づきあいが嫌いだからです。すみません」というのも書く事

gititページの「導入手順」

  • ghcおよびcabalモジュール導入あたりのメモを忘れない内に書く

各cgiを作成

  • deploy.cgi(intraからdocへ内容反映、プレビュー(diff形式?)あり)
  • push.cgi(githubかどこかの外部リポジトリにpush、シェルからも実行可能)
    • この時のpush元は、内部編集用ではなく、公開側からとする事

技情研ネットの各サイトのメンテ

  • Initializrベースでhtmlを書き直す。
    • その時に一緒にcss考え直す
  • サイトの見た目は「協力者/支持者を集める」事に微妙に影響する為、それなりに真面目に行う事。
    • 以下のサイトみたいなのがいいと思う。
      • ニャンパス株式会社の技術ページ。動いたりしなくていいので、こういうデザインにしたい。
      • Galois社のサイト。海外で一般的な会社のデザインみたいにしたい。あとここの会社は方針とか参考にできる部分が多い。あとで取り入れられそうなものは取り入れる事。

cssのカスタマイズ

技情研ネットのバナー作成

  • 200x40サイズのもの。内容は、三匹のアイコンのみ。「技情研ネット」とかの文字もなし。

以下のメモを整形してどこか適当な場所に移動させる

ghcいれなおし手順
laymanの設定を行う
layman -S
layman -a haskell
layman -s haskell
なんかエラーが出る時は、一度layman -d haskellしてやり直す事
(haskell-updaterがlaymanの中を書き換える為、git pullがうまくいかなくなってしまう様子)
vim /etc/make.conf # CABAL_EXTRA_CONFIGURE_FLAGS=--enable-shared
emerge -av ghc
emerge -av haskell-platform
emerge -av haskell-updater
haskell-updater
emerge -av cabal-dev
なお、パッケージがおかしくなった時は、 haskell-updater -c -u を実行する
また haskell-updater -c -u --all で、全パッケージの再構築ができる

構築ポリシーおよび手順

  • hackageにあるモジュールの内、gentooにあるものはcabalで入れずにemergeで入れる。
  • hackageにあるモジュールの内、emergeにないパッケージはcabalで ~/.cabal にインストールする。rootでglobalインストールはしない(これで入れてしまうと困る場面が多かった為)。
  • 上記以外で、例えば、ここで利用しているgititのように、gentooにあるけど、敢えて手動構築したいものは、一旦普通にemergeで依存物ごと入れてから–unmergeで本体だけ削除し(依存物は残し)、改めて本体を ~/.cabal に構築する
  • なお、「emerge –depclean package」で依存するものごと削除らしい。-p -vをつけて事前に確認する事!

gitit本体をいじる必要のあるTODO

このTODOの内、一般的な情報のものについては、完了後は#完了したtodoではなく、/gititに移動させましょう。

ページツールの「印刷用表示」の時に、フッタの「provided by 技情研ネット.」を出さないようにすべきか検討する

  • 今のところ、印刷時はこのフッタは消して、代わりに“?printable”を抜いた実urlを表示すべきだと思う
  • これで問題なさそうなら、そのように直す事

テンプレをいじって、 http://doc.tir.ne.jp/_activity が空の時にメッセージを出すようにする - 現状だと一ヶ月更新がないと空の表示になってしまい、ユーザに不審がられる恐れがある為。「最近一ヶ月は更新がありませんでした」程度は出したい - 調べた結果、これはテンプレだけでは対応できない。 Network/Gitit/Handlers.hs の showActivity をいじる必要がある。ここのcontentsが空の時に代替メッセージを入れるようにすればok。これはブランチ切ってパッチ化する事

ページのメタ情報を本文に差し込めるプラグイン作成

  • ほぼ仕訳帳の為の用途
    • 要はメタ情報欄と本文にそれぞれ同じ内容を書くのはよくない為(内容がちぐはぐになったら困るので)。

LastModified.hs が、過去のrevisionを見ている時でも最新ページのタイムスタンプを表示するのを直す

  • $revision$ がある時は、それを使って日時を引くようにする
    • 意外と面倒なので、$reveision$のある時はLast-Modifiedを出さないようにするだけにする事に

LastModified.hs の、 HSTMPTransform 化

  • ついでに他の問題にも対応する事

差分表示の時に一行の長さが長すぎてはみでるのをどうにかする

  • preだから。あとでcodeとbrにするパッチを作る。実際には以下のタグになっている

    <pre class="diff"><span> ... </span></pre>

ExportのSlidyを動くようにする。それができないなら「$exportbox$」から抜く方法を考える

「ページツール」の下あたりに何かの枠を入れる

  • …という案があったが、一体何の枠だったのか思い出せない、あとで思い出す事

コードブロックのインデント量がコードブロックも横幅に依存しているのを直す

  • 以下のようなコードブロックが、コードブロック内の横幅(文字数)によってインデント位置が変わる。おそらくcssで直せる。
~~~{.haskell .numberLines}
(show $ revDateTime rev)
~~~
  • 調べたところ、以下のようなタグになっていた。このクラスを調べる事。
<table class="sourceCode haskell numberLines"><tr class="sourceCode"><td class="lineNumbers"><pre>
  • 空行を入れる等して複数行にする事で、インデント量が一定になるようだ。htmlレベルで差異が出ているのかどうかは不明。

終了したTODO

rssの為に、公開側へのpush時にコミット内容をまとめる

  • 現状だと、pushした段階で大量のコミットログがrssに流れるので、それが嫌なので
  • しかしまとめると今度は編集履歴を見た時に各コミットがまざってしまって訳が分からなくなるのでは、という懸念が
    • intra側ではまざってないのでよいとする?
      • github側ではまざってるのでよくないと思う
    • 現状では、コミットログは「追記」「added」とかそんなのばかりなので、それならまざってもいいのでは
      • コミットログはちゃんと書きましょう、というルールにする事に
  • 上記により、コミット内容はまとめず、そのまま公開側に反映する事になった
  • ただし元々の「大量のコミットログが一度に流れる」という件はどうしようもないので、これについては#rssについてページを作成して、そこに注意点などを書く、という事にする

markdown記法の解説ページへのリンク追加の件

  • 日本語のmarkdown記法の解説ページ(可能ならpandoc版のもの)へのリンクを、編集画面内の左サイドバーに追加する
    • 英語版のリンクはもう入っている
    • 探したがpandoc版はなかった。
    • リンクつけるとしたら、 wikipediaのmarkdown項目全訳チートシートぐらいだが、どれも微妙な感じ
      • これを必要とするのは新しくメンバーになる人ぐらいなので、そのタイミングで入れるかどうか検討する事にする

見出しリンクの件

  • 各見出しのリンク先は#TOCだが、それよりは自分自身を指した方が便利なので変更する
    • もしくは、見出しの末尾に自分自身を指す、リンク取得用のhrefを入れておくか
    • この処理はpandocが行っているようで、gititだけでは直せないっぽいので諦める事に

*.st内における、httpからはじまるfull urlの出し方を調べ、pagetool.stのbingのところに反映

  • 調べた結果、取れるインターフェースはないようだ
    • デフォルトではhostnameシステムコールで取っている
    • どうしても取りたいなら自分でプラグイン作ってHost: ヘッダから取るしかなさそう
  • 取れないと困るというものでもないので、行わない事にする

UTC問題

タイムスタンプがUTCになっている問題は延期とする(UTCのままでokとする)。 ただし将来に対応作業を再開する可能性がある為、メモを残す。

尚、延期にする理由は「よく考えたら、あるタイムスタンプが日本の何時に書かれたものなのかパッと分かりづらいが、それが分からなくても困る人は別にいない」為。 また、万が一、技情研ネットが国際的に発展するような事になった時の事を考えると、JSTにこだわる意味もない為。

  • この修正を行うべき対象は以下の通り。
    • Network/Gitit/Handlers.hs 内の showActivity と showHistory の revDateTime のある辺り
      • リビジョン情報からUTCTimeを得て、それを単にshowしているだけ。後述の問題あり
    • LastModified.hs
      • 根本的には同上。しかしプラグインなのでバリバリに手を入れて直してしまっても別に問題はない
    • Signature.hs SignatureParse.hs Date.hs DateParse.hs
      • これは現在の日時を埋め込むので個別対応してもokだし簡単にできる
  • UTC問題の本質
    • gitのリビジョン情報内の日時にはタイムゾーン情報が含まれている。しかし Data.FileStore から得られるリビジョン情報はUTCTimeで日時を返している。そしてUTCTimeはタイムゾーン情報を含んでいない。
      • ここで可能な選択は二択。
        1. 諦めてUTC固定とする
        2. 任意のタイムゾーン(サーバに設定されているタイムゾーン)に変換する
      • 今回は前者を選んだが、後者を選んだ場合にどうなるかを記す。
        • doc.tir.ne.jp的にはJSTのみ対応でいいが、パッチとしてpull-reqするのであれば、夏時間ありのタイムゾーンにも対応させないとまずい。またpull-reqする内容が大きくなるのもよくない
        • 夏時間ありのタイムゾーン判定は面倒な事に一律で決定せず、たとえUTCであってもその日時によってタイムゾーンが変化する。これを求める方法は二つある。
          1. Data.Time.LocalTime の utcToLocalZonedTime。これはIOとして、システムにタイムゾーンを問い合わせを行う為、現状だと純粋関数で記述されてる箇所に詰め込むのが面倒。
          2. Data.Time.LocalTime.TimeZone.Series。これはIOではないが別途モジュールをインストールする必要があり、これを利用する場合はgitit.cabal等にも追加が必要で面倒。

実際にJSTにする為に書いたコードサンプルは以下になる。

  • 「元のコード」:
1
2
(show $ revDateTime rev)
                                                        
  • 「自分が書いた、IOで返す関数」:
1
2
3
4
5
6
7
8
import Data.FileStore (revDateTime)
import Data.Time.LocalTime (getTimeZone, utcToZonedTime)

revToDateTimeString :: Revision -> IO String
revToDateTimeString rev = do
  let dt = revDateTime rev
  tz <- getTimeZone dt
  show $ utcToZonedTime tz dt

provided by 技情研ネット.