Org-remarkのバージョン1.3.xのorg-remark.org日本語訳です
元の文書: https://github.com/nobiot/org-remark/blob/main/docs/org-remark.org
ライセンス: パッケージのライセンスと同じ、すなわちGPLv3.0ライセンスです

Table of Contents

TOC
COPYING
インストール
- 基本的なセットアップ
- use-packageによるセットアップ
はじめよう
使い方、機能や概念
カスタマイズ
- 行ハイライトのカスタマイズ
既知の制限
謝辞
貢献とフィードバック
Index - Features
Index - Commands
Index - User Options
GNU Free Documentation License

これはOrg-remarkのバージョン1.3.xのマニュアルである。新たなバージョンがGNU-ELPAにリリースされるまでは、バージョン1.3.xで導入された新たな機能が利用できるのはGNU-devel ELPAのみ。

最終更新日: 01 February 2024年2月1日

org-remarkを使えばテキストファイル、ウエブサイト(EWW)、EPUB電子ブック(nov.el)、Infoドキュメントのハイライトや注釈(annotate)をつけることができる。

COPYING

Copyright © 2021-2023 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and
with the Back-Cover Texts as in (a) below. A copy of the license is
included in the section entitled “GNU Free Documentation License.”

(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
modify this GNU manual.”

インストール

このパッケージは以下で入手できる:

GNU-ELPA (リリース版のみ; MELPA-Stableと同じ)
GNU-devel ELPA (リリース前のmainブランチ; MELPAと同じ)

GNU ELPAについてはEmacsならデフォルトでセットアップされている筈だ。GNU-devel ELPAを追加したければ、以下のようにURLをpackage-archivesに追加するだけでよい:

    (add-to-list 'package-archives
                 '("gnu-devel" . "https://elpa.gnu.org/devel/") :append)

基本的なセットアップ

インストールしたら以下を設定ファイルに追加するとよいだろう。

    (org-remark-global-tracking-mode +1)
    
    ;; Optional if you would like to highlight websites via eww-mode
    (with-eval-after-load 'eww
      (org-remark-eww-mode +1))
    
    ;; Optional if you would like to highlight EPUB books via nov.el
    (with-eval-after-load 'nov
      (org-remark-nov-mode +1))
    
    ;; Optional if you would like to highlight Info documentation via Info-mode
    (with-eval-after-load 'info
      (org-remark-info-mode +1))

org-remark-global-tracking-modeはファイル、ウェブサイト(EWW使用時)、EPUBブック(nov.el使用時)、それ以外にもmarginalノート(訳注: 余白や欄外のメモや書き込み)のファイルを割り当て済みのサポート対象バッファーをオープンすると自動的にorg-remark-modeをオンに切り替える。Emacsを終了してもEmacsセッションに跨りハイライト位置を正しく保つために役に立つだろう。

Emacsの初期化中に明示的にorgのロードを行っていないのであればorg-remarkには遅延ロードで行うことをお勧めする(だから上記の例には(require 'org-remark)の記述がないのだ)。org-remarkはorgも取り込むので、初期化が遅くなってしまうかもしれない。以下の例のように一部のコマンドにたいするキーバインディングをautoloadすることによって、org-remarkをロードするタイミングは制御可能だ。

候補となるようなキーバインディングを挙げておこう:

    ;; Key-bind `org-remark-mark' to global-map so that you can call it
    ;; globally before the library is loaded.
    
    (define-key global-map (kbd "C-c n m") #'org-remark-mark)
    (define-key global-map (kbd "C-c n l") #'org-remark-mark-line) ; new in v1.3
    
    ;; The rest of keybidings are done only on loading `org-remark'
    (with-eval-after-load 'org-remark
      (define-key org-remark-mode-map (kbd "C-c n o") #'org-remark-open)
      (define-key org-remark-mode-map (kbd "C-c n ]") #'org-remark-view-next)
      (define-key org-remark-mode-map (kbd "C-c n [") #'org-remark-view-prev)
      (define-key org-remark-mode-map (kbd "C-c n r") #'org-remark-remove)
      (define-key org-remark-mode-map (kbd "C-c n d") #'org-remark-delete))

use-packageによるセットアップ

Org-remarkのセットアップにuse-packageを用いることもできる。以下の設定は上述の設定例と等価な筈だ。

    (use-package org-remark
      :bind (;; :bind keyword also implicitly defers org-remark itself.
             ;; Keybindings before :map is set for global-map.
             ("C-c n m" . org-remark-mark)
             ("C-c n l" . org-remark-mark-line) ; new in v1.3
             :map org-remark-mode-map
             ("C-c n o" . org-remark-open)
             ("C-c n ]" . org-remark-view-next)
             ("C-c n [" . org-remark-view-prev)
             ("C-c n r" . org-remark-remove)
             ("C-c n d" . org-remark-delete))
      ;; Alternative way to enable `org-remark-global-tracking-mode' in
      ;; `after-init-hook'.
      ;; :hook (after-init . org-remark-global-tracking-mode)
      :init
      ;; It is recommended that `org-remark-global-tracking-mode' be
      ;; enabled when Emacs initializes. Alternatively, you can put it to
      ;; `after-init-hook' as in the comment above
      (org-remark-global-tracking-mode +1)
      :config
      (use-package org-remark-info :after info :config (org-remark-info-mode +1))
      (use-package org-remark-eww  :after eww  :config (org-remark-eww-mode +1))
      (use-package org-remark-nov  :after nov  :config (org-remark-nov-mode +1)))

はじめよう

ハイライトと注釈

一度インストールとセットアップが終われば(インストール)、簡単にOrg-remarkを使うことができるだろう。テキストの一部を選択してからM-x org-remark-markを呼び出してハイライトしてみよう。そのテキストがハイライトされる筈だ。このハイライトは範囲を対象としている。新しいバージョン1.3のorg-remark-mark-lineを呼び出せば、範囲だけではなく行全体のハイライトも可能だ。視覚的には行へのハイライト追加ではなく、バッファーのマージンにマークが追加されるのだ(デフォルトでは左マージンだがorg-remark-line-margin-sideでカスタマイズ可)。これが行のハイライトだ。バッファーの編集や閲覧を行う際にどのように表示されるかという点を除けば、範囲ハイライトと行ハイライトは同じように動作する。同じバッファーで目的に応じてこれらを併せて使い分けることができるのだ。

org-remark-modeをオンにするとメニューバーのアイテム“Org-remark”が利用できるようになる。これによりOrg-remarkのメインコマンドの発見性が向上する筈だ。Emacsのバージョン28以降であれば、マウス右クリックによるコンテキストメニューも表示できる。コンテキストメニューを有効にするには、Emacs組み込みのcontext-menu-modeをオンに切り替えればよい。

ハイライト用にマークしたmarginalノートを表示するには、そのハイライト箇所にカーソルを移動してM-x org-remark-openかM-x org-remark-viewを呼び出す。編集中のカレントバッファー左側に新たなバッファーが作成されるだろう。marginalノート用バッファーの位置はカスタマイズ可能だ(カスタマイズ用変数org-remark-notes-display-buffer-actionのドキュメント参照のこと)。

openコマンドならmarginalノートバッファーを編集できるようにカーソルが移動、viewコマンドならカーソルはカレントバッファーのままでmarginalノートが表示される。カーソルのあるハイライトに相当するエントリーだけに表示を絞るようにmarginal notes fileをナロー(narrow)する点は、どちらのコマンドも同じ。このmarginalノートは普通のOrgファイルに過ぎない。他のOrgファイルを編集する際と同じように編集して、バッファーを保存するだけでよい。

ハイライトから別のハイライトへの移動

テキストに追加したハイライトが何箇所かある際に、それらのハイライトへの移動は簡単だ。あるハイライトから別のハイライトに移動してmarginalノートを閲覧するにはorg-remark-view-nextとorg-remark-view-prevを使う。これらのコマンドはデフォルトではサイドウィンドウにmarginalノートを表示する。ハイライトのmarginalノートwww表示せず単に次または前のハイライトに移動したければ、org-remark-nextとorg-remark-prevを使えばよい。簡単にナビゲーションできるようにするには、以下のようにOrg-remarkコマンドに同じ"プレフィックスキー"を定義すればよいだろう:

C-c n o: org-remark-open
C-c n ]: org-remark-view-next
C-c n [: org-remark-view-prev
C-c n r: org-remark-remove
C-c n d: org-remark-delete

これらのキーバインディングに共通なプレフィックスキーはC-c nの部分だ。このようにキーバインディングをセットすれば、一度C-c n ]で次のハイライトを表示してそのまま]や[を使って次や前のハイライトに移動できるだろう。目指すハイライトに到達できたらoでオープン、rやdでremove/deleteできる。

自分用のハイライトペンの作成

Org-remarkにはハイライト用のデフォルトのペンがあり、更に2つのデフォルトのペンセットが用意されている:

org-remark-mark : デフォルトのハイライトペン
org-remark-mark-line: デフォルトの行ハイライト用のペン(テキスト範囲ではなくマージンにマークする)
org-remark-mark-yellow : marginalノートで"important"カテゴリに使用する黄色のハイライト
org-remark-mark-red-line : marginalノートの"review"カテゴリ、およびツールチップの"Review this"に使用する赤い波下線

Org-remarkには独自にカスタムされたペン関数を作成するためにorg-remark-createが用意されている。たとえば独自に黄色や赤色のペンを作成するために使用できる。これを行う方法についてはハイライト用のカスタムペンの作り方を参照のこと。

取っ掛かりとして必要なのはこれですべてだ。詳細についてはこのマニュアルの残りの部分、特に使い方機能や概念とカスタマイズのセクションを参照して欲しい。このセクションで紹介したコマンド以外のコマンドや、Org-remarkをカスタマイズするより多くの情報を記載しておいた。

ウエブサイトへのハイライトと注釈

テキストファイルと同じようにウェブサイトにたいしてハイライトや注釈をつけることができるのがorg-remark-eww-modeだ。これはグローバルなマイナーモードであり、追加の設定は何も必要ない。モードをオンにしてからeww-modeでウェブサイトを開いてテキストを選択、ハイライトするだけだ。基本的なセットアップについてはインストールの例を参照のこと。Org-remarkはサイトを編集する際にハイライト位置を自動的に調整しようと試みる。この機能の詳細についてはハイライト位置の自動調節とは?を参考にして欲しい。

EPUBブックへのハイライトと注釈

テキストファイルと同じようにEPUBブックにたいしてハイライトや注釈をつけることができるのがorg-remark-nov-modeだ。追加の設定は何も必要ない。モードをオンにしてからnov-modeでEPUBブックを開いてテキストを選択、ハイライトするだけだ。基本的なセットアップについてはインストールの例を参照のこと。テーブル(table: 表)のあるブックを読む場合には、ハイライト位置を自動調整する機能ハイライト位置の自動調節とは?について理解しておけば役に立つだろう。

InfoモードのInfoドキュメントへのハイライトと注釈

テキストファイルと同じようにInfoドキュメントにたいしてハイライトや注釈をつけることができるのがorg-remark-info-modeだ。追加の設定は何も必要ない。モードをオンにしてからInfo-modeでinfoノードを開いてテキストを選択、ハイライトするだけだ。基本的なセットアップについてはインストールの例を参照のこと。

使い方、機能や概念

ハイライト用のカスタムペンの作り方

org-remark-createは独自のカスタムペン関数を作成するマクロだ。Org-remarkにはデフォルトで用意された2つの追加ペンが同梱されている。自分でペンを作成する際にはそれらを参考して欲しい。

    (org-remark-create "red-line"
                       '(:underline (:color "dark red" :style wave))
                       '(CATEGORY "review" help-echo "Review this"))
    (org-remark-create "yellow"
                       '(:underline "gold" :background "lemon chiffon")
                       '(CATEGORY "important"))

マクロ: org-remark-create label &optional face properties: ハイライト用ペン関数を新たに作成して登録する。新たに作成されたペン関数は変数org-remark-available-pensに登録される。これはorg-remark-changeが選択リストとして使う変数だ。

LABELはハイライトペンの名前(必須)。ペン関数はorg-remark-mark-LABELと命名される。

選択したリージョンにたいしてハイライト用ペン関数が適用するフェイスがFACE(無名フェイスでも可)。FACEがnilの場合には、このマクロはデフォルトフェイスとしてorg-remark-highlighterを使用する。

PROPERTIESはシンボルと値のペアーからなるplist。ハイライトされるテキストはそれぞれにはノートファイルにおいて対応するOrgヘッドラインが付与されるとともに、ハイライトペンのプロパティドロワー(property drawer)に追加のプロパティをもつことができる。これを行うにはプロパティの前に"org-remark-"を前置するか、あるいは"CATEGORY"を使用する。

バージョン1.3では新しい行ハイライト用ペン関数を作成するorg-remark-createが使用できる。下記例のようにPROPERTIESパラメーターとしてorg-remark-typeにlineを指定すれば使用できる。これによりデフォルトの範囲ハイライト用ペン関数ではなく、行ハイライト用ペン関数を作成するようにOrg-remarkに指示するのだ。必須ではないがデフォルトコマンドorg-remark-mark-lineと一貫性を保つために、LABELには"line"という文字列を含めることをお勧めする。

    ;; This creates a custom command named org-remark-mark-line-alt with
    ;; face diff-hunk-header
    (org-remark-create "line-alt"
                     'diff-hunk-header
                     '(org-remark-type line))

プロパティとしてcategory(すべて小文字、シンボル)を使用しないこと。これはテキストプロパティ用の特別なプロパティであり、もし使う場合には値もシンボルにする必要がある(さもないとエラーになる)。CATEGORY(すべて大文字、シンボル)は使用できる。これを使えばmarginalノート用Orgファイルのプロパティドロワーの値をもつCATEGORYが追加されるだろう。

Emacs再起動に自動的にハイライトをオンに切り替えるには

Emacs初期化の一部としてorg-remark-global-tracking-modeをオンにするのはお勧めだ。そうすればファイルにハイライトを追加し始める前に処理される筈だからだ。

何かのファイルにハイライトを追加してからEmacsを終了、再起動するとorg-remark-global-tracking-modeがアクティブになり、自動的にorg-remark-modeがオンに切り替わるとともに、グローバルに追跡しているファイルにたいして以前のセッションのハイライトがロードされるだろう。

このグローバルマイナーモードなしでは、ハイライトや注釈をつけたファイルそれぞれにたいして、org-remark-modeをアクティブにすることを覚えておかなければならないのだ。これは非現実的な場合が多いと思う。

marginalノートを管理する方法

marginalノートファイル

ハイライト用ペン関数でテキストの一部をマークする際に、Org-remarkが自動的にmarginalノートファイルを作成する。デフォルトでは編集中のファイルと同じディレクトリーにmarginalia.orgという名前で作成される(marginalノートファイルの保存場所を変更するには、カスタマイズ、org-remark-notes-file-nameを参照のこと)。

注意すべき重要な点は、Org-remarkがヘッドラインのプロパティドロワーがハイライトを記憶するために以下のプロパティを使用することだ。

:org-remark-beg:
:org-remark-end:
:org-remark-id:
:org-remark-label:

要するにmarginalノートファイルとはOrgモードを使用したプレーンテキスト(plain text: 平文テキスト)によるデータベースなのだ。プレーンテキストデータベースなので、必要なら手作業でこれらのプロパティを簡単に編集できる。普通のOrgファイルと同じように、marginalノートファイルを直接編集できるということだ。

marginalノートファイルには、ハイライトが以下のように格納されている。複数のファイルとハイライトにたいして、ハイライトとノートを組織化するようデザインしている(Org-remarkが自動挿入するデフォルトのヘッドラインタイトルは変更可; セクションmarginalノートバッファーのヘッドラインを自分のやり方で組織化するを参照のこと)。

    * File 1
    ** Highlight 1 in File 1
    ** Highlight 2 in File 1
    [...]
    * File 2
    ** Highlight 1 in File 2
    [...]

何もノートに記述せずにmarginalノートファイルをほったらかしにしておいても問題はない。そのような場合には、marginalノートファイルのエントリーにはハイライトしたテキストの位置だけが保存されるだろう。Emacsを終了した後に再起動して同じファイルをvisitすれば、Org-remarkがこの情報をテキストをもう一度ハイライトするために使用する。

Org-remarkが自分用に予約済みの上記プロパティに加えて、あなた独自のカスタムプロパティとCATEGORYプロパティを追加できる。プロパティ名の前に"org-remark-"(または唯一の例外として"CATEGORY")を前置すれば、Org-remarkがそれらをmarginalノートバッファーのヘッドラインエントリーのハイライトにたいするプロパティドロワーに配置するのだ。カスタムプロパティはあなた独自のペン関数で定義すること(独自のペン関数の作成方法については、ハイライト用のカスタムペンの作り方を参照のこと)。

marginalノートバッファーのヘッドラインを自分のやり方で組織化する

テキスト範囲や行をハイライトすると、Orgモードを使用してOrg-remarkがmarginalノートバッファーに対応するヘッドラインを作成する。ヘッドラインのタイトルは、デフォルトではテキスト範囲の場合には選択されたテキスト、行ハイライトの場合にはその行の最初の40文字のいずれかとなる。後者に関しては最大文字より長い文字列の場合には切り詰められて、省略記号"…"に置き換えられる。40文字という最大長と省略記号はそれぞれカスタマイズ用変数のorg-remark-line-heading-title-max-lengthおよびorg-remark-line-ellipsisでカスタマイズ可能だ。

これらはデフォルトのヘッドラインの初期タイトルにすぎないので、必要に応じて自由に変更できる。たとえばEmacs Lispのスクリプトファイルで関数を定義している箇所に行ハイライトを追加するとしよう。それに対応するmarginalノートバッファーでのヘッドラインの初期タイトルは以下のようになるだろう。

    ** (defun name-of-the-function (arg)...)
     :PROPERTIES:...
     この関数は再チェックすること

これを以下のように変更するのは、特にアジェンダでヘッドラインを表示できるようにTODOアイテムとしてmarginalノートを組織化したい場合には理に適っているのかもしれない。

    ** TODO review name-of-the-function
     :PROPERTIES:...
     この関数は再チェックすること

`marginal-notes` Buffer

ハイライトにたいするmarginalノートをorg-remark-viewやorg-remark-openで表示する際には、marginalノートファイルをvisitするようなインダイレクトバッファー(indirect buffer: 間接バッファー)をOrg-remarkが複製する。デフォルトではカレントフレーム左側に、*marginal notes*という名前の専用(dedicated)のサイドウィンドウをオープンする。display-buffer関数やバッファーの名前は変更可能だ(カスタマイズを参照)。

marginalノートバッファーはカーソルのあるハイライト部分にナローイング(narrowing)して表示される

すべてのプロパティの後には、そのハイライトにたいするノートを自由に記入できる。一度ノートバッファーを保存すればテキストの抜粋(現在のところ最大200文字)が更新されて、ソースバッファーのハイライトに書き戻される。この抜粋されたテキストはハイライト上にマウスを移動した際に、Emacsのエコーエリア(スクリーン最下部)に表示されることになる。tooltip-modeモードをオンにしていれば、ハイライトの抜粋がツールチップとして表示されるだろう。

marginalノートファイルの保存場所を変更するには

marginalノートファイルの場所はユーザーオプションorg-remark-notes-file-nameによって指定される(デフォルトでは"marginalia.org")。

これはつまりソースファイルとは別ファイルとして同じディレクトリーにmarginalファイルが置かれることを意味する。

org-remark-notes-file-nameのカスタマイズにcustomizeコマンドで行う場合にはFileかFunctionを選択するオプションが得られる(カスタマイゼーショングループはorg-remark)。デフォルトであるFileのデフォルトは上述の通り"marginal.org"だ。単一のファイルを文字列を用いて指定する。デフォルトのように相対パスでも良いが絶対パスでも可。

ファイルやさまざまな条件に応じて動的に場所を変更したい場合には、オプションに関数を選択すればよい。デフォルトの関数はorg-remark-notes-file-name-functionであり、このファイルは拡張子部分を除いたソースファイルに、後置詞として-notes.orgを付加する。たとえばmy-source-file.txtという名前のファイルであれば、Org-remarkはmy-source-file-notes.orgにハイライトを保存することになる。独自に関数を作成してそれを使うこともできる。

以下にいくつか例とユースケースを挙げてみよう:

ソースファイルへのmarginalノートの格納: ソースファイルをmarginalノートファイルとしても活用する(ソースファイル中にメモ書きを残す)ためには、org-remark-notes-file-nameの値にビルトインの関数buffer-file-nameをセットすればよい。ソースファイルがOrgファイルであることが保証されている必要があることに注意。
ソースファイルそれぞれにmarginalノートファイルを作成、それらをどこか特定の場所に保存する: ソースファイルごとに絶対ファイル名をリターンするようなカスタム関数を作成して、その関数名をorg-remark-notes-file-nameにセットするのだ。以下のような関数になるだろう:

        (defun my/function ()
          (concat "~/path/to/note-files/"
                  (file-name-base (org-remark-notes-file-name-function))
                  ".org"))
        
        (setq org-remark-notes-file-name
              #'my/function)

marginalノートファイルのリンクに相対あるいは絶対ファイル名を使用するには

marginalノートファイルにはソースファイル逆参照するようなファイル名が格納されている。たとえば"File1.txt"にたいするmarginalノートのエントリーは以下のようなものだろう。

    * File 1
    :PROPERTIES:
    :org-remark-file: path/to/File1.txt
    :END:
    ** Highlight 1 in File 1
    :PROPERTIES:
    :[...other-properties]:
    :org-remark-link: [[file:path/to/File1.txt::14]]
    :END:

"File 1"という名前のレベル1のヘッドラインには、ソースファイルpath/to/File1.txtのファイル名が記録されており、同様に"Highlight 1 in File 1"という名前のレベル2のヘッドラインにはソースファイルとハイライトの行番号を逆参照するリンクが格納されている。

ご覧の通りどちらのファイルにたいしても、名前にはmarginalノートファイルからの相対ファイル名が用いられているようであり、つまりorg-remark-source-file-nameはデフォルトのセッティングのままである。

絶対ファイル名や選択した関数を使うように、この変数はカスタマイズできる。関数の場合にはソースファイルの絶対ファイル名を単一の引数とするような関数を指定する。default-directoryにはmarginalノートファイルのあるディレクトリーが一時的にセットされる。相対ファイル名を選択した場合の相対パスは、このdefault-directoryから算出されるのだ。

ハイライトのremoveとdelete

org-remark-removeはカーソルの下のハイライトを削除するコマンドだ。marginalノートファイルにある対応するエントリーの削除は行わない。これは意図的な振る舞いだ。Org-remarkがユーザーが編集した恐れのある何かを削除する際には控え目な挙動となるのだ。

ハイライトとエントリーの削除を同時に削除したければorg-remark-removeにユニバーサル引数を渡す(M-x org-remark-removeの前にC-uを追加する)か、あるいはorg-remark-deleteを使うこともできる。org-remark-deleteと、C-uを追加したorg-remark-removeは等価だ。

marginalノートバッファーのハイライトに対応するエントリーにノートが存在することを検知すると、削除関数はユーザーに確認を求める。

削除、あるいはmarginalノートバッファーでの削除はアンドゥ(undo: 取り消し)が可能だ(ハイライト機能によってテキストがマークされたソースバッファーではない)。このハイライトは技術的にはオーバーレイ(overlay)なので、それ故ソースバッファーのundoツリーの一部に含まれていないのだ。

バージョン1.3では新しいオプション機能の自動削除を使うことができる。この機能が有効だとハイライトを含むようなテキストの削除時に、Org-remarkがそのハイライトのヘッドラインを自動的に削除するのだ。そのハイライトのヘッドラインにたいしてmarginalノートが存在する際には、Org-remarkはハイライトの削除とヘッドラインのプロパティだけを行う。これはorg-remark-removeの処理と同じだ。marginalノートは手付かずのままだ。いずれの場合においても、Org-remarkが確認を求めることはない。

以下の例のようにすれば、この新しいユーザーオプションorg-remark-notes-auto-deleteを有効にできる

    (setopt org-remark-notes-auto-delete :auto-delete)

さらにバージョン1.3ではorg-remark-deleteにユニバーサル引数を渡せば(C-u M-x org-remark-delete)、ポイント位置にあるハイライトにたいしてOrg-remarkが自動削除を行うように手作業で指示できる。C-u C-u M-x org-remark-removeのようにorg-remark-removeに2連でユニバーサル引数を与ても同じ操作を行うことができる。org-remark-removeに1つのユニバーサル引数を渡したときにはorg-remark-deleteと同じなので、これは理に適った振る舞いだろう。

関数org-remark-removeとorg-remark-deleteについては、カスタマイズ変数org-remark-notes-auto-deleteのドキュメントを参照して欲しい。

ハイライト位置の自動調節とは?

Org-remarkはデフォルトではハイライトをロードする際に位置の自動調節を試みる。これは"nov.el"でEPUBブックを読む場合には特に役に立つだろう。最大限の可読性を得るために、利用可能なウィンドウスペースに応じてさまざまなサイズでテーブルをレンダリングするからだ。

これは読書には優れた機能ではあるが、ページレンダリングの際のウィンドウサイズ次第で後続のテキスト要素の位置も変化してしまう。これにより作成時の元の位置からハイライト位置がずれてしまうかもしれない。

それにたいしてOrg-remarkはハイライトのずれの自動補正を試みている。これはOrg-remarkの一般的な機能であり、(EWWによる)ウェブサイトの軽微な編集の補正も行っている。

技術的には以下のような処理になる。

ハイライトを新たに作成すると、Org-remarkは元のテキストハイライトをorg-remark-original-textというOrgプロパティに記録する
新たなファイル(たとえばEPUBブック)を次回オープンする際には、Org-remarkがノート用のOrgバッファーからハイライトをロードする
ハイライトそれぞれにたいして、カレントでハイライトされたテキストのorg-remark-original-textプロパティと比較を行う
同じであればOrg-remarkは何もしない
血ガウ場合にはOrg-remarkはデフォルトでは前後2つのパラグラフで同じテキスト文字列を探して、最初に見つかったマッチするテキスト文字列にたいして、その文字列にハイライトを自動的に移動する
自動的に調節したハイライトには、調節済みハイライトの位置を明確にするためにOrg-remarkがアイコンを追加する
これは一時的な調節だがノートバッファーでorg-remark-begとorg-remark-endのプロパティを手動で変更すれば位置の変更を永続化できるし、ハイライトされたテキストの範囲を調節した場合にはorg-remark-original-textの値の変更を選択することも可能だ

アイコン自体、あるいはアイコンのフェイスは以下のカスタマイズ変数でカスタマイズできる:

オプション: org-remark-icon-position-adjusted
フェイス: org-remark-highlighter-warning

Org-remarkがSVGアイコンを使うように設定する

アイコンが表示できるのはバージョン1.2からだ。アイコン表示というオプションを使えばデフォルトで使用されるmarginalノートの存在を視覚的に示すためのASCII文字列"(*)"、ハイライト位置が自動調節されたことを示す"(d)"ではなくアイコンを使うようにOrg-remarkをカスタマイズできる。ハイライト位置の自動調節とは?を参照のこと。

SVGアイコンのセットアップには主に2つの方法が存在する。

Emacsのバージョン29.1で利用可能になったビルトインの"icons"ライブラリー
カスタム関数を作成してNicolas Rougier氏のsvg-libのようなサードパーティ製ライブラリーを使用する

以下は1つ目のビルトインライブラリーを使用するためのクイックガイドだ

SVGアイコンの入手あるいは作成
ダウンロードしたSVGファイルをローカルのどこかに配置
define-iconマクロを使用してSVGファイルからアイコンを作成する

まずアイコンを.svgファイルとして作成、あるいはダウンロードする。たとえばBoxiconsはMITライセンスで提供されているSVGのアイコンコレクションだ。次にSVGファイルを~/.config/emacs/.cache/svg/bx-pen.svgのようなローカルのディレクトリーに配置する。そして最後にアイコンを定義するために以下の例のように設定の中でdefine-iconを使用すればよい。

    (define-icon annotation nil
    '((image "~/.config/emacs/.cache/svg/bx-pen.svg"
             :height (0.8 . em)))
    "Notes svg icon for Org-remark"
    :version 29.1)

これでアイコンが定義できたので、以下のようにカスタマイズ用の変数org-remark-icon-notesにセットする:

    ;; This example uses `setopt' that is made available as of 29.1. `setq' works too.
    (setopt org-remark-icon-notes (icon-string 'annotation))

ハイライトがあるようなバッファーをすでにオープンしていたら、revert-bufferでハイライトをリロードしよう。デフォルトの文字列"(*)"のかわりに定義したアイコンが表示される筈だ。

その他コマンド

コマンド org-remark-toggle: カレントバッファーのハイライトの表示/非表示の切り替え。
カレントバッファーのハイライトの表示/非表示はorg-remark-modeではなくこちらのコマンドの使用をお勧めする。このコマンドはハイライトの表示だけに影響を与えるので、ハイライト位置の追跡は依然として行われるからだ。org-remark-modeをオフにすると追跡も完全に停止するので、marginalノートファイルとカレントのソースバッファーで整合性がとれなくなるかもしれない。
コマンド org-remark-change: ポイント位置のハイライトのペンを別のペンに変更する。

カレントバッファー内のハイライト間の移動にはorg-remark-view-nextとorg-remark-view-prev、あるいは以下のコマンドペアーを使うことができる。前者はカーソルを移動してmarginalノートバッファーを表示、後者はカーソルの移動だけという違いがある。

コマンド org-remark-next: (もしあれば)次のハイライトに移動する
ポイントの下に何もなくてもバッファーにハイライトがあれば、巡回して最初のハイライトへと戻る
このコマンドは次のハイライトにポイントが移動した後には、C-n ] ] ] ] ]のように最後の文字を再入力するだけで更に移動を繰り返すことができる(コマンドがC-n ]にバインドされている場合)
コマンド org-remark-prev: (もしあれば)前のハイライトに移動する。

カスタマイズ

Org-remarkのユーザーオプションはカスタマイゼーショングループorg-remarkにある。

フェイス: org-remark-highlighter: org-remark-markのデフォルトフェイス。
オプション: org-remark-create-default-pen-set: 非nilならOrg-remarkがデフォルトのペンセットを作成、作成したくなければnilにセットすること。
オプション: org-remark-notes-file-name: ハイライトとmarginalノートを保存するファイルの名前(文字列か関数)
文字列ならmarginalノートファイルのファイル名であること。デフォルトはmarginalia.org。デフォルトの場合にはディレクトリーごとに1つのmarginalノートファイルとなる。Orgファイルであること。
関数の場合のデフォルトはorg-remark-notes-file-name-function。これはFILE-notes.orgのように拡張子を取り除いて-notes.orgを後置詞として付加したファイル名をリターンする関数だ。
オプション: org-remark-notes-display-buffer-action: marginalノートバッファーをオープンする際にOrg-remarkが使用するバッファーdisplayアクション。
オプション: org-remark-notes-buffer-name: marginalノートバッファーのバッファー名。org-remark-openやorg-remark-visitはこの名前でclone したインダイレクトバッファーを作成する。
オプション: org-remark-source-file-name: ソースファイルを逆参照するファイル名をリターンする関数。
関数はソースファイルの絶対ファイル名を唯一の引数として呼び出される。default-directoryは一時的にmarginalノートファイルを配置する場所にセットされる。
これはオプションRelative file nameオプションが選択されている際には、marginalノートファイルに記録されるソースファイル名はmarginalノートファイルからの相対パスになることを意味する。
オプション: org-remark-use-org-id: 非nilならOrg-remarkはmarginalノートにOrg-IDリンクを追加する。これはソースファイル内の関連するOrg-IDへのリンクである。Org-remarkはこのIDを作成しないので手作業で追加するか、あるいは他の関数をヘッドラインかファイルに追加する必要がある。
: org-remark-icon-notes: ハイライトにたいして関連するノートエントリーがあることを示すために用いられるアイコン。デフォルトは端末間等で互換性があるASCII文字の組み合わせ。お好みによってはemojiをセットしてもよい。作者はアイコンフォントやその他グラフィカルな要素を表示する手段に関する経験が豊富ではない。アイコンのフェイスはハイライトのフェイスと同じになるので、独自のフェイス定義をもつことはない。

nilにセットすればアイコンは完全に無効になる。

org-remark-toggleはアイコンと一緒にハイライトも切り替える。
オプション: org-remark-icon-position-adjusted:
これはハイライトがOrg-remarkによって自動調節された位置にあることを示すために用いられるアイコン。デフォルトは端末間等で互換性があるASCII文字の組み合わせ。お好みによってはemojiをセットしてもよい。作者はアイコンフォントやその他グラフィカルな要素を表示する手段に関する経験が豊富ではない。

nilにセットすればアイコンは完全に無効になる。

org-remark-toggleはアイコンと一緒にハイライトも切り替える。
フェイス: org-remark-highlighter-warning: これはハイライト位置が調節されていることを示すアイコンに用いられるフェイス。この機能自体についての詳細は、What is Automatic Adjustment of Highlight Positions?を参照のこと。
オプション: org-remark-open-hook: ノートバッファーがオープン/visitされたときに実行されるフック。引数なしで実行されるがノートバッファーがカレントバッファーになる。
オプション org-remark-highlights-after-load-functions: ノート用のOrgバッファーからOrg-remarkがハイライトをロードした後に実行されるアブノーマルフック。OVERLAYSとNOTES-BUFを引数に実行される。OVERLAYSはハイライト。ソースバッファーをカレントバッファーとして実行される。このフックは自動調節機能がによって使用される。この機能自体についての詳細は、ハイライト位置の自動調節とは?を参照のこと。

行ハイライトのカスタマイズ

バージョン1.3で可能になった行ハイライト用のオプションもある。カスタマイズグループはorg-remark-lineだ。

フェイス: org-remark-line-highlighter: デフォルトの行ハイライト用のペンのフェイス。
オプション: org-remark-line-icon: 行ハイライトの存在を示すためにマージンに表示されるグリフ(glyph)。SVGアイコンをセットできる。Org-remarkがSVGアイコンを使うように設定するを参照のこと。
オプション: org-remark-line-minimum-margin-width: マージン幅を指定する自然数。1つの自然数、あるいは2つの自然数からなるコンスセル(cons cell)でもよい。1つの自然数ならそれが左右両方のマージン幅になる。
このカスタマイズ変数がコンスセルなら(LEFT-MARGIN-WIDTH . RIGHT-MARGIN-WIDTH)という形式で指定する。
オプション: org-remark-line-margin-padding: メインのテキストエリアとマージン上のグリフ/アイコンの間のパッディング。
オプション: org-remark-line-margin-side: 行ハイライトを左右どちらのマージンに表示するか。
LeftかRightを選択できる。
オプション: org-remark-line-heading-title-max-length: タイトルのハイライトとして含められる文字列の最大長。
オプション org-remark-line-ellipsis: タイトルのハイライトが最大長を超える際に用いられる省略記号。
最大長のセットはorg-remark-line-heading-title-max-length。

既知の制限

ソースファイルと一緒にエクスポートできない: ソースファイルと一緒にmarginalノートをエクスポートするための機能は用意されていない。とはいえmarginalノートは普通のOrgファイルなのでソースファイルもOrgファイルであれば、ビルトインのinclude機能を使えば、たとえばエクスポートの出力に関連するmarginalノート部分を含めたりできるだろう。
コピペでハイライトが失われる: オーバーレイはkillの一部には含まれないのでyankできない。
ハイライトをアンドゥしても取り消しできない: オーバーレイはundoリストの一部には含まれないのでハイライトはundoできない。かわりにorg-remark-removeやorg-remark-deleteといったコマンドを使うこと。
ソースファイルとmarginalノートファイルの移動: ファイルとremark用のファイルを別ディレクトリーに一緒に移動しても、marginalノートファイルに保存されているソースのパスとファイル名は更新されない。ソースファイルとmarginalノートファイルの間のリンクを保つには、org-remark-source-file-nameに相対ファイル名(デフォルト)を使うというのも1つの方法だ。
org-remark-eww-modeのハイライトはずれる可能性がある: ウェブサイトが編集されてコンテンツがEmacsの外部で変更された場合に起こり得る(普通のウェブサイトなら当然あり得るシチュエーションだろう)。現在のところハイライト位置を訂正する手段はない。

謝辞

これは以下のパッケージに触発されて作成したパッケージだ。これらのパッケージのコードは何もコピーしてはいないがアイデアをいくつか拝借させてもらった(別ファイルへのmarginノートの保存等)。

Ov-highlight: John Kitchin氏によるパッケージ(Org-refの作者でもある)。hydraとマーカーによる優れたユーザー体験を提供するパッケージだ。マーカーの情報とコメントをBase64エンコード文字列で直接Orgファイルに保存できる。ovパッケージでオーバーレイを処理使用している。
Annotate.el: Bastian Bechtoldによるパッケージ(Org-journalの作者でもある)。テキストの右隣(か上端)という独創的な注釈表示を行う。非常に短い注釈用、もしかしたら(プログラミング実習等の)コードレビュー用にデザインされたのではあるまいか。(散文によく使われる)可変ピッチフォントの使用にたいするissue報告を最近目にした。
Org-annotate-file: contribライブラリーの一部。特定のテキストアイテムではなく分割されているOrgファイル全体に注釈をつけるためにデザインされたように思える。
InPlaceAnnotations (ipa-mode): 上述の"Annotate.el"と似たような感じ。
Transientのナビゲーション機能: transientのナビゲーション機能を実装するために、Paul W. Rankin氏(GitHubのユーザーアカウントはrnkn)による素晴らしいEmacsパッケージBinderから関連するコードを盛大にコピーさせてもらった。

貢献とフィードバック

issueやdiscussion、あるいはpullリクエストはGithubに作成して欲しい。何でも大歓迎だ。

Org-remarkはGNU ELPAへの提出を計画しているので、Org-remarkはFree Software Foundation(FSF)によって著作権保護されている。これは軽微とは言えない貢献を行うすべての人は、GNU Emacs(Orgモードのウエブサイト)に含められるように貢献したコードを貢献したコードの著作権をFSFに譲渡する必要があることを意味している。

最後まで読んでくれてありがとう。

Index - Features

Index - Commands

Index - User Options

GNU Free Documentation License