[elpa] externals/org-remark 06884bc6cb 1/6: docs: add an article on how to customize an SVG icon

[ELPA Syncer]

branch: externals/org-remark
commit 06884bc6cb1860a1e5adb74d6f73ae3c6b504805
Author: Noboru Ota <me@nobiot.com>
Commit: Noboru Ota <me@nobiot.com>

    docs: add an article on how to customize an SVG icon
---
 README-elpa                                        |   6 ++-
 README.org                                         |   2 +-
 .../2023-08-20T183400_how-to-buffer-window.org     |   2 +
 ...0T184309_C_how-to-set-icons-to-be-svg-images.md |  55 +++++++++++++++++++++
 resources/images/v1.2.0/2023-08-20-SVG-icon.png    | Bin 0 -> 147118 bytes
 5 files changed, 63 insertions(+), 2 deletions(-)

diff --git a/README-elpa b/README-elpa
index 0e1b7099a2..95f37a40ca 100644
--- a/README-elpa
+++ b/README-elpa
@@ -35,7 +35,11 @@ _________________
   [online] or or Info node `(org-remark) Getting Started'.
 
   For customization, refer to the customization group `org-remark' or
-  user manual: [online] or Info node `(org-remark) Customizing'.
+  user manual: [online] or Info node `(org-remark) Customizing'. A
+  [separate online
+  
article](<https://github.com/nobiot/org-remark/tree/main/docs/articles/2023-08-20T184309_C_how-to-set-icons-to-be-svg-images.md>)
+  has been written to guide you on how to customize an icon (to be
+  incorporated into the user manual later).
 
   An [introductory video] (8 minutes) and [V1.1.0 release introduction]
   (12 minutes) are available on YouTube.
diff --git a/README.org b/README.org
index 79ac957668..d112a52f97 100644
--- a/README.org
+++ b/README.org
@@ -18,7 +18,7 @@ For installation and minimum configuration, refer to 
[[#installation][Installati
 
 Getting Started in the user manual will get you started in 5 minutes: 
[[https://nobiot.github.io/org-remark/#Getting-Started][online]] or or Info 
node `(org-remark) Getting Started'.
 
-For customization, refer to the customization group `org-remark' or user 
manual: [[https://nobiot.github.io/org-remark/#Customizing][online]] or Info 
node `(org-remark) Customizing'.
+For customization, refer to the customization group `org-remark' or user 
manual: [[https://nobiot.github.io/org-remark/#Customizing][online]] or Info 
node `(org-remark) Customizing'. A [separate online 
article](https://github.com/nobiot/org-remark/tree/main/docs/articles/2023-08-20T184309_C_how-to-set-icons-to-be-svg-images.md)
 has been written to guide you on how to customize an icon (to be incorporated 
into the user manual later).
 
 An [[https://youtu.be/c8DHrAsFiLc][introductory video]] (8 minutes) and 
[[https://youtu.be/BTFuS21N00k][V1.1.0 release introduction]] (12 minutes) are 
available on YouTube.
 
diff --git a/docs/articles/2023-08-20T183400_how-to-buffer-window.org 
b/docs/articles/2023-08-20T183400_how-to-buffer-window.org
new file mode 100644
index 0000000000..d8f79658b9
--- /dev/null
+++ b/docs/articles/2023-08-20T183400_how-to-buffer-window.org
@@ -0,0 +1,2 @@
+Buffer window customization #43
+https://github.com/nobiot/org-remark/discussions/43
diff --git 
a/docs/articles/2023-08-20T184309_C_how-to-set-icons-to-be-svg-images.md 
b/docs/articles/2023-08-20T184309_C_how-to-set-icons-to-be-svg-images.md
new file mode 100644
index 0000000000..a542e7e69b
--- /dev/null
+++ b/docs/articles/2023-08-20T184309_C_how-to-set-icons-to-be-svg-images.md
@@ -0,0 +1,55 @@
+---
+title:    How to Set Icons to be SVG Images
+created:  2023-08-20
+modified: 20 August 2023
+category: #creation
+id:       2023-08-20T184309
+---
+
+# How to Set Org-remark to Use SVG Icons
+
+[Highlights with an icon indicating annotations 
exist](../../resources/images/v1.2.0/2023-08-20-SVG-icon.png "Highlights with 
an icon indicating annotations exist")
+
+I have released version 1.2.0 of Org-remark. In this version, highlights can 
display an icon to visually indicate that annotations exist for them. This was 
implemented in response to a feature request I received via YouTube comments 
and recorded in [issue #64](https://github.com/nobiot/org-remark/issues/64).
+
+The icon by default is a string of ASCII characters " `(*)`" so that it can be 
used for terminals. You can easily customize Org-remark to use an SVG image as 
shown in the image above.
+
+There are mainly two ways:
+
+1. Use the new `icons` library available as of Emacs version 29.1 (refer to 
Info nodes to learn more by evaluating `(info "(elisp)icons)` and `(info 
"(emacs)icons")` in Emacs)
+
+2. Create a custom function and use a third-party library such as 
[`svg-lib`](https://github.com/rougier/svg-lib) by Nicolas Rougier
+
+I will quickly show you the first option to use the new built-in library, 
which I believe is the easier.
+
+## Define an icon
+
+1. Get or create an SVG icon
+   In my example, I downloaded a "pen" icon as an `.svg` file from 
[Boxicons](https://boxicons.com/?query=pen) ([licensed under The MIT 
License](https://boxicons.com/usage#license)).
+
+2. Put the downloaded SVG file somewhere in your local.
+   I put it at `~/.config/emacs/.cache/svg/bx-pen.svg`.
+
+3. Use `define-icon` macro to create an icon with the SVG file.
+
+   For example, I used the code below. Make sure to change my example to the 
path part of the file name to your own. You can also play with the `:height` 
property as you see fit.
+
+``` emacs-lisp
+(define-icon annotation nil
+  '((image "/home/nobiot/.config/emacs/.cache/svg/bx-pen.svg"
+           :height (0.8 . em)))
+  "Notes svg icon for Org-remark"
+  :version 29.1)
+```
+
+## Customize Org-remark to use the icon
+
+Now the icon has been defined, you can set it to customizing variable 
`org-remark-icon-notes`, like so:
+
+``` emacs-lisp
+;; I use `setopt` that is made available as of 29.1. `setq` works too.
+;; Use whichever you prefer.
+(setopt org-remark-icon-notes (icon-string 'annotation))
+```
+
+If you have a buffer with highlights already open, you would need to 
`revert-buffer` to reload the highlights. You should see the icon you have 
defined instead of the default "`(*)`" string, like you see in the screen 
capture at the top of this article.
diff --git a/resources/images/v1.2.0/2023-08-20-SVG-icon.png 
b/resources/images/v1.2.0/2023-08-20-SVG-icon.png
new file mode 100644
index 0000000000..1e8cdb5856
Binary files /dev/null and b/resources/images/v1.2.0/2023-08-20-SVG-icon.png 
differ