Org-Remarkのマニュアル


- 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](#toc)
* [COPYING](#copying)
* [インストール](#インストール)
   * [基本的なセットアップ](#基本的なセットアップ)
   * [use-packageによるセットアップ](#use-packageによるセットアップ)
* [はじめよう](#はじめよう)
   * [ハイライトと注釈](#ハイライトと注釈)
   * [ハイライトから別のハイライトへの移動](#ハイライトから別のハイライトへの移動)
   * [自分用のハイライトペンの作成](#自分用のハイライトペンの作成)
   * [ウエブサイトへのハイライトと注釈](#ウエブサイトへのハイライトと注釈)
   * [EPUBブックへのハイライトと注釈](#epubブックへのハイライトと注釈)
   * [InfoモードのInfoドキュメントへのハイライトと注釈](#infoモードのinfoドキュメントへのハイライトと注釈)
* [使い方、機能や概念](#使い方機能や概念)
   * [ハイライト用のカスタムペンの作り方](#ハイライト用のカスタムペンの作り方)
   * [Emacs再起動に自動的にハイライトをオンに切り替えるには](#emacs再起動に自動的にハイライトをオンに切り替えるには)
   * [marginalノートを管理する方法](#marginalノートを管理する方法)
      * [marginalノートファイル](#marginalノートファイル)
      * [marginalノートバッファーのヘッドラインを自分のやり方で組織化する](#marginalノートバッファーのヘッドラインを自分のやり方で組織化する)
      * [marginalノートファイルの保存場所を変更するには](#marginalノートファイルの保存場所を変更するには)
      * [marginalノートファイルのリンクに相対あるいは絶対ファイル名を使用するには](#marginalノートファイルのリンクに相対あるいは絶対ファイル名を使用するには)
   * [ハイライトのremoveとdelete](#ハイライトのremoveとdelete)
   * [ハイライト位置の自動調節とは?](#ハイライト位置の自動調節とは)
   * [Org-remarkがSVGアイコンを使うように設定する](#org-remarkがsvgアイコンを使うように設定する)
   * [その他コマンド](#その他コマンド)
* [カスタマイズ](#カスタマイズ)
   * [行ハイライトのカスタマイズ](#行ハイライトのカスタマイズ)
* [既知の制限](#既知の制限)
* [謝辞](#謝辞)
* [貢献とフィードバック](#貢献とフィードバック)
* [Index - Features](#index---features)
* [Index - Commands](#index---commands)
* [Index - User Options](#index---user-options)
* [GNU Free Documentation License](#gnu-free-documentation-license)

<!-- Created by https://github.com/ekalinin/github-markdown-toc -->

<!-- This manual is for Org-remark version 1.3.x. The new features introduced with version 1.3.x are currently only available [GNU-devel ELPA](https://elpa.gnu.org/devel/org-remark.html) until the new version is released to [GNU-ELPA](https://elpa.gnu.org/packages/org-remark.html). -->

これはOrg-remarkのバージョン1.3.xのマニュアルである。新たなバージョンが[GNU-ELPA](https://elpa.gnu.org/packages/org-remark.html)にリリースされるまでは、バージョン1.3.xで導入された新たな機能が利用できるのは[GNU-devel ELPA](https://elpa.gnu.org/devel/org-remark.html)のみ。

<!-- Last updated: 01 February 2024. -->

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

<!-- Org-remark lets you highlight and annotate text files, websites (EWW), EPUB books (nov.el) and Info documentation (Info-mode). -->

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

# COPYING

Copyright &copy; 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.”


# インストール

<!-- This package is available on: -->

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

<!-- -   [GNU-ELPA](https://elpa.gnu.org/packages/org-remark.html) (releases only; equivalent to MELPA-Stable) -->
<!-- -   [GNU-devel ELPA](https://elpa.gnu.org/devel/org-remark.html) (unreleased main branch; equivalent to MELPA) -->

- [GNU-ELPA](https://elpa.gnu.org/packages/org-remark.html) (リリース版のみ; MELPA-Stableと同じ)

-   [GNU-devel ELPA](https://elpa.gnu.org/devel/org-remark.html) (リリース前のmainブランチ; MELPAと同じ)

<!-- GNU ELPA should be already set up in your Emacs by default. If you wish to add GNU-devel ELPA, simply add its URL to `package-archives` like this: -->

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

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

## 基本的なセットアップ

<!-- After installation, we suggest you put the setup below in your configuration. -->

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

```lisp
    (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` automatically turns on `org-remark-mode` when you open a file, website via EWW, EPUB book via nov.el, or other supported buffer that has a marginal notes file associated with it. This is useful to keep the location of your highlights correct across Emacs sessions after you shutdown Emacs. -->

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

<!-- Unless you explicitly load `org` during Emacs initialization, we suggest to defer loading `org-remark` (thus there is no `(require 'org-remark)` in the example above). This is because it will also pull in `org`, which can slow down initialization. You can control the timing of loading `org-remark` by autoloading some commands in a similar way with the example keybindings below. -->

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

<!-- Below are example keybindings you might like to consider: -->

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

```lisp
    ;; 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によるセットアップ

<!-- Alternatively, you can use `use-package` to set up Org-remark. The example provided below should be equivalent to the setup described above. -->

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

```lisp
    (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)))
```

# はじめよう

## ハイライトと注釈

<!-- Once you have installed and set it up ([Installation](#installation)), Org-remark is simple to use. Select a part of text and call `M-x org-remark-mark` to highlight it. You will see the selected text gets highlighted. This is a range-highlight. With the new version 1.3, you can also highlight a whole line in addition to a range of text by calling `org-remark-mark-line`. Visually, instead of adding a highlight to the line, it will add a mark on the margin of the buffer (the left margin is the default and you can customize it with `org-remark-line-margin-side`). This is a line-highlight. Both the range- and line-highlights behave the same way except for how they appear in the buffer you are editing or viewing. You can mix them in the same buffer as you see fit for your purposes. -->

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


<!-- The menu bar item &ldquo;Org-remark&rdquo; is available when you turn on `org-remark-mode`. It helps you discover Org-remark&rsquo;s main commands. If you use Emacs version 28 or newer, a context menu is also available by right-clicking your mouse. Turn on the Emacs built-in `context-menu-mode` to enable the context menu. -->

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

<!-- To display the marginal notes for the highlight you have just marked, place your cursor on the highlight and call `M-x org-remark-open` or `M-x org-remark-view`. This will create a new buffer to the left of the current buffer you are editing. You can customize where the marginal notes buffer is to be placed (see the documentation of customizing variable `org-remark-notes-display-buffer-action`). -->

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

<!-- The `open` command takes the cursor to the marginal notes buffer for you to edit notes; the `view` command keeps the cursor in the current buffer only to display the marginal notes. Both commands narrow the **marginal notes file** to the entry for the highlight under the cursor.  The marginal notes file is a normal Org file. Edit your notes just as you would do with any other Org files and save the buffer. -->

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

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

<!-- After you have added a couple of highlights in the text, you can move through the highlights easily. Use `org-remark-view-next` and `org-remark-view-prev` to browse the marginal notes as you move from one highlight to another. They display the marginal notes on the side-window by default. Or use `org-remark-next` and `org-remark-prev` if you simply want to move to the next/previous highlight without displaying marginal notes for them. -->

テキストに追加したハイライトが何箇所かある際に、それらのハイライトへの移動は簡単だ。あるハイライトから別のハイライトに移動して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`

<!-- The `C-c n` part is the prefix key common to all of them. If you set the keybindings like this, you can use `C-c n ]` once to view the next highlight and keep pressing a single key `]` or `[` to browse through the next/previous highlights. After you have reached the one you like to act on, press `o` to open it, `r` or `d` to remove/delete it. -->

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

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

<!-- Org-remark has a default highlighter pen function, and comes with a set of two additional pens by default: -->

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

<!-- -   **`org-remark-mark`       :** default highlighter pen -->
<!-- -   **`org-remark-mark-line`:** default line-highlighter pen, which adds a mark on the margin instead of a range of text -->
<!-- -   **`org-remark-mark-yellow`   :** yellow highlight with &ldquo;important&rdquo; category in the marginal notes entry -->
<!-- -   **`org-remark-mark-red-line`  :** wavy red underline with &ldquo;review&rdquo; category in the marginal notes entry and &ldquo;Review this&rdquo; in tool-tips -->


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

<!-- Org-remark lets you create your own custom pen functions with `org-remark-create`. Use the yellow and red line pens as examples, and create your own. For how to do it, [How to Create Custom Highlighter Pens](#create-custom-pens). -->

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

<!-- This is all you need to get started. For more detail, refer to the rest of this user manual, especially [Usage](#usage) and [Customizing](#customizing) sections. There is more to the commands introduced in this section and more ways in which you can customize Org-remark. -->

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

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

<!-- `org-remark-eww-mode` lets you highlight and annotate websites just like text files. It is a global minor mode. It does not require any additional configuration. All you need is to turn it on, visit a website with `eww-mode`, and select text and highlight it. Refer to the example of a basic setup given in [Installation](#installation). Org-remark can attempt to automatically adjust the position of highlights when a websites get edited. Lear more about the feature in [What is Automatic Adjustment of Highlight Positions?](#auto-adjust) -->

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

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

<!-- `org-remark-nov-mode` lets you highlight and annotate EPUB books just like text files. It is a global minor mode. It does not require any additional configuration. All you need is to turn it on, open a EPUB book with `nov-mode`, and select text and highlight it. Refer to the example of a basic setup given in [Installation](#installation). If you read books with tables, it is useful to learn about the feature that automatically adjust the highlight positions: [What is Automatic Adjustment of Highlight Positions?](#auto-adjust) -->

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

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

<!-- `org-remark-info-mode` lets you highlight and annotate Info documentation just like text files. It is a global minor mode. It does not require any additional configuration. All you need is to turn it on, open an Info node with `Info-mode`, and select text and highlight it. Refer to the example of a basic setup given in [Installation](#installation). -->



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

# 使い方、機能や概念

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

<!-- `org-remark-create` is a macro that lets you create your own custom pen functions. Org-remark comes with two additional pens that are created by default. Use them as examples to learn how to create your own. -->

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

```lisp
    (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"))
```

<!-- -   **Macro: `org-remark-create` label &optional face properties:** Create and register new highlighter pen functions. The newly created pen function will be registered to variable `org-remark-available-pens`.  It is used by `org-remark-change` as a selection list. -->
    
<!--     `LABEL` is the name of the highlighter and mandatory. The function will be named `org-remark-mark-LABEL`. -->
    
<!--     The highlighter pen function will apply `FACE` to the selected region. `FACE` can be an anonymous face.  When `FACE` is nil, this macro uses the default face `org-remark-highlighter`. -->
    
<!--     `PROPERTIES` is a plist of pairs of a symbol and value. Each highlighted text region will have a corresponding Org headline in the notes file, and it can have additional properties in the property drawer from the highlighter pen. To do this, prefix property names with &ldquo;`org-remark-`&rdquo; or use &ldquo;`CATEGORY`&rdquo;. -->

-   **マクロ: `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`"を使用する。

<!-- As of version 1.3, you can use `org-remark-create` to create a new line-highlighter pen. Use the `PROPERTIES` parameter like the example below to specify `org-remark-type` to be `line`. This tells Org-remark to create a line-highlighter pen function instead of a default range-highlighter one. The `LABEL` does not need to include the string &ldquo;line&rdquo;, but it is recommended for consistency with the default command `org-remark-mark-line`. -->

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

```lisp
    ;; 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再起動に自動的にハイライトをオンに切り替えるには

<!-- It is recommended that `org-remark-global-tracking-mode` be turned on as part of your Emacs initialization. This should be done before you start adding highlights in any file. -->

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

<!-- Once you have added highlights to some files, quit Emacs, and re-start it, active org-remark-global-tracking-mode will automatically turn on org-remark-mode and load the highlights from your previous sessions for the files being globally tracked. -->

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

<!-- Without this global minor mode, you would need to remember to activate `org-remark-mode` for each file where you add highlights and annotation. This is often unpractical. -->

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

## marginalノートを管理する方法

### marginalノートファイル

<!-- When you mark a part of text with a highlighter pen function, Org-remark will automatically create a **marginal notes file**. By default, it will be named `marginalia.org` and created in the same directory as the file you are editing ([How to Change Where Marginal Notes File is Saved](#change-marginal-notes-filename) [;Customizing](#customizing), `org-remark-notes-file-name`). -->

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

<!-- The important thing to note is that Org-remark uses following properties in the property drawer of the headline to remember the highlights: -->

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

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

<!-- Essentially, the marginal notes file is a database in the plain text with using Org mode. As a plain text database, you can easily edit these properties manually if necessary. You can directly edit the marginal notes file as a normal Org file. -->

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

<!-- The marginal notes file stores highlights and notes like this below; it is designed to organize highlights and notes for multiple files and multiple highlights (You are free to change the default headline titles Org-remark automatically inserts. Refer to section [Organize Headlines in Marginal Notes Buffer in Your Way](#organize-headlines)). -->

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

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

<!-- You can leave the marginal notes file as it is without writing any notes. In this case, the entries in marginal notes file simply save the locations of your highlighted text. After you quit Emacs,  re-start it, and visit the same source file, Org-remark uses this information to highlight the text again. -->

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

<!-- In addition to the properties above that Org-remark reserves for itself, you can add your own custom properties and `CATEGORY` property. Use &ldquo;org-remark-&rdquo; as the prefix to the property names (or &ldquo;CATEGORY&rdquo;, which is the only exception), and Org-remark put them to the property drawer of highlight&rsquo;s headline entry in the marginal notes buffer. Define the custom properties in your own custom pen functions (for how to create your own pens, [How to Create Custom Highlighter Pens](#create-custom-pens)). -->

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

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

<!-- When you highlight a range of text or a line, Org-remark creates a corresponding headline in the marginal notes buffer with using Org mode. By default, the headline&rsquo;s title is either the selected text for the range-highlight or the first 40 characters of the line for the line-highlight. For the latter, if the string is longer than the maximum characters, it will be truncated and replaced by an ellipsis &ldquo;…&rdquo;. Both the 40 character maximum length and the ellipsis can be customized with customizing variables `org-remark-line-heading-title-max-length` and `org-remark-line-ellipsis` respectively. -->

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

<!-- These are only default initial headline titles and you are free to change them as you see fit. For example, you may add a line-highlight to the line where you define a function in an Emacs Lisp script file. The initial title of the corresponding headline in the marginal notes buffer will be something like this below. -->

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

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

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

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

### `*marginal-notes*` Buffer

<!-- When you display the marginal notes with `org-remark-view` or `org-remark-open` for a given highlight, Org-remark creates a cloned indirect buffer visiting the marginal notes file. By default, it is a dedicated side-window opened to the left part of the current frame, and it is named `*marginal notes*`. You can change the behavior of `display-buffer` function and the name of the buffer ([Customizing](#customizing)). -->

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

<!-- Org-remark displays the marginal notes buffer narrowed to the highlight the cursor is on. -->

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

<!-- After all the properties, you can freely write your notes for the highlight. Once you save the notes buffer, an excerpt of the text (currently up to 200 characters) gets updated back onto the highlight in the source buffer. You can hover your mouse over the highlight to see the excerpt displayed in the echo area (bottom of the screen) of Emacs. If you have `tooltip-mode` mode turned on, the excerpt is displayed as a took tip for the highlight. -->

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

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

<!-- The location of the marginal notes file is specified by user option `org-remark-notes-file-name` and its default is &ldquo;marginalia.org&rdquo;. This means the marginal notes file will reside in the same directory as the source files as a separate file. -->

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

<!-- This means the marginal notes file will reside in the same directory as the source files as a separate file. -->

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

<!-- If you use the `customize` command to customize `org-remark-notes-file-name`, you will have an option to choose a `File` or `Function` (customization group `org-remark`). The default is `File` with the default &ldquo;marginal.org&rdquo; as noted above.  Use a string to specify the single file name; you can specify a relative path like the default or an absolute path. -->

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

<!-- If you would like to dynamically change the location based on the file and various different conditions, select the function as an option.  The default function is `org-remark-notes-file-name-function`. It adds `-notes.org` as a suffix to the source file&rsquo;s name without the extension. For example, for a file named `my-source-file.txt`,  Org-remark will store highlights in  `my-source-file-notes.org`.  You can create your own function and use it. -->

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

<!-- Some examples and use cases are listed below: -->

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

<!-- -   **Store Marginal Notes in the Source File:** In order to use the source file also as the marginal notes file (storing the notes in the source file), you can set the built-in function `buffer-file-name` as the value of `org-remark-notes-file-name`. Note that you will need to ensure that the source files are an Org file. -->

<!-- -   **Create a marginal notes file for each source file and store all of them in a specific location:** Create a custom function that returns an absolute file name per source file, and set `org-remark-notes-file-name` to the function name. It might look like this: -->

-   **ソースファイルへのmarginalノートの格納:** ソースファイルをmarginalノートファイルとしても活用する(ソースファイル中にメモ書きを残す)ためには、`org-remark-notes-file-name`の値にビルトインの関数`buffer-file-name`をセットすればよい。ソースファイルがOrgファイルであることが保証されている必要があることに注意。

-   **ソースファイルそれぞれにmarginalノートファイルを作成、それらをどこか特定の場所に保存する:** ソースファイルごとに絶対ファイル名をリターンするようなカスタム関数を作成して、その関数名を`org-remark-notes-file-name`にセットするのだ。以下のような関数になるだろう:

```lisp
        (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ノートファイルのリンクに相対あるいは絶対ファイル名を使用するには

<!-- The marginal notes file stores the file name pointing back at source files. For example, a marginal notes entry for File1.txt might look like this example below. -->

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

```text
    * 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:
```

<!-- The level-1 headline named &ldquo;File 1&rdquo; records the file name of the source file `path/to/File1.txt`.  Similarly, the level-2 headline named &ldquo;Highlight 1 in File 1&rdquo; stores the link pointing back at the source file and the line number of the highlight. -->

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


<!-- As you can see, both file names use a relative file name from the marginal notes file. This is the default setting of `org-remark-source-file-name`. -->

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


<!-- You can customize the variable to use absolute file names, or to use a function of your choice. The function is called with a single argument: the absolute file name of source file.  The `default-directory` is temporarily set to the directory where the marginal notes file resides. If you choose to use relative file names, the relative path is computed from `default-directory`. -->

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

## ハイライトのremoveとdelete

<!-- You can remove the highlight under the cursor with command `org-remark-remove`. This command does not delete the corresponding entry in the marginal notes file. This is intentional; Org-remark is conservative when it deletes anything that the user might have edited. -->

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

<!-- If you wish to delete the entry and the highlight at the same time, pass a universal argument to \`org-remark-remove\` (e.g. by adding `C-u` before `M-x org-remark-remove`) or use `org-remark-delete`. `org-remark-delete` is identical with adding `C-u` to `org-remark-remove`. -->

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

<!-- The delete function will prompt for confirmation if it detects any notes present in the corresponding entry for the highlight in question in the marginal notes buffer. -->

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

<!-- > Note that you can undo the deletion or removal **in the marginal notes buffer** &#x2013; not in the source buffer where you mark text with a highlighter. Technically, highlights are overlays and are therefore not part of the undo tree in the source buffer. -->

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

<!-- As of version 1.3, you can use a new optional feature, automatic deletion. When the feature is enabled, Org-remark will automatically delete the highlight&rsquo;s headline when you delete text that includes a highlight, provided there is no marginal notes for it. If marginal notes are present for the highlight&rsquo;s headline, Org-remark only removes the highlight, deleting the properties from the highlight headline &#x2013; same operation as `org-remark-remove`. Your marginal notes will be kept intact. In either case, Org-remark does not ask for your confirmation. -->

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

<!-- You can enable it with the new user option `org-remark-notes-auto-delete` like this example below. -->

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

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

<!-- Furthermore,  with v1.3, if you pass a universal argument to `org-remark-delete` (e.g. `C-u M-x org-remark-delete`) you can manually get Org-remark to do automatic deletion for the highlight at point. You can also pass double universal arguments to `org-remark-remove` (e.g. `C-u C-u M-x org-remark-remove`) for the same operation. This should make sense because passing a single universal argument to `org-remark-remove` is the same as `org-remark-delete`. Refer to the documentation of the customizing variable `org-remark-notes-auto-delete,` the functions `org-remark-remove` and `org-remark-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`と同じなので、これは理に適った振る舞いだろう。

<!-- Refer to the documentation of the customizing variable `org-remark-notes-auto-delete,` the functions `org-remark-remove` and `org-remark-delete`. -->

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

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

<!-- Org-remark by default attempts to automatically adjust the position of highlights when they are loaded. This is useful especially for EPUB books read by nov.el. It renders tables in different sizes depending on the available space of the window to maximize their readability. -->

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


<!-- This is a good feature for reading; however, it also changes the positions of subsequent text elements depending on the window size when the page is rendered. It can result in dislocating the positions of highlights, different from they are originally created. -->

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

<!-- Org-remark attempts to automatically corrects the highlights dislocated. This is a general feature so Org-remark attempts to correct minor edits to websites (for EWW). -->

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

<!-- More technically, it works as follows. -->

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

<!-- 1.  When you create a new highlight, Org-remark records the original text highlighted in the Org property named &ldquo;`org-remark-original-text`&rdquo;. -->

<!-- 2.  Next time when you open a new file (EPUB book as an example), Org-remark loads the highlights from the notes Org buffer. -->

<!-- 3.  For each highlight, it compares the currently highlighted text with the value of `org-remark-original-text` property. -->

<!-- 4.  If they are the same, Org-remark does nothing. -->

<!-- 5.  If different, Org-remark by default looks for the same text string +- two paragraphs. When it finds the **first** matching text string, it automatically moves the highlight to the matched text string. -->

<!-- 6.  Org-remark adds an icon to the auto-adjusted highlight to make it clear that the position of highlight has been adjusted. -->

<!-- 7.  This adjustment is temporary. If you prefer to change the position permanently, you can do so by manually changing the `org-remark-beg` and `org-remark-end` properties in the notes buffer and save. You can also choose to alter the value of `org-remark-original-text` if you have adjusted the range of highlighted text. -->

1.  ハイライトを新たに作成すると、Org-remarkは元のテキストハイライトを`org-remark-original-text`というOrgプロパティに記録する

2.  新たなファイル(たとえばEPUBブック)を次回オープンする際には、Org-remarkがノート用のOrgバッファーからハイライトをロードする

3.  ハイライトそれぞれにたいして、カレントでハイライトされたテキストの`org-remark-original-text`プロパティと比較を行う

4.  同じであればOrg-remarkは何もしない

5.  血ガウ場合にはOrg-remarkはデフォルトでは前後2つのパラグラフで同じテキスト文字列を探して、**最初**に見つかったマッチするテキスト文字列にたいして、その文字列にハイライトを自動的に移動する

6.  自動的に調節したハイライトには、調節済みハイライトの位置を明確にするためにOrg-remarkがアイコンを追加する

7.  これは一時的な調節だがノートバッファーで`org-remark-beg`と`org-remark-end`のプロパティを手動で変更すれば位置の変更を永続化できるし、ハイライトされたテキストの範囲を調節した場合には`org-remark-original-text`の値の変更を選択することも可能だ

<!-- You can customize the icon itself and its face with the following customizing variables: -->

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

-   オプション: `org-remark-icon-position-adjusted`

-   フェイス: `org-remark-highlighter-warning`

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

<!-- As of v1.2, highlights can display an icon. With this option, you can customize Org-remark to visually indicate that marginal notes exist for them instead of the default ASCII string &ldquo;(\*)&rdquo;, or to indicate that the Org-remark has automatically adjusted the highlight position (default ASCII string &ldquo;(d)&rdquo;; refer to [What is Automatic Adjustment of Highlight Positions?](#auto-adjust)). -->

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

<!-- There are mainly two ways to set up SVG icons. -->

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

<!-- 1.  Use the new built-in \`icons\` library available as of Emacs version 29.1 -->
<!-- 2.  Create a custom function and use a third-party library such as [`svg-lib`](https://github.com/rougier/svg-lib) by Nicolas Rougier -->

1.  Emacsのバージョン29.1で利用可能になったビルトインの"icons"ライブラリー

2.  カスタム関数を作成してNicolas Rougier氏の[`svg-lib`](https://github.com/rougier/svg-lib)のようなサードパーティ製ライブラリーを使用する

<!-- Below is a quick guide on the first option to use the built-in library-->

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

<!-- 1.  Get or create an SVG icon -->
<!-- 2.  Put the downloaded SVG file somewhere in your local -->
<!-- 3.  Use define-icon macro to create an icon with the SVG file -->

1.  SVGアイコンの入手あるいは作成

2.  ダウンロードしたSVGファイルをローカルのどこかに配置

3.  `define-icon`マクロを使用してSVGファイルからアイコンを作成する

<!-- First, create or download an icon as an `.svg` file. For example, [Boxicons](https://boxicons.com/) has a collection of SVG icons, which [are provided under The MIT License](https://boxicons.com/usage#license). Second, place the SVG file in your local directory, e.g.   `~/.config/emacs/.cache/svg/bx-pen.svg`. And finally, use `define-icon` to define the icon in your configuration like this example below. -->

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

```lisp
    (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)
```

<!-- Now the icon has been defined, you can set it to customizing variable ~org-remark-icon-notes~  like so: -->

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

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

<!-- If you have a buffer with highlights already open, use `revert-buffer` to reload the highlights. You should see the icon you have defined instead of the default “(\*)” string. -->

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

## その他コマンド

<!-- -   **Command `org-remark-toggle`:** Toggle showing/hiding of highlights in current buffer. -->
<!--     If you would like to hide/show the highlights in the current buffer, it is recommended to use this command instead of `org-remark-mode`. This command only affects the display of the highlights and their locations are still kept tracked.  Toggling off `org-remark-mode` stops this tracking completely, which will likely result in inconsistency between the marginal notes file and the current source buffer. -->

<!-- -   **Command `org-remark-change`:** Change the highlight at point to one by another pen. This command will show you a list of available pens to choose from. -->

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

-   **コマンド `org-remark-change`:** ポイント位置のハイライトのペンを別のペンに変更する。

<!-- To navigate through highlights in the current buffer, you can use `org-remark-view-next` / `org-remark-view-prev` or the following pair of commands. The former moves your cursor and displays the marginal notes buffer; the latter only moves your cursor. -->

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

<!-- -   **Command `org-remark-next`:** Move to the next highlight, if any. -->
<!--     If there is none below the point but there is a highlight in the buffer, cycle back to the first one. -->
<!--     After the point has moved to the next highlight, this command lets you move further by re-entering only the last letter like this example:  `C-n ] ] ] ] ]` (assuming this command is bound to C-n ]) -->

<!-- -   **Command `org-remark-prev`:** Move to the previous highlight, if any. -->


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

-   **コマンド `org-remark-prev`:** (もしあれば)前のハイライトに移動する。

# カスタマイズ

<!-- Org-remark&rsquo;s user options are available in the customization group `org-remark`. -->

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


<!-- -   **Face: `org-remark-highlighter`:** Default face for `org-remark-mark` -->

<!-- -   **Option: `org-remark-create-default-pen-set`:** When non-nil, Org-remark creates default pen set. Set to nil if you prefer for it not to. -->

<!-- -   **Option: `org-remark-notes-file-name`:** Name of the file where we store highlights and marginal notes. It can be either a string or function. -->
<!--     If it is a string, it should be a file name to the marginal notes file. The default is `marginalia.org`.  The default will result in one marginal notes file per directory.  Ensure that it is an Org file. -->
<!--     If it is a function, the default function is `org-remark-notes-file-name-function`.  It returns a file name like this: `FILE-notes.org` by adding `-notes.org` as a suffix to the file name without the extension. -->

<!-- -   **Option: `org-remark-notes-display-buffer-action`:** Buffer display action that Org-remark uses to open marginal notes buffer. -->

<!-- -   **Option: `org-remark-notes-buffer-name`:** Buffer name of the marginal notes buffer. `org-remark-open` and `org-remark-visit` create an indirect clone buffer with this name. -->

<!-- -   **Option: `org-remark-source-file-name`:** Function that returns the file name to point back at the source file. -->
<!--     The function is called with a single argument: the absolute file name of source file.  The `default-directory` is temporarily set to the directory where the marginal notes file resides. -->
<!--     This means that when the `Relative file name` option is selected, the source file name recorded in the marginal notes file will be relative to it. -->

<!-- -   **Option: `org-remark-use-org-id`:** When non-nil, Org-remark adds an Org-ID link to marginal notes. The link points at the relevant Org-ID in the source file. Org-remark does not create this ID, which needs to be added manually or some other function to either the headline or file. -->

<!-- -   **Option: `org-remark-icon-notes`:** It&rsquo;s the icon used to indicate that a given highlight has its associated notes entry. The default is a combination of ASCII characters to be compatible with terminal and others. If it is preferred, you can set an emoji to it. The author has not experienced well with icon fonts and other means of displaying graphic elements. The face of the icon becomes the same as the highlight, thus it does not have its own face definition. -->
    
<!--     By setting it to `nil`, you can disable the icon altogether. -->
    
<!--     `org-remark-toggle` also toggles the icon along with the highlight -->

<!-- -   Option: `org-remark-icon-position-adjusted` : -->
<!--     It&rsquo;s the icon used to indicate that the position of a given highlight has been automatically adjusted by Org-remark. The default is a combination of ASCII characters to be compatible with terminal and others. If it is preferred, you can set an emoji to it. The author has not experienced well with icon fonts and other means of displaying graphic elements. -->
    
<!--     By setting it to `nil`, you can disable the icon altogether. -->
    
<!--     `org-remark-toggle` also toggles the icon along with the highlight -->

<!-- -   **Face: `org-remark-highlighter-warning`:** This face is used by the icon to indicate that the position of a given highlight has been adjusted. To know more about the feature itself, refer to [What is Automatic Adjustment of Highlight Positions?](#auto-adjust). -->

<!-- -   **Option: `org-remark-open-hook`:** Hook run when a note buffer is opened/visited. It gets run with no additional argument but the current buffer will become the note buffer. -->

<!-- -   **Option `org-remark-highlights-after-load-functions`:** Abnormal hook run after Org-remark loads the highlights from the note org buffer. It is run with OVERLAYS and NOTES-BUF as arguments. OVERLAYS are highlights. It is run with the source buffer as current buffer. This hook is used by the automatic adjustment feature. To know more about the feature itself, refer to [ハイライト位置の自動調節とは?](#auto-adjust). -->

-   **フェイス: `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?](#auto-adjust)を参照のこと。

-   **オプション: `org-remark-open-hook`:** ノートバッファーがオープン/visitされたときに実行されるフック。引数なしで実行されるがノートバッファーがカレントバッファーになる。

-   **オプション `org-remark-highlights-after-load-functions`:** ノート用のOrgバッファーからOrg-remarkがハイライトをロードした後に実行されるアブノーマルフック。OVERLAYSとNOTES-BUFを引数に実行される。OVERLAYSはハイライト。ソースバッファーをカレントバッファーとして実行される。このフックは自動調節機能がによって使用される。この機能自体についての詳細は、[ハイライト位置の自動調節とは?](#ハイライト位置の自動調節とは)を参照のこと。

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

<!-- These are user options for line highlights available as of v1.3. They are listed in customizing group `org-remark-line`. -->

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

<!-- -   **Face: `org-remark-line-highlighter`:** Face for the default line highlighter pen. -->

<!-- -   **Option: `org-remark-line-icon`:** Glyph displayed on the margin to indicate the line-highlight. You can set an SVG icon to it. Refer to [How to Set Org-remark to Use SVG Icons](#icon). -->

<!-- -   **Option: `org-remark-line-minimum-margin-width`:** Margin width in a natural number. It can be a single number or a cons cell of two. When it is a single number, both the left and right margin widths will be the -->

<!-- same. When this customizing variable is a cons cell, the format is as follows: (LEFT-MARGIN-WIDTH . RIGHT-MARGIN-WIDTH). -->

<!-- -   **Option: `org-remark-line-margin-padding`:** Padding between the main text area the glyph/icon on the margin. -->

<!-- -   **Option: `org-remark-line-margin-side`:** The side of margin to display line highlights. -->

<!-- Left or Right can be chosen. -->

<!-- -   **Option: `org-remark-line-heading-title-max-length`:** Maximum length of string included as the highlight title. -->

<!-- -   **Option `org-remark-line-ellipsis`:** Ellipsis used when the highlight title is longer than maximum. -->

-   **フェイス: `org-remark-line-highlighter`:** デフォルトの行ハイライト用のペンのフェイス。

-   **オプション: `org-remark-line-icon`:** 行ハイライトの存在を示すためにマージンに表示されるグリフ(glyph)。SVGアイコンをセットできる。[Org-remarkが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`。

# 既知の制限

<!-- -   **No export together with the source file:** There is no out-of-the-box feature to export marginal notes together with the source file.  Nevertheless, the marginal notes is a normal Org file, thus if the source file is also an Org file, you could use the built-in `include` feature, for example, to include relevant parts of the marginal notes into the export output. -->

<!-- -   **Copy & pasting loses highlights:** Overlays are not part of the kill; thus cannot be yanked. -->

<!-- -   **Undo highlight does not undo it:** Overlays are not part of the undo list; you cannot undo highlighting. Use `org-remark-remove` or `org-remark-delete` commands instead. -->

<!-- -   **Moving source files and marginal notes files:** Moving your files and remark file to another directory does not update the source paths and file names stored in the marginal notes file. One way to keep the links between the source files and marginal notes files is to use relative file names with `org-remark-source-file-name` (default). -->

<!-- -   **With `org-remark-eww-mode` highlights can get displaced:** This happens when the website is edited and its content changes outside Emacs &#x2013; of course this is normal for websites. Currently there is no way to fix the location of highlights. -->

-   **ソースファイルと一緒にエクスポートできない:** ソースファイルと一緒に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の外部で変更された場合に起こり得る(普通のウェブサイトなら当然あり得るシチュエーションだろう)。現在のところハイライト位置を訂正する手段はない。

# 謝辞

<!-- To create this package, I was inspired by the following packages. I did not copy any part of them, but borrowed some ideas from them &#x2013; e.g. saving the margin notes in a separate file. -->

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

<!-- -   **[Ov-highlight](https://github.com/jkitchin/ov-highlight):** John Kitchin&rsquo;s (author of Org-ref). Great UX for markers with hydra. Saves the marker info and comments directly within the Org file as Base64 encoded string. It uses overlays with using `ov` package. -->

<!-- -   **[Annotate.el](https://github.com/bastibe/annotate.el):** Bastian Bechtold&rsquo;s (author of Org-journal). Unique display of annotations right next to (or on top of) the text. It seems to be designed for very short annotations, and perhaps for code review (programming practice); I have seen recent issues reported when used with variable-pitch fonts (prose). -->

<!-- -   **[Org-annotate-file](https://github.com/tkf/org-mode/blob/master/contrib/lisp/org-annotate-file.el):** Part of Org&rsquo;s contrib library. It seems to be designed to annotate a whole file in a separate Org file, rather than specific text items. -->

<!-- -   **[InPlaceAnnotations (ipa-mode)](https://github.com/IdoMagal/ipa.el):** It looks similar to Annotate.el above. -->

<!-- -   **Transient navigation feature:** To implement the transient navigation feature, I liberally copied the relevant code from a wonderful Emacs package, [Binder](https://github.com/rnkn/binder/blob/24d55db236fea2b405d4bdc69b4c33d0f066059c/binder.el#L658-L665) by Paul W. Rankin (GitHub user [rnkn](https://github.com/rnkn)). -->

-   **[Ov-highlight](https://github.com/jkitchin/ov-highlight):** John Kitchin氏によるパッケージ(Org-refの作者でもある)。hydraとマーカーによる優れたユーザー体験を提供するパッケージだ。マーカーの情報とコメントをBase64エンコード文字列で直接Orgファイルに保存できる。`ov`パッケージでオーバーレイを処理使用している。

-   **[Annotate.el](https://github.com/bastibe/annotate.el):** Bastian Bechtoldによるパッケージ(Org-journalの作者でもある)。テキストの右隣(か上端)という独創的な注釈表示を行う。非常に短い注釈用、もしかしたら(プログラミング実習等の)コードレビュー用にデザインされたのではあるまいか。(散文によく使われる)可変ピッチフォントの使用にたいするissue報告を最近目にした。

-   **[Org-annotate-file](https://github.com/tkf/org-mode/blob/master/contrib/lisp/org-annotate-file.el):** contribライブラリーの一部。特定のテキストアイテムではなく分割されているOrgファイル全体に注釈をつけるためにデザインされたように思える。

-   **[InPlaceAnnotations (ipa-mode)](https://github.com/IdoMagal/ipa.el):** 上述の"Annotate.el"と似たような感じ。

-   **Transientのナビゲーション機能:** transientのナビゲーション機能を実装するために、Paul W. Rankin氏(GitHubのユーザーアカウントは[rnkn](https://github.com/rnkn))による素晴らしいEmacsパッケージ[Binder](https://github.com/rnkn/binder/blob/24d55db236fea2b405d4bdc69b4c33d0f066059c/binder.el#L658-L665)から関連するコードを盛大にコピーさせてもらった。

# 貢献とフィードバック

<!-- Create issues, discussion, and/or pull requests in the GitHub repository. All welcome. -->

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

<!-- Org-remark is planned to be submitted to GNU ELPA and thus copyrighted by the Free Software Foundation (FSF). This means that anyone who is making a substantive code contribution will need to “assign the copyright for your contributions to the FSF so that they can be included in GNU Emacs” (Org Mode website). -->

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

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

# Index - Features


# Index - Commands


# Index - User Options


# GNU Free Documentation License