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.
From f6891e33522c1ec321d01d8c3986fbf789c79224 Mon Sep 17 00:00:00 2001
From: Max Nikulin <maniku...@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))))
+(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
From fd6d686bb9e09981d05cbfc0ddab74dc8bcceb99 Mon Sep 17 00:00:00 2001
From: Max Nikulin <maniku...@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
From dfde96e6b31da8cb9a25c98434237da4f78272f5 Mon Sep 17 00:00:00 2001
From: Max Nikulin <maniku...@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