adiaryマニュアル

Windows版では adiary.exe をWindowsサービスに登録するプログラムが公開されています。

• 汎用EXEファイルWindowsサービスラッパー
• 使い方
• オプション指定の例
• その他
• バグ報告等

汎用EXEファイルWindowsサービスラッパー

• 実行ファイル（Downloadをクリック）
• ソースコード
• ライセンス：GPLv3 or later

adiary_service.exe はadiary専用のアプリケーションではなく、汎用のサービスラッパーとして製作しています。このプログラムを使用することで、任意のEXEファイルをWindowsサービスとして起動できます。

• 同じフォルダにある、実行ファイル名から「_service」を削除したものを起動ターゲットとして使用します。
• ターゲット起動時のオプションは、サービス登録時のオプション（引数）をそのまま使用します。

使い方

adiary.exe と同じフォルダに adiary_service.exe を配置します。 adiary_service.exe を実行すると、サービスに登録します（そのままサービスが開始されます）。サービスに登録されると、Windows起動のタイミングで、adiaryがバックグラウンド起動するようになります。

もう一度実行するとサービスから削除します。

サービス登録することで、ユーザー権限ではなくシステム権限でadiaryが動作することになります。セキュリティ面には十分ご注意ください。

オプション指定の例

adiary.exe を「-p 8888」オプション付きでサービスに登録したい場合は、adiary_service.exe でサービスを登録する際に「-p 8888」オプションを付けて起動します。

サービス登録時に付いていたオプションを、そのままサービス起動のオプションとして使用します。

その他

• 内部的に「sc」コマンドを呼び出してサービス登録をしています。
• サービス停止時、起動したプロセス（adiary.exe等）にCTRL-Cを送信し、それでもプロセスが落ちないときに「プロセスkill」を実行しています。
  • 孫プロセスまではkillしていないので、CTRL-Cで終了しないアプリでは、孫プロセスが残る可能性があります。
• サービスとして起動されたかどうかは、カレントディレクトが.EXEファイルの存在するディレクトリと等しいかどうかで判定しています。等しい時は通常起動判定になります。
  • もっと良い判定方法があれば誰か教えて。

バグ報告等

adiaryのバグ報告と同じようにお願いします。

Ver3.30から、reStructuredText で書かれた記事をエクスポートして、そのままブラウザ上から Sphinx で処理（make）することが可能になりました。これにより、adiary を Sphinx統合環境CMS として利用できます。

• 利用条件
• 設定と注意
• 使い方
• その他
• conf.pyの変更

利用条件

• adiaryが動作する環境。
• Sphinxがインストールされた環境。
• adiaryの管理者権限アカウント。

Windowsとminiconda（Anaconda）環境でも動作確認しています。

サーバが Debian系 ならばSphinxは以下のコマンドで導入できます。

apt-get install python-sphinx

設定と注意

使用するためには、adiary.conf.cgi に以下の設定が必要です。

<$v.special_export = true>

この設定より、adiary管理者権限のあるアカウントでのみ、Sphinx連携機能が使えるようになります。*1

SphinxがWeb上から呼び出されることを想定していないため、この設定はセキュリティーホールとなる可能性があります。アカウントの管理には特に注意してください。

使い方

reStructuredText(RST)を使用して、adiary内に記事を執筆します。記事をコンテンツ設定すると「コンテンツkey」+「.rst」が出力ファイル名になります。

執筆した記事を、Sphinxで処理するために、管理メニューから「ブログの管理」→「エクスポート」に進みます。

「reStructuredText出力」を開き、「Sphinxで処理する」のチェックを入れます。

出力ボタンを押すと .rst ファイルが出力され、Sphinxが起動しそのファイルを処理します。

その他

• アルバム上に貼り付けた画像等は、そのままSphinxでの出力に反映されます。
• csv-tableディレクティブで外部ファイル参照時、アルバム内のファイルを files/table.csv のように参照すればSphinxでも問題なく取り込めます。
• Sphinxの拡張ディレクティブや拡張Roleには今のところ対応していません。必要がありましたら理由を添えてご要望ください。前向きに検討いたします。

conf.pyの変更

一回目の出力時に「sphinx-quickstart」が呼ばれ、「conf.py」が自動的に生成されます。

必要に応じてサーバにsshで入るか、sftpで接続するなどして、conf.pyを書き換えてください。

慎重に互換性を調べながら実装したので忠実に再現されていると思いますが、バグがありましたらご連絡ください。

• 非互換の仕様
• ディレクティブの非互換
• roleの非互換
• 何も処理しないディレクティブ
• 非対応ディレクティブ
• fileオプション

非互換の仕様

• リスト要素にブロックが存在するとき、その要素のみ<p>タグが出現する。
  • Sphinxでは、並列要素および親要素すべてが<p>タグにより段落処理される。
• 脚注は書いた場所ではなく、セクションの終わりに出力される。
• 複数の参照元がある脚注/引用でも、ラベル自体にリンクを生成する。
• 脚注/引用参照は明示的リンクを生成する（オーバーライドできない）。
• 脚注/引用参照でリンクラベルを参照した際はエラーを出力する。
• 無名リンクの参照数と定義数が一致しないとき、一致する分だけリンクを出力する。
• 同じラベルのリンク宣言が複数ある時、同じURLを示していてもエラーとなる。
• 埋め込みリンクで定義した参照名が重複した場合、エラーとなりリンクを出力しない。
• 置換定義の中で許可されないインラインタグ（脚注参照等）がある場合も、置換定義を有効とする。
• 無効なエイリアスまたは循環参照しているリンク定義も、本文には何も出力しない。*1

その他、使用タグはHTML5準拠で適当に変換してあります。

ディレクティブの非互換

• ファイル参照時、アルバム内のファイル以外は参照できない（image::等）。
• 「note:」や「WARNING:」等のタイトルを翻訳せず英字のまま出力する。
• image:: リンクtargetが見つからず、altもないとき、空文字ではなくファイル名に対してエラーを出力する。
• code:: 未知の言語を指定してもエラーにならない。
• math:: 引数があっても式番号を出力しない。*2
• csv-table::
  • delim, quote, escape に使用できるのは1byte文字のみ。
  • delim, quote, escape のいずれかに同じ文字を指定した場合エラーとする。*3
  • urlオプションは無視される。
• contents::
  • backlinks 非対応*4
  • 出力すべき内容がない時でも、空のdivやタイトルが出力される。
• sectnum:: 存在する場所以降にのみ影響する。
• raw:: htmlのみ対応。urlオプションは無視される。

roleの非互換

• code:: 未知の言語（language）を指定してもエラーにならない。
• :pep: :rfc: の省略形roleを使っても、リンク文字を<strong>に入れない。
• :raw: オプションにformat指定がエラーになっても、エラー結果を本文に出力する。*5

何も処理しないディレクティブ

オプション等はチェックされるが、出力に影響しない。

• header
• footer
• meta
• title

非対応ディレクティブ

使用するとエラーになる。

• line-block
• list-table
• target-notes
• include
• class

fileオプション

• imageディレクティブや、その他ディレクティブでのfileオプションは、アルバム内の参照のみ許可しています。
• ファイルパスを files/ で始めると、アルバム内の参照と解釈し置換します。
• アルバムの外のファイルを参照することは（../path/ や /path/ 等を使用しても）できません。

• ディレクティブ宣言
• ディレクティブオプション
  • class指定
• image
• figure
• code
• math
• unicode
• cvs-table
• contents
• sectnum
• header, footer
• target-notes
• class
• default-role
• role
• roleディレクティブ（role定義）
  • classの挙動

ディレクティブ宣言

• ディレクティブのtypeに許可される文字は以下のとおり。

  半角英数字および語中に含まれるハイフン、アンダースコア、ピリオドで構成された大文字・小文字を区別しない単語。連続した「ハイフン、アンダースコア、ピリオド」は互いに連続してはいけない。

  • ディレクティブに全角文字は使用できない。*1
• 不正なtype宣言の場合、ディレクティブとみなされない（コメントとして処理される）。
• 「::」の手前にスペース1つまでは書いて良い。
• ディレクティブはトップレベル要素で終わる。

ディレクティブオプション

• オプション名もオプションの値も大文字・小文字を区別しない。
• オプションの値が列挙されている場合、空の値を持つオプションはエラーとなる。
• オプション名部分に日本語文字等を書くと、Pythonごと落ちる。
• オプション名部分は「\」エスケープが有効

  	:o===pt--i\\=on=: これはオプション 
  	:no-option\: オプションではない 
  	:na\ m\e: nameオプションと解釈される
  	: name : オプションではない
  

• オプション後に、オプションではない引数があるとエラーとなる。

  .. topic:: www
  	:class: eeee
  	error-string
  

• classオプションは class="" 属性に展開される。
• nameオプションは id="" 属性に展開される。
  • nameはリンクターゲット名となる。
  • nameと他のリンクターゲット名が重複した場合「Duplicate explicit target name」エラーとなる。
  • nameに使用できない文字（記号等）や全角文字が含まれる場合、その部分をハイフン(-)ひとつに置き換える。（例）:name: xx@yy!!!zz → id="xx-yy-zz"
  • name中のバックスラッシュは評価されない。
  • name中の連続したスペースは1つのスペースに置き換えられる。

class指定

• スペースで区切ることで、複数のクラスを指定できる。
• 半角英数以外の文字が1つ以上連続した場合、ひとつの「-」に置き換えられる。
• クラス名の先頭にある1つ以上の半角英字以外の文字は除去される。
  • スペースで区切られたクラス名それぞれについて判定される。
• 大文字の半角英数は小文字に変換される。
• これらの処理の結果、クラス指定が空文字となった場合や、そもそも値が空の時はエラーとなる。

image

• 置換定義の image の align は top/middle/bottom のみ使用できる。
• 置換定義ではない image の align はfigureと同一の仕様になる。
  • align の left/right はfloatオブジェクトとなる。
  • align の top/middle/bottom は指定するとエラーとなる。*2
• width/height には小数を書いても良い。
• scale は整数のみ。0でも良い。
• target が見つからずエラーになった場合、altの文字列に対するリンクエラーを生成する。
  • alt文字列が指定されていない場合は、空文字に対するリンクエラーを生成する。

figure

• <div class="figure" style="width:XXXXX">といったタグで展開される。

code

• 未知の言語を指定するとエラーになる。
• 引数に2つ以上（の言語）を指定するとエラーとなる。
• number-linesオプションは負数でも良い。

math

• classオプションは使用できない。
• 引数は単に content の手前に展開される。
• 本文部分に「\\」を含む時、本文部分は以下に展開される。

  \begin{split}
  本文
  \end{split}
  

• 引数がある場合は以下に展開される。

  \begin{align}\begin{aligned}
  	引数部分 \\
  	\begin{split}
  		本分部分
  	\end{split}
  \end{aligned}\end{align}
  

  • このせいで、本文に \begin{eqnarray} 等があるTeX数式の表示に失敗する。
  • 引数があると、引数部分に式番号が出力される。
  • オプションがあるとたとえ空でも引数があるとみなされる。
  • mathディレクティブで引数（やオプション）を書くのは止めたほうが良い。
• 引数のみの場合は単に「\[ 引数 \]」に展開される。
• 引数も本文もない場合は、空の数式div環境が作られる。

unicode

• 指定された文字は、概ね実体として展開される。
• 置換対象の前後にはスペースが必要。
• 置換対象の前後にあるスペースはいくつでも除去される。
• 「..」によるコメントより後の行は（オプションを除き）無視される。

cvs-table

• escape, delim, quoteに空文字を指定すると、Pythonごと落ちる。
  • スペースを指定する場合は U+20 等と記述する。
• escape, delim, quoteオプションにすべて同じ文字を指定できる。
• escape, delim, quoteオプションはheaderオプションには効かない。
• escape文字を指定した場合でも、quote文字2個を連ねる（""）エスケープは有効。
• widthsオプションが指定されているとき、headerオプションを含めて最大カラム数がwidthsで指定した個数と同じでなければならない。
  • 超えても、少なくてもダメ。
• widthsによる幅指定は、整数の%表記（四捨五入）に変換される。
• headerオプションには複数行記述できる。
• header-rows, stub-columnsには負数を指定できない。
• header-rows, stub-columnsよりもデータが大きくなければならない。
  • 2行のテーブルでは、header-rowsは1か0しか許されない。
  • stub-columnsが1のとき、headerオプションを除くすべての行でカラムが2つ以上存在しなければならない。カラムが存在すれば中身は空でも良い。

    .. csv-table:: これはダメ
    	:stub-columns: 1
    
    	aaaa, bbbbb
    	cccc
    
    .. csv-table:: これは大丈夫
    	:stub-columns: 1
    
    	aaaa, bbbbb
    	,
    

• quoteが終わった直後の文字は、headerオプションを除き行末か「,」でなければならない。

  .. csv-table:: エラーになる
  
  	"aaaa" , bbbb
  

contents

• depthに負数を指定するとエラーになる。
• depth=0 と 1 は同じ結果（トップレベル要素のみ表示）となる。
• backlinks 省略時は entry と同じ。
• 複数のcontentsディレクティブがあるとき、backlinksはそのタイトルエントリーに対して「最初の none でないもの」が有効
• localが指定されていない場合、デフォルトタイトルとして「Contents」が展開される。
• localを指定すると、localクラスが足される。
• セクションが存在しない文章の最初でlocalを指定すると、クラス以外はlocalを指定しない場合と同じ結果。
• 出力すべき内容がない時、タイトルもdivも出力されない。

sectnum

• 存在する場所にかかわらず、そのファイル全体に影響を及ぼす。
• 複数存在する場合、存在する数だけ同じ処理が行われる。
• start, depth共に負数を指定できる。
• depthが1以下の場合、トップレベル要素のみ作用する。
• prefix, suffix内の記法はエスケープさ、「\」もそのまま出力される。

header, footer

• htmlには何も出力されない。

target-notes

• 有効なリンク参照をすべてfootnoteのように出力する。
• 複数ある場合は、複数のリンクとバックリンクを出力する。

class

• クラス名等がなぜか出力される。挙動が意味不明。

  .. class:: class-name
  .. class:: class-name2
  
  	てすと
  

  <dl class="class">
  <dt>
  <code class="descname">class-name</code></dt>
  <dd></dd></dl>
  
  <em class="property">class </em><code class="descname">class-name2</code></dt>
  <dd><p>てすと</p></dd></dl>
  

• Sphoinxのマニュアルによれば、rst-class を使えということらしい。

  デフォルトドメインに class ディレクティブが存在するため、このディレクティブはそのままでは使用できません。そのため、Sphinxでは、 rst-class という名前で再定義しています。
  

default-role

• 何も指定していない場合 :title: がデフォルトとなる。
• その場所以降、次の default-role が出てくるまでの間のリテラルに対して有効。
• 空のroleを指定した場合、デフォルトのrole（:title:）が選択される。
• 未知（未定義）のroleを指定した場合、default-roleの指定自体が無効となる。
  • その直前に指定されているものが、有効となる。
  • 未定義のroleを指定して、後からそのroleを定義した場合も、同じ挙動（無効）となる。

role

• role名が規定の文字列でない場合、roleと認識されない。
  • 「ロール名は英数字と内部に独立した『- _ + : .』」
• role名は、すべて小文字に変換され参照される。
• roleは :role:`xxx` 形式であること。以下は無効。

  - :strong: `文字`
  - :strong:``文字``
  - :strong:文字
  

• roleと参照 _ の両方があるとエラーになる。

  - :strong:`エラー`_
  - :strong:`エラー`__
  - `エラー`:strong:_
  - :strong:`エラー`:strong:__
  - `有効な参照`_:void-role:
  - `有効な参照`__:void-role:
  

• :pep: :rfc: は省略形を使うと、リンク部が太字（strong）になる。
• :pep: :rfc: は整数以外を指定するとエラーとなる。ただし負数を指定しても良い。
• 存在するroleでエラーが発生した場合、その部分は何も出力されない。
• :raw: の format は大文字小文字を区別する。*3
• :code: で未知のlanguageを指定するとエラーになる。

roleディレクティブ（role定義）

• 新しいrole名が正しくない場合エラーとなる。
• 継承元role名が見つからない場合エラーとなる。
• emphasisやstrong等、組み込み済のroleも再定義できる。
• role名を大文字でも定義できるが、参照できないクラスになる。*4
  • 継承元としても参照できない。以下は最初の定義以外すべてエラーとなる。

    .. role:: UPPER
    .. role:: err (UPPER)
    
    :upper:`test` :UPPER:`test` :err:`test` 
    

• 自分自身を継承元として再定義できる。

  .. role:: strong ( strong )
  	:class: XXX
  

• 置換定義中にrole参照が存在した場合、置換定義を行った時点でのroleを参照する。
  • default-roleについても同様。置換定義を行った時点でのdefault-roleを参照する。
• class以外の（存在する）オプションの正当性は、定義時ではなく使用時（評価時）に評価される。

classの挙動

• classオプションを指定しない場合、定義role名がclassオプションに指定されたものとみなされる。
• もしrole名がclass名として許されない形式（数字のみ等）で、classオプションも指定されていない場合、role定義自体がエラーとなる。

  .. role: new-class
  .. role: 123456
  
  :new-class:`新しいクラス`
  → <span class="new-class">新しいクラス</span>
  

• role が元々classを持っている場合（literalやmath等）、classオプションを指定するとそのクラスを追加で出力する。
  • 多重継承した場合、継承元のオプションは一切引き継がない。
  • オリジナル（大元）のroleやclassは引き継ぐ。