From: Max Nikulin <manikulin@gmail.com>
To: emacs-orgmode@gnu.org
Subject: [RFC][PATCH v2] Allow to export to ascii custom link types as notes
Date: Wed, 25 Oct 2023 22:16:41 +0700 [thread overview]
Message-ID: <uhbbgr$or9$1@ciao.gmane.io> (raw)
In-Reply-To: <87lebt8rrm.fsf@localhost>
[-- Attachment #1: Type: text/plain, Size: 813 bytes --]
On 23/10/2023 19:09, Ihor Radchenko wrote:
>>>>>> + (if (string-match-p "\\`\u200b*\\[.*\\]\u200b*\\'" anchor)
>>>>>> + anchor
>>>>>> + (format "[%s]" anchor))
>
> I did not mean unrelated to ox-ascii. I meant unrelated to "add new
> feature allowing more flexibility for :export property of links when
> exporting to ASCII".
Since "ox-ascii.el: Consistently add brackets around links" has been
committed, this regexp is not necessary to preserve inconsistencies in
link formatting. Avoiding duplication of brackets was just a bonus.
See next version of the draft. Functions are still not documented.
`cons' is made an implementation detail, however completely opaque
structure is an obstacle for derived export backend. Perhaps getter
functions should be introduced as well.
[-- Attachment #2: 0001-test-ox-ascii.el-Test-custom-links.patch --]
[-- Type: text/x-patch, Size: 4747 bytes --]
From f6891e33522c1ec321d01d8c3986fbf789c79224 Mon Sep 17 00:00:00 2001
From: Max Nikulin <manikulin@gmail.com>
Date: Fri, 20 Oct 2023 17:10:36 +0700
Subject: [PATCH 1/3] test-ox-ascii.el: Test custom links
* testing/lisp/test-ox-ascii.el (test-ox-ascii--restore-syntax)
(test-ox-ascii--link-export-inline): Helper functions.
(test-ox-ascii/link-custom-protocol-fallback)
(test-ox-ascii/link-custom-protocol-string): Test export of custom link
types having the :export parameters or relying on format provided by
default when `org-ascii-links-to-notes' enabled or disabled.
---
testing/lisp/test-ox-ascii.el | 84 +++++++++++++++++++++++++++++++++++
1 file changed, 84 insertions(+)
diff --git a/testing/lisp/test-ox-ascii.el b/testing/lisp/test-ox-ascii.el
index fe12c0c27..07def1633 100644
--- a/testing/lisp/test-ox-ascii.el
+++ b/testing/lisp/test-ox-ascii.el
@@ -27,7 +27,91 @@ (require 'ox-ascii nil t)
(unless (featurep 'ox-ascii)
(signal 'missing-test-dependency "org-export-ascii"))
+(defun test-ox-ascii--restore-syntax ()
+ (org-link-make-regexps)
+ (when (featurep 'org-element) (org-element-update-syntax)))
+
+(defun test-ox-ascii--link-export-inline (path desc backend info)
+ (and (org-export-derived-backend-p backend 'ascii)
+ (let ((description (and (org-string-nw-p desc) (org-trim desc)))
+ (target (format "(|tststr:%s|)" path)))
+ (if description
+ (format "[|%s|] %s" description target)
+ target))))
\f
+(ert-deftest test-ox-ascii/link-custom-protocol-fallback ()
+ "Test link custom protocol fallback."
+ (unwind-protect
+ (let ((org-link-parameters))
+ (org-link-set-parameters "tstdflt")
+ ;; As notes.
+ (let ((org-ascii-links-to-notes t))
+ (should ; With description.
+ (string-equal
+ (org-export-string-as
+ "Link [[tstdflt:path-descr][with description]] as note."
+ 'ascii t)
+ "Link [with description] as note.
+\n
+[with description] <tstdflt:path-descr>\n"))
+ (should ; No description.
+ (string-equal
+ (org-export-string-as
+ "Link [[tstdflt:path-no-descr]] without description (note)."
+ 'ascii t)
+ "Link <tstdflt:path-no-descr> without description (note).\n")))
+ ;; Inline.
+ (let ((org-ascii-links-to-notes nil))
+ (should ; With description.
+ (string-equal
+ (org-export-string-as
+ "Inline link [[tstdflt:path-descr][with description]]."
+ 'ascii t)
+ "Inline link [with description] (<tstdflt:path-descr>).\n"))
+ (should ; No description.
+ (string-equal
+ (org-export-string-as
+ "Inline link [[tstdflt:path-no-descr]] without description."
+ 'ascii t)
+ "Inline link <tstdflt:path-no-descr> without description.\n"))))
+ (test-ox-ascii--restore-syntax)))
+
+(ert-deftest test-ox-ascii/link-custom-protocol-string ()
+ "Test link custom protocol forced inline (string return value)."
+ (unwind-protect
+ (let ((org-link-parameters))
+ (org-link-set-parameters "tststr"
+ :export #'test-ox-ascii--link-export-inline)
+ ;; Inline despite as notes is requested.
+ (let ((org-ascii-links-to-notes t))
+ (should ; With description.
+ (string-equal
+ (org-export-string-as
+ "Link [[tststr:path-descr][with description]] as string (opt note)."
+ 'ascii t)
+ "Link [|with description|] (|tststr:path-descr|) as string (opt note).\n"))
+ (should ; No description.
+ (string-equal
+ (org-export-string-as
+ "Link [[tststr:path-no-descr]] without description as string (opt note)."
+ 'ascii t)
+ "Link (|tststr:path-no-descr|) without description as string (opt note).\n")))
+ ;; Inline.
+ (let ((org-ascii-links-to-notes nil))
+ (should ; With description.
+ (string-equal
+ (org-export-string-as
+ "Link [[tststr:path-descr][with description]] as string (opt inline)."
+ 'ascii t)
+ "Link [|with description|] (|tststr:path-descr|) as string (opt inline).\n"))
+ (should ; No description.
+ (string-equal
+ (org-export-string-as
+ "Link <tststr:path-no-descr> without description as string (opt inline)."
+ 'ascii t)
+ "Link (|tststr:path-no-descr|) without description as string (opt
+inline).\n"))))
+ (test-ox-ascii--restore-syntax)))
(ert-deftest test-ox-ascii/list ()
"Test lists."
--
2.39.2
[-- Attachment #3: 0002-ox-ascii.el-Refactor-link-export.patch --]
[-- Type: text/x-patch, Size: 4157 bytes --]
From fd6d686bb9e09981d05cbfc0ddab74dc8bcceb99 Mon Sep 17 00:00:00 2001
From: Max Nikulin <manikulin@gmail.com>
Date: Fri, 20 Oct 2023 17:29:03 +0700
Subject: [PATCH 2/3] ox-ascii.el: Refactor link export
* lisp/ox-ascii.el (org-ascii--describe-links, org-ascii-link): Avoid
duplication of fragments of code.
(org-ascii-link-inline): A new helper function for `org-ascii-link'.
Prepare to expanding `org-link-parameters' :export protocol to allow
export of custom links as notes at the end of headings.
---
lisp/ox-ascii.el | 56 +++++++++++++++++++++++++++---------------------
1 file changed, 31 insertions(+), 25 deletions(-)
diff --git a/lisp/ox-ascii.el b/lisp/ox-ascii.el
index ae4273489..10bb1fce7 100644
--- a/lisp/ox-ascii.el
+++ b/lisp/ox-ascii.el
@@ -946,11 +946,13 @@ (defun org-ascii--describe-links (links width info)
(lambda (link)
(let* ((type (org-element-property :type link))
(description (org-element-contents link))
+ (raw-link (org-element-property :raw-link link))
(anchor (org-export-data
- (or description (org-element-property :raw-link link))
- info)))
+ (or description raw-link)
+ info))
+ location)
(cond
- ((member type '("coderef" "radio")) nil)
+ ((member type '("coderef" "radio")))
((member type '("custom-id" "fuzzy" "id"))
;; Only links with a description need an entry. Other are
;; already handled in `org-ascii-link'.
@@ -963,25 +965,24 @@ (defun org-ascii--describe-links (links width info)
(condition-case nil
(org-export-resolve-id-link link info)
(org-link-broken nil)))))
- (when dest
- (concat
- (org-ascii--fill-string
- (format "[%s] %s" anchor (org-ascii--describe-datum dest info))
- width info)
- "\n\n")))))
+ (setq location
+ (and dest (org-ascii--describe-datum dest info))))))
;; Do not add a link that cannot be resolved and doesn't have
;; any description: destination is already visible in the
;; paragraph.
- ((not (org-element-contents link)) nil)
+ ((not description))
;; Do not add a link already handled by custom export
;; functions.
((org-export-custom-protocol-maybe link anchor 'ascii info) nil)
- (t
- (concat
- (org-ascii--fill-string
- (format "[%s] <%s>" anchor (org-element-property :raw-link link))
- width info)
- "\n\n")))))
+ (t (setq location (format "<%s>" raw-link))))
+ (and
+ location
+ anchor
+ (concat
+ (org-ascii--fill-string
+ (format "[%s] %s" anchor location)
+ width info)
+ "\n\n"))))
links ""))
(defun org-ascii--checkbox (item info)
@@ -1584,6 +1585,15 @@ (defun org-ascii-line-break (_line-break _contents _info)
;;;; Link
+(defun org-ascii-link-inline (link desc info)
+ (cond
+ ((not desc) link)
+ ((plist-get info :ascii-links-to-notes)
+ (format "[%s]" desc))
+ ((string-match-p "\\`(.*)\\'" link)
+ (format "[%s] %s" desc link))
+ (t (format "[%s] (%s)" desc link))))
+
(defun org-ascii-link (link desc info)
"Transcode a LINK object from Org to ASCII.
@@ -1605,11 +1615,10 @@ (defun org-ascii-link (link desc info)
(org-export-resolve-id-link link info))))
(pcase (org-element-type destination)
((guard desc)
- (if (plist-get info :ascii-links-to-notes)
- (format "[%s]" desc)
- (format "[%s] (%s)"
- desc
- (org-ascii--describe-datum destination info))))
+ (org-ascii-link-inline
+ (org-ascii--describe-datum destination info)
+ desc
+ info))
;; External file.
(`plain-text destination)
(`headline
@@ -1628,10 +1637,7 @@ (defun org-ascii-link (link desc info)
(_ "???"))))
(t
(let ((path (org-element-property :raw-link link)))
- (if (not (org-string-nw-p desc)) (format "<%s>" path)
- (concat (format "[%s]" desc)
- (and (not (plist-get info :ascii-links-to-notes))
- (format " (<%s>)" path)))))))))
+ (org-ascii-link-inline (format "<%s>" path) desc info))))))
;;;; Node Properties
--
2.39.2
[-- Attachment #4: 0003-ox-ascii.el-Allow-to-export-custom-links-as-notes.patch --]
[-- Type: text/x-patch, Size: 10553 bytes --]
From dfde96e6b31da8cb9a25c98434237da4f78272f5 Mon Sep 17 00:00:00 2001
From: Max Nikulin <manikulin@gmail.com>
Date: Fri, 20 Oct 2023 23:35:16 +0700
Subject: [PATCH 3/3] ox-ascii.el: Allow to export custom links as notes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
* lisp/ox-ascii.el (org-ascii-make-link-formatted): New function whose
value may be returned by the :export property of `org-link-parameters'
to create links optionally formatted similar to footnotes.
(org-ascii--describe-links, org-ascii-link): Handle values returned by
`org-ascii-make-link-formatted'. It allows to respect
`org-ascii-links-to-notes' for custom link types.
* testing/lisp/test-ox-ascii.el
(test-ox-ascii/link-custom-protocol-cons): New test for the added
feature.
* lisp/ol-man.el (org-man-export):
* lisp/ol-docview.el (org-docview-export): Allow to export links to man
pages and to documents as notes at the end of heading.
See the following mailing list thread:
Ihor Radchenko to emacs-orgmode… Re: Exporting elisp: and shell: links.
Sat, 14 Oct 2023 08:13:35 +0000.
https://list.orgmode.org/87wmvp1v0w.fsf@localhost
---
lisp/ol-docview.el | 6 ++-
lisp/ol-man.el | 6 ++-
lisp/ox-ascii.el | 34 ++++++++++++--
testing/lisp/test-ox-ascii.el | 83 +++++++++++++++++++++++++++++++++++
4 files changed, 121 insertions(+), 8 deletions(-)
diff --git a/lisp/ol-docview.el b/lisp/ol-docview.el
index bcb26520b..fd945fe2e 100644
--- a/lisp/ol-docview.el
+++ b/lisp/ol-docview.el
@@ -51,13 +51,14 @@ (require 'ol)
(declare-function doc-view-goto-page "doc-view" (page))
(declare-function image-mode-window-get "image-mode" (prop &optional winprops))
(declare-function org-open-file "org" (path &optional in-emacs line search))
+(declare-function org-ascii-make-link-formatted "ox-ascii" (path desc info))
(org-link-set-parameters "docview"
:follow #'org-docview-open
:export #'org-docview-export
:store #'org-docview-store-link)
-(defun org-docview-export (link description backend _info)
+(defun org-docview-export (link description backend info)
"Export a docview LINK with DESCRIPTION for BACKEND."
(let ((path (if (string-match "\\(.+\\)::.+" link) (match-string 1 link)
link))
@@ -67,7 +68,8 @@ (defun org-docview-export (link description backend _info)
(cond
((eq backend 'html) (format "<a href=\"%s\">%s</a>" path desc))
((eq backend 'latex) (format "\\href{%s}{%s}" path desc))
- ((eq backend 'ascii) (format "[%s] (<%s>)" desc path))
+ ((eq backend 'ascii)
+ (org-ascii-make-link-formatted (format "(<%s>)" path) desc info))
(t path)))))
(defun org-docview-open (link _)
diff --git a/lisp/ol-man.el b/lisp/ol-man.el
index b0701c689..da1cca9ed 100644
--- a/lisp/ol-man.el
+++ b/lisp/ol-man.el
@@ -33,6 +33,8 @@ (org-assert-version)
(require 'ol)
+(declare-function org-ascii-make-link-formatted "ox-ascii" (path desc info))
+
(org-link-set-parameters "man"
:follow #'org-man-open
:export #'org-man-export
@@ -86,7 +88,7 @@ (defun org-man-get-page-name ()
(match-string 1 (buffer-name))
(error "Cannot create link to this man page")))
-(defun org-man-export (link description backend)
+(defun org-man-export (link description backend info)
"Export a man page LINK with DESCRIPTION.
BACKEND is the current export backend."
(let ((path (format "http://man.he.net/?topic=%s§ion=all" link))
@@ -95,7 +97,7 @@ (defun org-man-export (link description backend)
((eq backend 'html) (format "<a target=\"_blank\" href=\"%s\">%s</a>" path desc))
((eq backend 'latex) (format "\\href{%s}{%s}" path desc))
((eq backend 'texinfo) (format "@uref{%s,%s}" path desc))
- ((eq backend 'ascii) (format "[%s] (<%s>)" desc path))
+ ((eq backend 'ascii) (org-ascii-make-link-formatted (format "<%s>" path) desc info))
((eq backend 'md) (format "[%s](%s)" desc path))
(t path))))
diff --git a/lisp/ox-ascii.el b/lisp/ox-ascii.el
index 10bb1fce7..722b2aa4c 100644
--- a/lisp/ox-ascii.el
+++ b/lisp/ox-ascii.el
@@ -967,13 +967,26 @@ (defun org-ascii--describe-links (links width info)
(org-link-broken nil)))))
(setq location
(and dest (org-ascii--describe-datum dest info))))))
+ ;; Do not add a link already handled by custom export
+ ;; functions.
+ ((pcase (org-export-custom-protocol-maybe
+ link
+ (and description (org-export-data description info))
+ 'ascii
+ info)
+ ((pred null))
+ ((pred stringp) t)
+ (`(,(and (or `nil (pred stringp)) path) .
+ ,(and (or `nil (pred stringp)) desc))
+ (setq location (org-string-nw-p path))
+ (setq anchor desc)
+ t)
+ (_ (error "Link :export returned not cons, or string, or nil: %s"
+ raw-link))))
;; Do not add a link that cannot be resolved and doesn't have
;; any description: destination is already visible in the
;; paragraph.
((not description))
- ;; Do not add a link already handled by custom export
- ;; functions.
- ((org-export-custom-protocol-maybe link anchor 'ascii info) nil)
(t (setq location (format "<%s>" raw-link))))
(and
location
@@ -1601,7 +1614,15 @@ (defun org-ascii-link (link desc info)
INFO is a plist holding contextual information."
(let ((type (org-element-property :type link)))
(cond
- ((org-export-custom-protocol-maybe link desc 'ascii info))
+ ((pcase (org-export-custom-protocol-maybe link desc 'ascii info)
+ ((pred null) nil) ; Use fallback.
+ ((and (pred stringp) str) str)
+ (`(nil . nil) "")
+ (`(,(and (or `nil (pred stringp)) custom-path) .
+ ,(and (or `nil (pred stringp)) custom-desc))
+ (org-ascii-link-inline custom-path custom-desc info))
+ (_ (error "Link :export returned not cons, or string, or nil: %s"
+ (org-element-property :raw-link link)))))
((string= type "coderef")
(let ((ref (org-element-property :path link)))
(format (org-export-get-coderef-format ref desc)
@@ -2224,6 +2245,11 @@ (defun org-ascii-publish-to-utf8 (plist filename pub-dir)
(org-publish-org-to
'ascii filename ".txt" `(:ascii-charset utf-8 ,@plist) pub-dir))
+(defun org-ascii-make-link-formatted (path descr _info)
+ "To be used in :export property of `org-link-parameters'.
+Returns an opaque type interpreted by `org-ascii-link'."
+ (cons path descr))
+
(provide 'ox-ascii)
diff --git a/testing/lisp/test-ox-ascii.el b/testing/lisp/test-ox-ascii.el
index 07def1633..5165e867c 100644
--- a/testing/lisp/test-ox-ascii.el
+++ b/testing/lisp/test-ox-ascii.el
@@ -113,6 +113,89 @@ (ert-deftest test-ox-ascii/link-custom-protocol-string ()
inline).\n"))))
(test-ox-ascii--restore-syntax)))
+(ert-deftest test-ox-ascii/link-custom-protocol-cons ()
+ "Test of custom link type optionally exported as a note."
+ (unwind-protect
+ (let ((org-link-parameters))
+ (org-link-set-parameters
+ "tstcons"
+ :export (lambda (path descr _backend info)
+ (org-ascii-make-link-formatted
+ (concat "excons-" path) descr info)))
+ ;; As notes.
+ (let ((org-ascii-links-to-notes t))
+ (should ; With description.
+ (string-equal
+ (org-export-string-as
+ "Link [[tstcons:path-descr][with descr[iption]\u200b]] as note."
+ 'ascii t)
+ "Link [with descr[iption]\u200b] as note.
+\n
+[with descr[iption]\u200b] excons-path-descr\n"))
+ (should ; No description.
+ (string-equal
+ (org-export-string-as
+ "Link <tstcons:path-no-descr> without description (note)."
+ 'ascii t)
+ "Link excons-path-no-descr without description (note).\n")))
+ ;; Inline.
+ (let ((org-ascii-links-to-notes nil))
+ (should ; With description.
+ (string-equal
+ (org-export-string-as
+ "Inline link [[tstcons:path-descr][with description]]."
+ 'ascii t)
+ "Inline link [with description] (excons-path-descr).\n"))
+ (should ; No description.
+ (string-equal
+ (org-export-string-as
+ "Inline link [[tstcons:path-no-descr]] without description."
+ 'ascii t)
+ "Inline link excons-path-no-descr without description.\n")))
+ ;; Ugly formatting with duplicated brackets.
+ ;; Behavior likely should be changed to not add another pair of brackets.
+ (let ((org-link-parameters))
+ (org-link-set-parameters
+ "brcons"
+ :export (lambda (path descr _backend info)
+ (org-ascii-make-link-formatted
+ (format "(exbr-%s)" path)
+ (and descr (format "[%s]" descr))
+ info)))
+ (let ((org-ascii-links-to-notes t))
+ (should
+ (string-equal
+ (org-export-string-as
+ "Link [[brcons:path-descr][with brackets]] as note."
+ 'ascii t)
+ "Link [[with brackets]] as note.
+\n
+[[with brackets]] (exbr-path-descr)\n")))
+ ;; Inline.
+ (let ((org-ascii-links-to-notes nil))
+ (should
+ (string-equal
+ (org-export-string-as
+ "Link [[brcons:path-descr][with brackets]] inline."
+ 'ascii t)
+ "Link [[with brackets]] (exbr-path-descr) inline.\n"))))
+ ;; Error.
+ (org-link-set-parameters
+ "tsterr"
+ :export (lambda (path descr _backend _info)
+ (list (concat "ex-error! " path) descr "extra arg")))
+ (let* ((err (should-error
+ (org-export-string-as
+ "Signals [[tsterr:invalid :export][aaa]] error."
+ 'ascii t)
+ :type 'error))
+ (err-text (cadr err)))
+ (should-not (unless (and (stringp err-text)
+ (string-match-p "\\`Link :export returned not.*"
+ err-text))
+ err))))
+ (test-ox-ascii--restore-syntax)))
+
(ert-deftest test-ox-ascii/list ()
"Test lists."
;; Number counter.
--
2.39.2
next prev parent reply other threads:[~2023-10-25 15:18 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-10-20 17:21 [RFC][PATCH] Allow to export to ascii custom link types as notes Max Nikulin
2023-10-22 9:13 ` Ihor Radchenko
2023-10-22 17:05 ` Max Nikulin
2023-10-23 9:17 ` Ihor Radchenko
2023-10-23 11:00 ` Max Nikulin
2023-10-23 12:09 ` Ihor Radchenko
2023-10-24 8:11 ` Max Nikulin
2023-10-24 10:40 ` Ihor Radchenko
2023-10-24 15:06 ` [PATCH] ox-ascii.el: Consistently add brackets around links (was: Re: [RFC][PATCH] Allow to export to ascii custom link types as notes) Max Nikulin
2023-10-25 10:34 ` Ihor Radchenko
2023-10-26 16:46 ` man pages references (Re: [PATCH] ox-ascii.el: Consistently add brackets around links) Max Nikulin
2023-11-05 12:08 ` Ihor Radchenko
2023-10-27 14:36 ` [RFC][PATCH] Allow to export to ascii custom link types as notes Max Nikulin
2023-10-25 15:16 ` Max Nikulin [this message]
2023-11-07 9:30 ` [RFC][PATCH v2] " Ihor Radchenko
2023-11-07 11:48 ` Max Nikulin
2023-11-07 11:58 ` Ihor Radchenko
2023-11-08 10:23 ` Max Nikulin
2023-11-08 10:45 ` Ihor Radchenko
2023-11-08 10:57 ` Max Nikulin
2023-11-08 11:16 ` Ihor Radchenko
2023-11-09 11:12 ` Max Nikulin
2023-11-11 11:17 ` Ihor Radchenko
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='uhbbgr$or9$1@ciao.gmane.io' \
--to=manikulin@gmail.com \
--cc=emacs-orgmode@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).