Merge branch 'maint'
[org-mode/org-tableheadings.git] / lisp / ox-ascii.el
blob2a129e9de78fd4fdcfe5a2cbef9e50689af6d255
1 ;;; ox-ascii.el --- ASCII Back-End for Org Export Engine -*- lexical-binding: t; -*-
3 ;; Copyright (C) 2012-2017 Free Software Foundation, Inc.
5 ;; Author: Nicolas Goaziou <n.goaziou at gmail dot com>
6 ;; Keywords: outlines, hypermedia, calendar, wp
8 ;; This file is part of GNU Emacs.
10 ;; GNU Emacs is free software: you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation, either version 3 of the License, or
13 ;; (at your option) any later version.
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
23 ;;; Commentary:
25 ;; This library implements an ASCII back-end for Org generic exporter.
26 ;; See Org manual for more information.
28 ;;; Code:
30 (require 'ox)
31 (require 'ox-publish)
32 (require 'cl-lib)
34 (declare-function aa2u "ext:ascii-art-to-unicode" ())
36 ;;; Define Back-End
38 ;; The following setting won't allow modifying preferred charset
39 ;; through a buffer keyword or an option item, but, since the property
40 ;; will appear in communication channel nonetheless, it allows
41 ;; overriding `org-ascii-charset' variable on the fly by the ext-plist
42 ;; mechanism.
44 ;; We also install a filter for headlines and sections, in order to
45 ;; control blank lines separating them in output string.
47 (org-export-define-backend 'ascii
48 '((bold . org-ascii-bold)
49 (center-block . org-ascii-center-block)
50 (clock . org-ascii-clock)
51 (code . org-ascii-code)
52 (drawer . org-ascii-drawer)
53 (dynamic-block . org-ascii-dynamic-block)
54 (entity . org-ascii-entity)
55 (example-block . org-ascii-example-block)
56 (export-block . org-ascii-export-block)
57 (export-snippet . org-ascii-export-snippet)
58 (fixed-width . org-ascii-fixed-width)
59 (footnote-reference . org-ascii-footnote-reference)
60 (headline . org-ascii-headline)
61 (horizontal-rule . org-ascii-horizontal-rule)
62 (inline-src-block . org-ascii-inline-src-block)
63 (inlinetask . org-ascii-inlinetask)
64 (inner-template . org-ascii-inner-template)
65 (italic . org-ascii-italic)
66 (item . org-ascii-item)
67 (keyword . org-ascii-keyword)
68 (latex-environment . org-ascii-latex-environment)
69 (latex-fragment . org-ascii-latex-fragment)
70 (line-break . org-ascii-line-break)
71 (link . org-ascii-link)
72 (node-property . org-ascii-node-property)
73 (paragraph . org-ascii-paragraph)
74 (plain-list . org-ascii-plain-list)
75 (plain-text . org-ascii-plain-text)
76 (planning . org-ascii-planning)
77 (property-drawer . org-ascii-property-drawer)
78 (quote-block . org-ascii-quote-block)
79 (radio-target . org-ascii-radio-target)
80 (section . org-ascii-section)
81 (special-block . org-ascii-special-block)
82 (src-block . org-ascii-src-block)
83 (statistics-cookie . org-ascii-statistics-cookie)
84 (strike-through . org-ascii-strike-through)
85 (subscript . org-ascii-subscript)
86 (superscript . org-ascii-superscript)
87 (table . org-ascii-table)
88 (table-cell . org-ascii-table-cell)
89 (table-row . org-ascii-table-row)
90 (target . org-ascii-target)
91 (template . org-ascii-template)
92 (timestamp . org-ascii-timestamp)
93 (underline . org-ascii-underline)
94 (verbatim . org-ascii-verbatim)
95 (verse-block . org-ascii-verse-block))
96 :menu-entry
97 '(?t "Export to Plain Text"
98 ((?A "As ASCII buffer"
99 (lambda (a s v b)
100 (org-ascii-export-as-ascii a s v b '(:ascii-charset ascii))))
101 (?a "As ASCII file"
102 (lambda (a s v b)
103 (org-ascii-export-to-ascii a s v b '(:ascii-charset ascii))))
104 (?L "As Latin1 buffer"
105 (lambda (a s v b)
106 (org-ascii-export-as-ascii a s v b '(:ascii-charset latin1))))
107 (?l "As Latin1 file"
108 (lambda (a s v b)
109 (org-ascii-export-to-ascii a s v b '(:ascii-charset latin1))))
110 (?U "As UTF-8 buffer"
111 (lambda (a s v b)
112 (org-ascii-export-as-ascii a s v b '(:ascii-charset utf-8))))
113 (?u "As UTF-8 file"
114 (lambda (a s v b)
115 (org-ascii-export-to-ascii a s v b '(:ascii-charset utf-8))))))
116 :filters-alist '((:filter-headline . org-ascii-filter-headline-blank-lines)
117 (:filter-parse-tree org-ascii-filter-paragraph-spacing
118 org-ascii-filter-comment-spacing)
119 (:filter-section . org-ascii-filter-headline-blank-lines))
120 :options-alist
121 '((:subtitle "SUBTITLE" nil nil parse)
122 (:ascii-bullets nil nil org-ascii-bullets)
123 (:ascii-caption-above nil nil org-ascii-caption-above)
124 (:ascii-charset nil nil org-ascii-charset)
125 (:ascii-global-margin nil nil org-ascii-global-margin)
126 (:ascii-format-drawer-function nil nil org-ascii-format-drawer-function)
127 (:ascii-format-inlinetask-function
128 nil nil org-ascii-format-inlinetask-function)
129 (:ascii-headline-spacing nil nil org-ascii-headline-spacing)
130 (:ascii-indented-line-width nil nil org-ascii-indented-line-width)
131 (:ascii-inlinetask-width nil nil org-ascii-inlinetask-width)
132 (:ascii-inner-margin nil nil org-ascii-inner-margin)
133 (:ascii-links-to-notes nil nil org-ascii-links-to-notes)
134 (:ascii-list-margin nil nil org-ascii-list-margin)
135 (:ascii-paragraph-spacing nil nil org-ascii-paragraph-spacing)
136 (:ascii-quote-margin nil nil org-ascii-quote-margin)
137 (:ascii-table-keep-all-vertical-lines
138 nil nil org-ascii-table-keep-all-vertical-lines)
139 (:ascii-table-use-ascii-art nil nil org-ascii-table-use-ascii-art)
140 (:ascii-table-widen-columns nil nil org-ascii-table-widen-columns)
141 (:ascii-text-width nil nil org-ascii-text-width)
142 (:ascii-underline nil nil org-ascii-underline)
143 (:ascii-verbatim-format nil nil org-ascii-verbatim-format)))
147 ;;; User Configurable Variables
149 (defgroup org-export-ascii nil
150 "Options for exporting Org mode files to ASCII."
151 :tag "Org Export ASCII"
152 :group 'org-export)
154 (defcustom org-ascii-text-width 72
155 "Maximum width of exported text.
156 This number includes margin size, as set in
157 `org-ascii-global-margin'."
158 :group 'org-export-ascii
159 :version "24.4"
160 :package-version '(Org . "8.0")
161 :type 'integer)
163 (defcustom org-ascii-global-margin 0
164 "Width of the left margin, in number of characters."
165 :group 'org-export-ascii
166 :version "24.4"
167 :package-version '(Org . "8.0")
168 :type 'integer)
170 (defcustom org-ascii-inner-margin 2
171 "Width of the inner margin, in number of characters.
172 Inner margin is applied between each headline."
173 :group 'org-export-ascii
174 :version "24.4"
175 :package-version '(Org . "8.0")
176 :type 'integer)
178 (defcustom org-ascii-quote-margin 6
179 "Width of margin used for quoting text, in characters.
180 This margin is applied on both sides of the text."
181 :group 'org-export-ascii
182 :version "24.4"
183 :package-version '(Org . "8.0")
184 :type 'integer)
186 (defcustom org-ascii-list-margin 0
187 "Width of margin used for plain lists, in characters.
188 This margin applies to top level list only, not to its
189 sub-lists."
190 :group 'org-export-ascii
191 :version "26.1"
192 :package-version '(Org . "8.3")
193 :type 'integer)
195 (defcustom org-ascii-inlinetask-width 30
196 "Width of inline tasks, in number of characters.
197 This number ignores any margin."
198 :group 'org-export-ascii
199 :version "24.4"
200 :package-version '(Org . "8.0")
201 :type 'integer)
203 (defcustom org-ascii-headline-spacing '(1 . 2)
204 "Number of blank lines inserted around headlines.
206 This variable can be set to a cons cell. In that case, its car
207 represents the number of blank lines present before headline
208 contents whereas its cdr reflects the number of blank lines after
209 contents.
211 A nil value replicates the number of blank lines found in the
212 original Org buffer at the same place."
213 :group 'org-export-ascii
214 :version "24.4"
215 :package-version '(Org . "8.0")
216 :type '(choice
217 (const :tag "Replicate original spacing" nil)
218 (cons :tag "Set a uniform spacing"
219 (integer :tag "Number of blank lines before contents")
220 (integer :tag "Number of blank lines after contents"))))
222 (defcustom org-ascii-indented-line-width 'auto
223 "Additional indentation width for the first line in a paragraph.
224 If the value is an integer, indent the first line of each
225 paragraph by this width, unless it is located at the beginning of
226 a section, in which case indentation is removed from that line.
227 If it is the symbol `auto' preserve indentation from original
228 document."
229 :group 'org-export-ascii
230 :version "24.4"
231 :package-version '(Org . "8.0")
232 :type '(choice
233 (integer :tag "Number of white spaces characters")
234 (const :tag "Preserve original width" auto)))
236 (defcustom org-ascii-paragraph-spacing 'auto
237 "Number of white lines between paragraphs.
238 If the value is an integer, add this number of blank lines
239 between contiguous paragraphs. If is it the symbol `auto', keep
240 the same number of blank lines as in the original document."
241 :group 'org-export-ascii
242 :version "24.4"
243 :package-version '(Org . "8.0")
244 :type '(choice
245 (integer :tag "Number of blank lines")
246 (const :tag "Preserve original spacing" auto)))
248 (defcustom org-ascii-charset 'ascii
249 "The charset allowed to represent various elements and objects.
250 Possible values are:
251 `ascii' Only use plain ASCII characters
252 `latin1' Include Latin-1 characters
253 `utf-8' Use all UTF-8 characters"
254 :group 'org-export-ascii
255 :version "24.4"
256 :package-version '(Org . "8.0")
257 :type '(choice
258 (const :tag "ASCII" ascii)
259 (const :tag "Latin-1" latin1)
260 (const :tag "UTF-8" utf-8)))
262 (defcustom org-ascii-underline '((ascii ?= ?~ ?-)
263 (latin1 ?= ?~ ?-)
264 (utf-8 ?═ ?─ ?╌ ?┄ ?┈))
265 "Characters for underlining headings in ASCII export.
267 Alist whose key is a symbol among `ascii', `latin1' and `utf-8'
268 and whose value is a list of characters.
270 For each supported charset, this variable associates a sequence
271 of underline characters. In a sequence, the characters will be
272 used in order for headlines level 1, 2, ... If no character is
273 available for a given level, the headline won't be underlined."
274 :group 'org-export-ascii
275 :version "24.4"
276 :package-version '(Org . "8.0")
277 :type '(list
278 (cons :tag "Underline characters sequence"
279 (const :tag "ASCII charset" ascii)
280 (repeat character))
281 (cons :tag "Underline characters sequence"
282 (const :tag "Latin-1 charset" latin1)
283 (repeat character))
284 (cons :tag "Underline characters sequence"
285 (const :tag "UTF-8 charset" utf-8)
286 (repeat character))))
288 (defcustom org-ascii-bullets '((ascii ?* ?+ ?-)
289 (latin1 ?§ ?¶)
290 (utf-8 ?◊))
291 "Bullet characters for headlines converted to lists in ASCII export.
293 Alist whose key is a symbol among `ascii', `latin1' and `utf-8'
294 and whose value is a list of characters.
296 The first character is used for the first level considered as low
297 level, and so on. If there are more levels than characters given
298 here, the list will be repeated.
300 Note that this variable doesn't affect plain lists
301 representation."
302 :group 'org-export-ascii
303 :version "24.4"
304 :package-version '(Org . "8.0")
305 :type '(list
306 (cons :tag "Bullet characters for low level headlines"
307 (const :tag "ASCII charset" ascii)
308 (repeat character))
309 (cons :tag "Bullet characters for low level headlines"
310 (const :tag "Latin-1 charset" latin1)
311 (repeat character))
312 (cons :tag "Bullet characters for low level headlines"
313 (const :tag "UTF-8 charset" utf-8)
314 (repeat character))))
316 (defcustom org-ascii-links-to-notes t
317 "Non-nil means convert links to notes before the next headline.
318 When nil, the link will be exported in place. If the line
319 becomes long in this way, it will be wrapped."
320 :group 'org-export-ascii
321 :version "24.4"
322 :package-version '(Org . "8.0")
323 :type 'boolean)
325 (defcustom org-ascii-table-keep-all-vertical-lines nil
326 "Non-nil means keep all vertical lines in ASCII tables.
327 When nil, vertical lines will be removed except for those needed
328 for column grouping."
329 :group 'org-export-ascii
330 :version "24.4"
331 :package-version '(Org . "8.0")
332 :type 'boolean)
334 (defcustom org-ascii-table-widen-columns t
335 "Non-nil means widen narrowed columns for export.
336 When nil, narrowed columns will look in ASCII export just like in
337 Org mode, i.e. with \"=>\" as ellipsis."
338 :group 'org-export-ascii
339 :version "24.4"
340 :package-version '(Org . "8.0")
341 :type 'boolean)
343 (defcustom org-ascii-table-use-ascii-art nil
344 "Non-nil means table.el tables are turned into ascii-art.
346 It only makes sense when export charset is `utf-8'. It is nil by
347 default since it requires ascii-art-to-unicode.el package. You
348 can download it here:
350 http://gnuvola.org/software/j/aa2u/ascii-art-to-unicode.el."
351 :group 'org-export-ascii
352 :version "24.4"
353 :package-version '(Org . "8.0")
354 :type 'boolean)
356 (defcustom org-ascii-caption-above nil
357 "When non-nil, place caption string before the element.
358 Otherwise, place it right after it."
359 :group 'org-export-ascii
360 :version "24.4"
361 :package-version '(Org . "8.0")
362 :type 'boolean)
364 (defcustom org-ascii-verbatim-format "`%s'"
365 "Format string used for verbatim text and inline code."
366 :group 'org-export-ascii
367 :version "24.4"
368 :package-version '(Org . "8.0")
369 :type 'string)
371 (defcustom org-ascii-format-drawer-function
372 (lambda (_name contents _width) contents)
373 "Function called to format a drawer in ASCII.
375 The function must accept three parameters:
376 NAME the drawer name, like \"LOGBOOK\"
377 CONTENTS the contents of the drawer.
378 WIDTH the text width within the drawer.
380 The function should return either the string to be exported or
381 nil to ignore the drawer.
383 The default value simply returns the value of CONTENTS."
384 :group 'org-export-ascii
385 :version "24.4"
386 :package-version '(Org . "8.0")
387 :type 'function)
389 (defcustom org-ascii-format-inlinetask-function
390 'org-ascii-format-inlinetask-default
391 "Function called to format an inlinetask in ASCII.
393 The function must accept nine parameters:
394 TODO the todo keyword, as a string
395 TODO-TYPE the todo type, a symbol among `todo', `done' and nil.
396 PRIORITY the inlinetask priority, as a string
397 NAME the inlinetask name, as a string.
398 TAGS the inlinetask tags, as a list of strings.
399 CONTENTS the contents of the inlinetask, as a string.
400 WIDTH the width of the inlinetask, as a number.
401 INLINETASK the inlinetask itself.
402 INFO the info channel.
404 The function should return either the string to be exported or
405 nil to ignore the inline task."
406 :group 'org-export-ascii
407 :version "24.4"
408 :package-version '(Org . "8.3")
409 :type 'function)
413 ;;; Internal Functions
415 ;; Internal functions fall into three categories.
417 ;; The first one is about text formatting. The core functions are
418 ;; `org-ascii--current-text-width' and
419 ;; `org-ascii--current-justification', which determine, respectively,
420 ;; the current text width allowed to a given element and its expected
421 ;; justification. Once this information is known,
422 ;; `org-ascii--fill-string', `org-ascii--justify-lines',
423 ;; `org-ascii--justify-element' `org-ascii--box-string' and
424 ;; `org-ascii--indent-string' can operate on a given output string.
425 ;; In particular, justification happens at the regular (i.e.,
426 ;; non-greater) element level, which means that when the exporting
427 ;; process reaches a container (e.g., a center block) content are
428 ;; already justified.
430 ;; The second category contains functions handling elements listings,
431 ;; triggered by "#+TOC:" keyword. As such, `org-ascii--build-toc'
432 ;; returns a complete table of contents, `org-ascii--list-listings'
433 ;; returns a list of referenceable src-block elements, and
434 ;; `org-ascii--list-tables' does the same for table elements.
436 ;; The third category includes general helper functions.
437 ;; `org-ascii--build-title' creates the title for a given headline
438 ;; or inlinetask element. `org-ascii--build-caption' returns the
439 ;; caption string associated to a table or a src-block.
440 ;; `org-ascii--describe-links' creates notes about links for
441 ;; insertion at the end of a section. It uses
442 ;; `org-ascii--unique-links' to get the list of links to describe.
443 ;; Eventually, `org-ascii--translate' translates a string according
444 ;; to language and charset specification.
447 (defun org-ascii--fill-string (s text-width info &optional justify)
448 "Fill a string with specified text-width and return it.
450 S is the string being filled. TEXT-WIDTH is an integer
451 specifying maximum length of a line. INFO is the plist used as
452 a communication channel.
454 Optional argument JUSTIFY can specify any type of justification
455 among `left', `center', `right' or `full'. A nil value is
456 equivalent to `left'. For a justification that doesn't also fill
457 string, see `org-ascii--justify-lines' and
458 `org-ascii--justify-block'.
460 Return nil if S isn't a string."
461 (when (stringp s)
462 (let ((double-space-p sentence-end-double-space))
463 (with-temp-buffer
464 (let ((fill-column text-width)
465 (use-hard-newlines t)
466 (sentence-end-double-space double-space-p))
467 (insert (if (plist-get info :preserve-breaks)
468 (replace-regexp-in-string "\n" hard-newline s)
470 (fill-region (point-min) (point-max) justify))
471 (buffer-string)))))
473 (defun org-ascii--justify-lines (s text-width how)
474 "Justify all lines in string S.
475 TEXT-WIDTH is an integer specifying maximum length of a line.
476 HOW determines the type of justification: it can be `left',
477 `right', `full' or `center'."
478 (with-temp-buffer
479 (insert s)
480 (goto-char (point-min))
481 (let ((fill-column text-width)
482 ;; Disable `adaptive-fill-mode' so it doesn't prevent
483 ;; filling lines matching `adaptive-fill-regexp'.
484 (adaptive-fill-mode nil))
485 (while (< (point) (point-max))
486 (justify-current-line how)
487 (forward-line)))
488 (buffer-string)))
490 (defun org-ascii--justify-element (contents element info)
491 "Justify CONTENTS of ELEMENT.
492 INFO is a plist used as a communication channel. Justification
493 is done according to the type of element. More accurately,
494 paragraphs are filled and other elements are justified as blocks,
495 that is according to the widest non blank line in CONTENTS."
496 (if (not (org-string-nw-p contents)) contents
497 (let ((text-width (org-ascii--current-text-width element info))
498 (how (org-ascii--current-justification element)))
499 (cond
500 ((eq (org-element-type element) 'paragraph)
501 ;; Paragraphs are treated specially as they need to be filled.
502 (org-ascii--fill-string contents text-width info how))
503 ((eq how 'left) contents)
504 (t (with-temp-buffer
505 (insert contents)
506 (goto-char (point-min))
507 (catch 'exit
508 (let ((max-width 0))
509 ;; Compute maximum width. Bail out if it is greater
510 ;; than page width, since no justification is
511 ;; possible.
512 (save-excursion
513 (while (not (eobp))
514 (unless (looking-at-p "[ \t]*$")
515 (end-of-line)
516 (let ((column (current-column)))
517 (cond
518 ((>= column text-width) (throw 'exit contents))
519 ((> column max-width) (setq max-width column)))))
520 (forward-line)))
521 ;; Justify every line according to TEXT-WIDTH and
522 ;; MAX-WIDTH.
523 (let ((offset (/ (- text-width max-width)
524 (if (eq how 'right) 1 2))))
525 (if (zerop offset) (throw 'exit contents)
526 (while (not (eobp))
527 (unless (looking-at-p "[ \t]*$")
528 (indent-to-column offset))
529 (forward-line)))))
530 (buffer-string))))))))
532 (defun org-ascii--indent-string (s width)
533 "Indent string S by WIDTH white spaces.
534 Empty lines are not indented."
535 (when (stringp s)
536 (replace-regexp-in-string
537 "\\(^\\)[ \t]*\\S-" (make-string width ?\s) s nil nil 1)))
539 (defun org-ascii--box-string (s info)
540 "Return string S with a partial box to its left.
541 INFO is a plist used as a communication channel."
542 (let ((utf8p (eq (plist-get info :ascii-charset) 'utf-8)))
543 (format (if utf8p "┌────\n%s\n└────" ",----\n%s\n`----")
544 (replace-regexp-in-string
545 "^" (if utf8p "│ " "| ")
546 ;; Remove last newline character.
547 (replace-regexp-in-string "\n[ \t]*\\'" "" s)))))
549 (defun org-ascii--current-text-width (element info)
550 "Return maximum text width for ELEMENT's contents.
551 INFO is a plist used as a communication channel."
552 (pcase (org-element-type element)
553 ;; Elements with an absolute width: `headline' and `inlinetask'.
554 (`inlinetask (plist-get info :ascii-inlinetask-width))
555 (`headline
556 (- (plist-get info :ascii-text-width)
557 (let ((low-level-rank (org-export-low-level-p element info)))
558 (if low-level-rank (* low-level-rank 2)
559 (plist-get info :ascii-global-margin)))))
560 ;; Elements with a relative width: store maximum text width in
561 ;; TOTAL-WIDTH.
563 (let* ((genealogy (org-element-lineage element nil t))
564 ;; Total width is determined by the presence, or not, of an
565 ;; inline task among ELEMENT parents.
566 (total-width
567 (if (cl-some (lambda (parent)
568 (eq (org-element-type parent) 'inlinetask))
569 genealogy)
570 (plist-get info :ascii-inlinetask-width)
571 ;; No inlinetask: Remove global margin from text width.
572 (- (plist-get info :ascii-text-width)
573 (plist-get info :ascii-global-margin)
574 (let ((parent (org-export-get-parent-headline element)))
575 ;; Inner margin doesn't apply to text before first
576 ;; headline.
577 (if (not parent) 0
578 (let ((low-level-rank
579 (org-export-low-level-p parent info)))
580 ;; Inner margin doesn't apply to contents of
581 ;; low level headlines, since they've got their
582 ;; own indentation mechanism.
583 (if low-level-rank (* low-level-rank 2)
584 (plist-get info :ascii-inner-margin)))))))))
585 (- total-width
586 ;; Each `quote-block' and `verse-block' above narrows text
587 ;; width by twice the standard margin size.
588 (+ (* (cl-count-if (lambda (parent)
589 (memq (org-element-type parent)
590 '(quote-block verse-block)))
591 genealogy)
593 (plist-get info :ascii-quote-margin))
594 ;; Apply list margin once per "top-level" plain-list
595 ;; containing current line
596 (* (cl-count-if
597 (lambda (e)
598 (and (eq (org-element-type e) 'plain-list)
599 (not (eq (org-element-type (org-export-get-parent e))
600 'item))))
601 genealogy)
602 (plist-get info :ascii-list-margin))
603 ;; Text width within a plain-list is restricted by
604 ;; indentation of current item. If that's the case,
605 ;; compute it with the help of `:structure' property from
606 ;; parent item, if any.
607 (let ((item
608 (if (eq (org-element-type element) 'item) element
609 (cl-find-if (lambda (parent)
610 (eq (org-element-type parent) 'item))
611 genealogy))))
612 (if (not item) 0
613 ;; Compute indentation offset of the current item,
614 ;; that is the sum of the difference between its
615 ;; indentation and the indentation of the top item in
616 ;; the list and current item bullet's length. Also
617 ;; remove checkbox length, and tag length (for
618 ;; description lists) or bullet length.
619 (let ((struct (org-element-property :structure item))
620 (beg-item (org-element-property :begin item)))
621 (+ (- (org-list-get-ind beg-item struct)
622 (org-list-get-ind
623 (org-list-get-top-point struct) struct))
624 (string-width (or (org-ascii--checkbox item info)
625 ""))
626 (string-width
627 (let ((tag (org-element-property :tag item)))
628 (if tag (org-export-data tag info)
629 (org-element-property :bullet item))))))))))))))
631 (defun org-ascii--current-justification (element)
632 "Return expected justification for ELEMENT's contents.
633 Return value is a symbol among `left', `center', `right' and
634 `full'."
635 (let (justification)
636 (while (and (not justification)
637 (setq element (org-element-property :parent element)))
638 (pcase (org-element-type element)
639 (`center-block (setq justification 'center))
640 (`special-block
641 (let ((name (org-element-property :type element)))
642 (cond ((string= name "JUSTIFYRIGHT") (setq justification 'right))
643 ((string= name "JUSTIFYLEFT") (setq justification 'left)))))))
644 (or justification 'left)))
646 (defun org-ascii--build-title
647 (element info text-width &optional underline notags toc)
648 "Format ELEMENT title and return it.
650 ELEMENT is either an `headline' or `inlinetask' element. INFO is
651 a plist used as a communication channel. TEXT-WIDTH is an
652 integer representing the maximum length of a line.
654 When optional argument UNDERLINE is non-nil, underline title,
655 without the tags, according to `org-ascii-underline'
656 specifications.
658 If optional argument NOTAGS is non-nil, no tags will be added to
659 the title.
661 When optional argument TOC is non-nil, use optional title if
662 possible. It doesn't apply to `inlinetask' elements."
663 (let* ((headlinep (eq (org-element-type element) 'headline))
664 (numbers
665 ;; Numbering is specific to headlines.
666 (and headlinep (org-export-numbered-headline-p element info)
667 ;; All tests passed: build numbering string.
668 (concat
669 (mapconcat
670 'number-to-string
671 (org-export-get-headline-number element info) ".")
672 " ")))
673 (text
674 (org-trim
675 (org-export-data
676 (if (and toc headlinep) (org-export-get-alt-title element info)
677 (org-element-property :title element))
678 info)))
679 (todo
680 (and (plist-get info :with-todo-keywords)
681 (let ((todo (org-element-property :todo-keyword element)))
682 (and todo (concat (org-export-data todo info) " ")))))
683 (tags (and (not notags)
684 (plist-get info :with-tags)
685 (let ((tag-list (org-export-get-tags element info)))
686 (and tag-list
687 (format ":%s:"
688 (mapconcat 'identity tag-list ":"))))))
689 (priority
690 (and (plist-get info :with-priority)
691 (let ((char (org-element-property :priority element)))
692 (and char (format "(#%c) " char)))))
693 (first-part (concat numbers todo priority text)))
694 (concat
695 first-part
696 ;; Align tags, if any.
697 (when tags
698 (format
699 (format " %%%ds"
700 (max (- text-width (1+ (string-width first-part)))
701 (string-width tags)))
702 tags))
703 ;; Maybe underline text, if ELEMENT type is `headline' and an
704 ;; underline character has been defined.
705 (when (and underline headlinep)
706 (let ((under-char
707 (nth (1- (org-export-get-relative-level element info))
708 (cdr (assq (plist-get info :ascii-charset)
709 (plist-get info :ascii-underline))))))
710 (and under-char
711 (concat "\n"
712 (make-string (/ (string-width first-part)
713 (char-width under-char))
714 under-char))))))))
716 (defun org-ascii--has-caption-p (element _info)
717 "Non-nil when ELEMENT has a caption affiliated keyword.
718 INFO is a plist used as a communication channel. This function
719 is meant to be used as a predicate for `org-export-get-ordinal'."
720 (org-element-property :caption element))
722 (defun org-ascii--build-caption (element info)
723 "Return caption string for ELEMENT, if applicable.
725 INFO is a plist used as a communication channel.
727 The caption string contains the sequence number of ELEMENT along
728 with its real caption. Return nil when ELEMENT has no affiliated
729 caption keyword."
730 (let ((caption (org-export-get-caption element)))
731 (when caption
732 ;; Get sequence number of current src-block among every
733 ;; src-block with a caption.
734 (let ((reference
735 (org-export-get-ordinal
736 element info nil 'org-ascii--has-caption-p))
737 (title-fmt (org-ascii--translate
738 (pcase (org-element-type element)
739 (`table "Table %d:")
740 (`src-block "Listing %d:"))
741 info)))
742 (org-ascii--fill-string
743 (concat (format title-fmt reference)
745 (org-export-data caption info))
746 (org-ascii--current-text-width element info) info)))))
748 (defun org-ascii--build-toc (info &optional n keyword local)
749 "Return a table of contents.
751 INFO is a plist used as a communication channel.
753 Optional argument N, when non-nil, is an integer specifying the
754 depth of the table.
756 Optional argument KEYWORD specifies the TOC keyword, if any, from
757 which the table of contents generation has been initiated.
759 When optional argument LOCAL is non-nil, build a table of
760 contents according to the current headline."
761 (concat
762 (unless local
763 (let ((title (org-ascii--translate "Table of Contents" info)))
764 (concat title "\n"
765 (make-string
766 (string-width title)
767 (if (eq (plist-get info :ascii-charset) 'utf-8) ?─ ?_))
768 "\n\n")))
769 (let ((text-width
770 (if keyword (org-ascii--current-text-width keyword info)
771 (- (plist-get info :ascii-text-width)
772 (plist-get info :ascii-global-margin)))))
773 (mapconcat
774 (lambda (headline)
775 (let* ((level (org-export-get-relative-level headline info))
776 (indent (* (1- level) 3)))
777 (concat
778 (unless (zerop indent) (concat (make-string (1- indent) ?.) " "))
779 (org-ascii--build-title
780 headline info (- text-width indent) nil
781 (or (not (plist-get info :with-tags))
782 (eq (plist-get info :with-tags) 'not-in-toc))
783 'toc))))
784 (org-export-collect-headlines info n (and local keyword)) "\n"))))
786 (defun org-ascii--list-listings (keyword info)
787 "Return a list of listings.
789 KEYWORD is the keyword that initiated the list of listings
790 generation. INFO is a plist used as a communication channel."
791 (let ((title (org-ascii--translate "List of Listings" info)))
792 (concat
793 title "\n"
794 (make-string (string-width title)
795 (if (eq (plist-get info :ascii-charset) 'utf-8) ?─ ?_))
796 "\n\n"
797 (let ((text-width
798 (if keyword (org-ascii--current-text-width keyword info)
799 (- (plist-get info :ascii-text-width)
800 (plist-get info :ascii-global-margin))))
801 ;; Use a counter instead of retrieving ordinal of each
802 ;; src-block.
803 (count 0))
804 (mapconcat
805 (lambda (src-block)
806 ;; Store initial text so its length can be computed. This is
807 ;; used to properly align caption right to it in case of
808 ;; filling (like contents of a description list item).
809 (let* ((initial-text
810 (format (org-ascii--translate "Listing %d:" info)
811 (cl-incf count)))
812 (initial-width (string-width initial-text)))
813 (concat
814 initial-text " "
815 (org-trim
816 (org-ascii--indent-string
817 (org-ascii--fill-string
818 ;; Use short name in priority, if available.
819 (let ((caption (or (org-export-get-caption src-block t)
820 (org-export-get-caption src-block))))
821 (org-export-data caption info))
822 (- text-width initial-width) info)
823 initial-width)))))
824 (org-export-collect-listings info) "\n")))))
826 (defun org-ascii--list-tables (keyword info)
827 "Return a list of tables.
829 KEYWORD is the keyword that initiated the list of tables
830 generation. INFO is a plist used as a communication channel."
831 (let ((title (org-ascii--translate "List of Tables" info)))
832 (concat
833 title "\n"
834 (make-string (string-width title)
835 (if (eq (plist-get info :ascii-charset) 'utf-8) ?─ ?_))
836 "\n\n"
837 (let ((text-width
838 (if keyword (org-ascii--current-text-width keyword info)
839 (- (plist-get info :ascii-text-width)
840 (plist-get info :ascii-global-margin))))
841 ;; Use a counter instead of retrieving ordinal of each
842 ;; src-block.
843 (count 0))
844 (mapconcat
845 (lambda (table)
846 ;; Store initial text so its length can be computed. This is
847 ;; used to properly align caption right to it in case of
848 ;; filling (like contents of a description list item).
849 (let* ((initial-text
850 (format (org-ascii--translate "Table %d:" info)
851 (cl-incf count)))
852 (initial-width (string-width initial-text)))
853 (concat
854 initial-text " "
855 (org-trim
856 (org-ascii--indent-string
857 (org-ascii--fill-string
858 ;; Use short name in priority, if available.
859 (let ((caption (or (org-export-get-caption table t)
860 (org-export-get-caption table))))
861 (org-export-data caption info))
862 (- text-width initial-width) info)
863 initial-width)))))
864 (org-export-collect-tables info) "\n")))))
866 (defun org-ascii--unique-links (element info)
867 "Return a list of unique link references in ELEMENT.
868 ELEMENT is either a headline element or a section element. INFO
869 is a plist used as a communication channel."
870 (let* (seen
871 (unique-link-p
872 ;; Return LINK if it wasn't referenced so far, or nil.
873 ;; Update SEEN links along the way.
874 (lambda (link)
875 (let ((footprint
876 ;; Normalize description in footprints.
877 (cons (org-element-property :raw-link link)
878 (let ((contents (org-element-contents link)))
879 (and contents
880 (replace-regexp-in-string
881 "[ \r\t\n]+" " "
882 (org-trim
883 (org-element-interpret-data contents))))))))
884 ;; Ignore LINK if it hasn't been translated already. It
885 ;; can happen if it is located in an affiliated keyword
886 ;; that was ignored.
887 (when (and (org-string-nw-p
888 (gethash link (plist-get info :exported-data)))
889 (not (member footprint seen)))
890 (push footprint seen) link)))))
891 (org-element-map (if (eq (org-element-type element) 'section)
892 element
893 ;; In a headline, only retrieve links in title
894 ;; and relative section, not in children.
895 (list (org-element-property :title element)
896 (car (org-element-contents element))))
897 'link unique-link-p info nil 'headline t)))
899 (defun org-ascii--describe-datum (datum info)
900 "Describe DATUM object or element.
901 If DATUM is a string, consider it to be a file name, per
902 `org-export-resolve-id-link'. INFO is the communication channel,
903 as a plist."
904 (pcase (org-element-type datum)
905 (`plain-text (format "See file %s" datum)) ;External file
906 (`headline
907 (format (org-ascii--translate "See section %s" info)
908 (if (org-export-numbered-headline-p datum info)
909 (mapconcat #'number-to-string
910 (org-export-get-headline-number datum info)
911 ".")
912 (org-export-data (org-element-property :title datum) info))))
914 (let ((number (org-export-get-ordinal
915 datum info nil #'org-ascii--has-caption-p))
916 ;; If destination is a target, make sure we can name the
917 ;; container it refers to.
918 (enumerable
919 (org-element-lineage datum '(headline paragrah src-block table) t)))
920 (pcase (org-element-type enumerable)
921 (`headline
922 (format (org-ascii--translate "See section %s" info)
923 (if (org-export-numbered-headline-p enumerable info)
924 (mapconcat #'number-to-string number ".")
925 (org-export-data
926 (org-element-property :title enumerable) info))))
927 ((guard (not number))
928 (org-ascii--translate "Unknown reference" info))
929 (`paragraph
930 (format (org-ascii--translate "See figure %s" info) number))
931 (`src-block
932 (format (org-ascii--translate "See listing %s" info) number))
933 (`table
934 (format (org-ascii--translate "See table %s" info) number))
935 (_ (org-ascii--translate "Unknown reference" info)))))))
937 (defun org-ascii--describe-links (links width info)
938 "Return a string describing a list of links.
939 LINKS is a list of link type objects, as returned by
940 `org-ascii--unique-links'. WIDTH is the text width allowed for
941 the output string. INFO is a plist used as a communication
942 channel."
943 (mapconcat
944 (lambda (link)
945 (let* ((type (org-element-property :type link))
946 (description (org-element-contents link))
947 (anchor (org-export-data
948 (or description (org-element-property :raw-link link))
949 info)))
950 (cond
951 ((member type '("coderef" "radio")) nil)
952 ((member type '("custom-id" "fuzzy" "id"))
953 ;; Only links with a description need an entry. Other are
954 ;; already handled in `org-ascii-link'.
955 (when description
956 (let ((dest (if (equal type "fuzzy")
957 (org-export-resolve-fuzzy-link link info)
958 (org-export-resolve-id-link link info))))
959 (concat
960 (org-ascii--fill-string
961 (format "[%s] %s" anchor (org-ascii--describe-datum dest info))
962 width info)
963 "\n\n"))))
964 ;; Do not add a link that cannot be resolved and doesn't have
965 ;; any description: destination is already visible in the
966 ;; paragraph.
967 ((not (org-element-contents link)) nil)
968 ;; Do not add a link already handled by custom export
969 ;; functions.
970 ((org-export-custom-protocol-maybe link anchor 'ascii) nil)
972 (concat
973 (org-ascii--fill-string
974 (format "[%s] %s" anchor (org-element-property :raw-link link))
975 width info)
976 "\n\n")))))
977 links ""))
979 (defun org-ascii--checkbox (item info)
980 "Return checkbox string for ITEM or nil.
981 INFO is a plist used as a communication channel."
982 (let ((utf8p (eq (plist-get info :ascii-charset) 'utf-8)))
983 (pcase (org-element-property :checkbox item)
984 (`on (if utf8p "☑ " "[X] "))
985 (`off (if utf8p "☐ " "[ ] "))
986 (`trans (if utf8p "☒ " "[-] ")))))
990 ;;; Template
992 (defun org-ascii-template--document-title (info)
993 "Return document title, as a string.
994 INFO is a plist used as a communication channel."
995 (let* ((text-width (plist-get info :ascii-text-width))
996 ;; Links in the title will not be resolved later, so we make
997 ;; sure their path is located right after them.
998 (info (org-combine-plists info '(:ascii-links-to-notes nil)))
999 (with-title (plist-get info :with-title))
1000 (title (org-export-data
1001 (when with-title (plist-get info :title)) info))
1002 (subtitle (org-export-data
1003 (when with-title (plist-get info :subtitle)) info))
1004 (author (and (plist-get info :with-author)
1005 (let ((auth (plist-get info :author)))
1006 (and auth (org-export-data auth info)))))
1007 (email (and (plist-get info :with-email)
1008 (org-export-data (plist-get info :email) info)))
1009 (date (and (plist-get info :with-date)
1010 (org-export-data (org-export-get-date info) info))))
1011 ;; There are two types of title blocks depending on the presence
1012 ;; of a title to display.
1013 (if (string= title "")
1014 ;; Title block without a title. DATE is positioned at the top
1015 ;; right of the document, AUTHOR to the top left and EMAIL
1016 ;; just below.
1017 (cond
1018 ((and (org-string-nw-p date) (org-string-nw-p author))
1019 (concat
1020 author
1021 (make-string (- text-width (string-width date) (string-width author))
1022 ?\s)
1023 date
1024 (when (org-string-nw-p email) (concat "\n" email))
1025 "\n\n\n"))
1026 ((and (org-string-nw-p date) (org-string-nw-p email))
1027 (concat
1028 email
1029 (make-string (- text-width (string-width date) (string-width email))
1030 ?\s)
1031 date "\n\n\n"))
1032 ((org-string-nw-p date)
1033 (concat
1034 (org-ascii--justify-lines date text-width 'right)
1035 "\n\n\n"))
1036 ((and (org-string-nw-p author) (org-string-nw-p email))
1037 (concat author "\n" email "\n\n\n"))
1038 ((org-string-nw-p author) (concat author "\n\n\n"))
1039 ((org-string-nw-p email) (concat email "\n\n\n")))
1040 ;; Title block with a title. Document's TITLE, along with the
1041 ;; AUTHOR and its EMAIL are both overlined and an underlined,
1042 ;; centered. Date is just below, also centered.
1043 (let* ((utf8p (eq (plist-get info :ascii-charset) 'utf-8))
1044 ;; Format TITLE. It may be filled if it is too wide,
1045 ;; that is wider than the two thirds of the total width.
1046 (title-len (min (apply #'max
1047 (mapcar #'length
1048 (org-split-string
1049 (concat title "\n" subtitle) "\n")))
1050 (/ (* 2 text-width) 3)))
1051 (formatted-title (org-ascii--fill-string title title-len info))
1052 (formatted-subtitle (when (org-string-nw-p subtitle)
1053 (org-ascii--fill-string subtitle title-len info)))
1054 (line
1055 (make-string
1056 (min (+ (max title-len
1057 (string-width (or author ""))
1058 (string-width (or email "")))
1060 text-width) (if utf8p ?━ ?_))))
1061 (org-ascii--justify-lines
1062 (concat line "\n"
1063 (unless utf8p "\n")
1064 (upcase formatted-title)
1065 (and formatted-subtitle (concat "\n" formatted-subtitle))
1066 (cond
1067 ((and (org-string-nw-p author) (org-string-nw-p email))
1068 (concat "\n\n" author "\n" email))
1069 ((org-string-nw-p author) (concat "\n\n" author))
1070 ((org-string-nw-p email) (concat "\n\n" email)))
1071 "\n" line
1072 (when (org-string-nw-p date) (concat "\n\n\n" date))
1073 "\n\n\n") text-width 'center)))))
1075 (defun org-ascii-inner-template (contents info)
1076 "Return complete document string after ASCII conversion.
1077 CONTENTS is the transcoded contents string. INFO is a plist
1078 holding export options."
1079 (org-element-normalize-string
1080 (let ((global-margin (plist-get info :ascii-global-margin)))
1081 (org-ascii--indent-string
1082 (concat
1083 ;; 1. Document's body.
1084 contents
1085 ;; 2. Footnote definitions.
1086 (let ((definitions (org-export-collect-footnote-definitions info))
1087 ;; Insert full links right inside the footnote definition
1088 ;; as they have no chance to be inserted later.
1089 (info (org-combine-plists info '(:ascii-links-to-notes nil))))
1090 (when definitions
1091 (concat
1092 "\n\n\n"
1093 (let ((title (org-ascii--translate "Footnotes" info)))
1094 (concat
1095 title "\n"
1096 (make-string
1097 (string-width title)
1098 (if (eq (plist-get info :ascii-charset) 'utf-8) ?─ ?_))))
1099 "\n\n"
1100 (let ((text-width (- (plist-get info :ascii-text-width)
1101 global-margin)))
1102 (mapconcat
1103 (lambda (ref)
1104 (let ((id (format "[%s] " (car ref))))
1105 ;; Distinguish between inline definitions and
1106 ;; full-fledged definitions.
1107 (org-trim
1108 (let ((def (nth 2 ref)))
1109 (if (org-element-map def org-element-all-elements
1110 #'identity info 'first-match)
1111 ;; Full-fledged definition: footnote ID is
1112 ;; inserted inside the first parsed
1113 ;; paragraph (FIRST), if any, to be sure
1114 ;; filling will take it into consideration.
1115 (let ((first (car (org-element-contents def))))
1116 (if (not (eq (org-element-type first) 'paragraph))
1117 (concat id "\n" (org-export-data def info))
1118 (push id (nthcdr 2 first))
1119 (org-export-data def info)))
1120 ;; Fill paragraph once footnote ID is inserted
1121 ;; in order to have a correct length for first
1122 ;; line.
1123 (org-ascii--fill-string
1124 (concat id (org-export-data def info))
1125 text-width info))))))
1126 definitions "\n\n"))))))
1127 global-margin))))
1129 (defun org-ascii-template (contents info)
1130 "Return complete document string after ASCII conversion.
1131 CONTENTS is the transcoded contents string. INFO is a plist
1132 holding export options."
1133 (let ((global-margin (plist-get info :ascii-global-margin)))
1134 (concat
1135 ;; Build title block.
1136 (org-ascii--indent-string
1137 (concat (org-ascii-template--document-title info)
1138 ;; 2. Table of contents.
1139 (let ((depth (plist-get info :with-toc)))
1140 (when depth
1141 (concat
1142 (org-ascii--build-toc info (and (wholenump depth) depth))
1143 "\n\n\n"))))
1144 global-margin)
1145 ;; Document's body.
1146 contents
1147 ;; Creator. Justify it to the bottom right.
1148 (and (plist-get info :with-creator)
1149 (org-ascii--indent-string
1150 (let ((text-width
1151 (- (plist-get info :ascii-text-width) global-margin)))
1152 (concat
1153 "\n\n\n"
1154 (org-ascii--fill-string
1155 (plist-get info :creator) text-width info 'right)))
1156 global-margin)))))
1158 (defun org-ascii--translate (s info)
1159 "Translate string S according to specified language and charset.
1160 INFO is a plist used as a communication channel."
1161 (let ((charset (intern (format ":%s" (plist-get info :ascii-charset)))))
1162 (org-export-translate s charset info)))
1166 ;;; Transcode Functions
1168 ;;;; Bold
1170 (defun org-ascii-bold (_bold contents _info)
1171 "Transcode BOLD from Org to ASCII.
1172 CONTENTS is the text with bold markup. INFO is a plist holding
1173 contextual information."
1174 (format "*%s*" contents))
1177 ;;;; Center Block
1179 (defun org-ascii-center-block (_center-block contents _info)
1180 "Transcode a CENTER-BLOCK element from Org to ASCII.
1181 CONTENTS holds the contents of the block. INFO is a plist
1182 holding contextual information."
1183 ;; Center has already been taken care of at a lower level, so
1184 ;; there's nothing left to do.
1185 contents)
1188 ;;;; Clock
1190 (defun org-ascii-clock (clock _contents info)
1191 "Transcode a CLOCK object from Org to ASCII.
1192 CONTENTS is nil. INFO is a plist holding contextual
1193 information."
1194 (org-ascii--justify-element
1195 (concat org-clock-string " "
1196 (org-timestamp-translate (org-element-property :value clock))
1197 (let ((time (org-element-property :duration clock)))
1198 (and time
1199 (concat " => "
1200 (apply 'format
1201 "%2s:%02s"
1202 (org-split-string time ":"))))))
1203 clock info))
1206 ;;;; Code
1208 (defun org-ascii-code (code _contents info)
1209 "Return a CODE object from Org to ASCII.
1210 CONTENTS is nil. INFO is a plist holding contextual
1211 information."
1212 (format (plist-get info :ascii-verbatim-format)
1213 (org-element-property :value code)))
1216 ;;;; Drawer
1218 (defun org-ascii-drawer (drawer contents info)
1219 "Transcode a DRAWER element from Org to ASCII.
1220 CONTENTS holds the contents of the block. INFO is a plist
1221 holding contextual information."
1222 (let ((name (org-element-property :drawer-name drawer))
1223 (width (org-ascii--current-text-width drawer info)))
1224 (funcall (plist-get info :ascii-format-drawer-function)
1225 name contents width)))
1228 ;;;; Dynamic Block
1230 (defun org-ascii-dynamic-block (_dynamic-block contents _info)
1231 "Transcode a DYNAMIC-BLOCK element from Org to ASCII.
1232 CONTENTS holds the contents of the block. INFO is a plist
1233 holding contextual information."
1234 contents)
1237 ;;;; Entity
1239 (defun org-ascii-entity (entity _contents info)
1240 "Transcode an ENTITY object from Org to ASCII.
1241 CONTENTS are the definition itself. INFO is a plist holding
1242 contextual information."
1243 (org-element-property
1244 (intern (concat ":" (symbol-name (plist-get info :ascii-charset))))
1245 entity))
1248 ;;;; Example Block
1250 (defun org-ascii-example-block (example-block _contents info)
1251 "Transcode a EXAMPLE-BLOCK element from Org to ASCII.
1252 CONTENTS is nil. INFO is a plist holding contextual information."
1253 (org-ascii--justify-element
1254 (org-ascii--box-string
1255 (org-export-format-code-default example-block info) info)
1256 example-block info))
1259 ;;;; Export Snippet
1261 (defun org-ascii-export-snippet (export-snippet _contents _info)
1262 "Transcode a EXPORT-SNIPPET object from Org to ASCII.
1263 CONTENTS is nil. INFO is a plist holding contextual information."
1264 (when (eq (org-export-snippet-backend export-snippet) 'ascii)
1265 (org-element-property :value export-snippet)))
1268 ;;;; Export Block
1270 (defun org-ascii-export-block (export-block _contents info)
1271 "Transcode a EXPORT-BLOCK element from Org to ASCII.
1272 CONTENTS is nil. INFO is a plist holding contextual information."
1273 (when (string= (org-element-property :type export-block) "ASCII")
1274 (org-ascii--justify-element
1275 (org-element-property :value export-block) export-block info)))
1278 ;;;; Fixed Width
1280 (defun org-ascii-fixed-width (fixed-width _contents info)
1281 "Transcode a FIXED-WIDTH element from Org to ASCII.
1282 CONTENTS is nil. INFO is a plist holding contextual information."
1283 (org-ascii--justify-element
1284 (org-ascii--box-string
1285 (org-remove-indentation
1286 (org-element-property :value fixed-width)) info)
1287 fixed-width info))
1290 ;;;; Footnote Definition
1292 ;; Footnote Definitions are ignored. They are compiled at the end of
1293 ;; the document, by `org-ascii-inner-template'.
1296 ;;;; Footnote Reference
1298 (defun org-ascii-footnote-reference (footnote-reference _contents info)
1299 "Transcode a FOOTNOTE-REFERENCE element from Org to ASCII.
1300 CONTENTS is nil. INFO is a plist holding contextual information."
1301 (format "[%s]" (org-export-get-footnote-number footnote-reference info)))
1304 ;;;; Headline
1306 (defun org-ascii-headline (headline contents info)
1307 "Transcode a HEADLINE element from Org to ASCII.
1308 CONTENTS holds the contents of the headline. INFO is a plist
1309 holding contextual information."
1310 ;; Don't export footnote section, which will be handled at the end
1311 ;; of the template.
1312 (unless (org-element-property :footnote-section-p headline)
1313 (let* ((low-level (org-export-low-level-p headline info))
1314 (width (org-ascii--current-text-width headline info))
1315 ;; Export title early so that any link in it can be
1316 ;; exported and seen in `org-ascii--unique-links'.
1317 (title (org-ascii--build-title headline info width (not low-level)))
1318 ;; Blank lines between headline and its contents.
1319 ;; `org-ascii-headline-spacing', when set, overwrites
1320 ;; original buffer's spacing.
1321 (pre-blanks
1322 (make-string (or (car (plist-get info :ascii-headline-spacing))
1323 (org-element-property :pre-blank headline)
1325 ?\n))
1326 (links (and (plist-get info :ascii-links-to-notes)
1327 (org-ascii--describe-links
1328 (org-ascii--unique-links headline info) width info)))
1329 ;; Re-build contents, inserting section links at the right
1330 ;; place. The cost is low since build results are cached.
1331 (body
1332 (if (not (org-string-nw-p links)) contents
1333 (let* ((contents (org-element-contents headline))
1334 (section (let ((first (car contents)))
1335 (and (eq (org-element-type first) 'section)
1336 first))))
1337 (concat (and section
1338 (concat (org-element-normalize-string
1339 (org-export-data section info))
1340 "\n\n"))
1341 links
1342 (mapconcat (lambda (e) (org-export-data e info))
1343 (if section (cdr contents) contents)
1344 ""))))))
1345 ;; Deep subtree: export it as a list item.
1346 (if low-level
1347 (let* ((bullets (cdr (assq (plist-get info :ascii-charset)
1348 (plist-get info :ascii-bullets))))
1349 (bullet
1350 (format "%c "
1351 (nth (mod (1- low-level) (length bullets)) bullets))))
1352 (concat bullet title "\n" pre-blanks
1353 ;; Contents, indented by length of bullet.
1354 (org-ascii--indent-string body (length bullet))))
1355 ;; Else: Standard headline.
1356 (concat title "\n" pre-blanks body)))))
1359 ;;;; Horizontal Rule
1361 (defun org-ascii-horizontal-rule (horizontal-rule _contents info)
1362 "Transcode an HORIZONTAL-RULE object from Org to ASCII.
1363 CONTENTS is nil. INFO is a plist holding contextual
1364 information."
1365 (let ((text-width (org-ascii--current-text-width horizontal-rule info))
1366 (spec-width
1367 (org-export-read-attribute :attr_ascii horizontal-rule :width)))
1368 (org-ascii--justify-lines
1369 (make-string (if (and spec-width (string-match "^[0-9]+$" spec-width))
1370 (string-to-number spec-width)
1371 text-width)
1372 (if (eq (plist-get info :ascii-charset) 'utf-8) ?― ?-))
1373 text-width 'center)))
1376 ;;;; Inline Src Block
1378 (defun org-ascii-inline-src-block (inline-src-block _contents info)
1379 "Transcode an INLINE-SRC-BLOCK element from Org to ASCII.
1380 CONTENTS holds the contents of the item. INFO is a plist holding
1381 contextual information."
1382 (format (plist-get info :ascii-verbatim-format)
1383 (org-element-property :value inline-src-block)))
1386 ;;;; Inlinetask
1388 (defun org-ascii-format-inlinetask-default
1389 (_todo _type _priority _name _tags contents width inlinetask info)
1390 "Format an inline task element for ASCII export.
1391 See `org-ascii-format-inlinetask-function' for a description
1392 of the parameters."
1393 (let* ((utf8p (eq (plist-get info :ascii-charset) 'utf-8))
1394 (width (or width (plist-get info :ascii-inlinetask-width))))
1395 (org-ascii--indent-string
1396 (concat
1397 ;; Top line, with an additional blank line if not in UTF-8.
1398 (make-string width (if utf8p ?━ ?_)) "\n"
1399 (unless utf8p (concat (make-string width ? ) "\n"))
1400 ;; Add title. Fill it if wider than inlinetask.
1401 (let ((title (org-ascii--build-title inlinetask info width)))
1402 (if (<= (string-width title) width) title
1403 (org-ascii--fill-string title width info)))
1404 "\n"
1405 ;; If CONTENTS is not empty, insert it along with
1406 ;; a separator.
1407 (when (org-string-nw-p contents)
1408 (concat (make-string width (if utf8p ?─ ?-)) "\n" contents))
1409 ;; Bottom line.
1410 (make-string width (if utf8p ?━ ?_)))
1411 ;; Flush the inlinetask to the right.
1412 (- (plist-get info :ascii-text-width) (plist-get info :ascii-global-margin)
1413 (if (not (org-export-get-parent-headline inlinetask)) 0
1414 (plist-get info :ascii-inner-margin))
1415 (org-ascii--current-text-width inlinetask info)))))
1417 (defun org-ascii-inlinetask (inlinetask contents info)
1418 "Transcode an INLINETASK element from Org to ASCII.
1419 CONTENTS holds the contents of the block. INFO is a plist
1420 holding contextual information."
1421 (let ((width (org-ascii--current-text-width inlinetask info)))
1422 (funcall (plist-get info :ascii-format-inlinetask-function)
1423 ;; todo.
1424 (and (plist-get info :with-todo-keywords)
1425 (let ((todo (org-element-property
1426 :todo-keyword inlinetask)))
1427 (and todo (org-export-data todo info))))
1428 ;; todo-type
1429 (org-element-property :todo-type inlinetask)
1430 ;; priority
1431 (and (plist-get info :with-priority)
1432 (org-element-property :priority inlinetask))
1433 ;; title
1434 (org-export-data (org-element-property :title inlinetask) info)
1435 ;; tags
1436 (and (plist-get info :with-tags)
1437 (org-element-property :tags inlinetask))
1438 ;; contents and width
1439 contents width inlinetask info)))
1442 ;;;; Italic
1444 (defun org-ascii-italic (_italic contents _info)
1445 "Transcode italic from Org to ASCII.
1446 CONTENTS is the text with italic markup. INFO is a plist holding
1447 contextual information."
1448 (format "/%s/" contents))
1451 ;;;; Item
1453 (defun org-ascii-item (item contents info)
1454 "Transcode an ITEM element from Org to ASCII.
1455 CONTENTS holds the contents of the item. INFO is a plist holding
1456 contextual information."
1457 (let* ((utf8p (eq (plist-get info :ascii-charset) 'utf-8))
1458 (checkbox (org-ascii--checkbox item info))
1459 (list-type (org-element-property :type (org-export-get-parent item)))
1460 (bullet
1461 ;; First parent of ITEM is always the plain-list. Get
1462 ;; `:type' property from it.
1463 (org-list-bullet-string
1464 (pcase list-type
1465 (`descriptive
1466 (concat checkbox
1467 (org-export-data (org-element-property :tag item) info)
1468 ": "))
1469 (`ordered
1470 ;; Return correct number for ITEM, paying attention to
1471 ;; counters.
1472 (let* ((struct (org-element-property :structure item))
1473 (bul (org-element-property :bullet item))
1474 (num (number-to-string
1475 (car (last (org-list-get-item-number
1476 (org-element-property :begin item)
1477 struct
1478 (org-list-prevs-alist struct)
1479 (org-list-parents-alist struct)))))))
1480 (replace-regexp-in-string "[0-9]+" num bul)))
1481 (_ (let ((bul (org-element-property :bullet item)))
1482 ;; Change bullets into more visible form if UTF-8 is active.
1483 (if (not utf8p) bul
1484 (replace-regexp-in-string
1485 "-" "•"
1486 (replace-regexp-in-string
1487 "+" "⁃"
1488 (replace-regexp-in-string "*" "‣" bul))))))))))
1489 (concat
1490 bullet
1491 (unless (eq list-type 'descriptive) checkbox)
1492 ;; Contents: Pay attention to indentation. Note: check-boxes are
1493 ;; already taken care of at the paragraph level so they don't
1494 ;; interfere with indentation.
1495 (let ((contents (org-ascii--indent-string contents (string-width bullet))))
1496 (if (eq (org-element-type (car (org-element-contents item))) 'paragraph)
1497 (org-trim contents)
1498 (concat "\n" contents))))))
1501 ;;;; Keyword
1503 (defun org-ascii-keyword (keyword _contents info)
1504 "Transcode a KEYWORD element from Org to ASCII.
1505 CONTENTS is nil. INFO is a plist holding contextual
1506 information."
1507 (let ((key (org-element-property :key keyword))
1508 (value (org-element-property :value keyword)))
1509 (cond
1510 ((string= key "ASCII") (org-ascii--justify-element value keyword info))
1511 ((string= key "TOC")
1512 (org-ascii--justify-element
1513 (let ((case-fold-search t))
1514 (cond
1515 ((string-match-p "\\<headlines\\>" value)
1516 (let ((depth (and (string-match "\\<[0-9]+\\>" value)
1517 (string-to-number (match-string 0 value))))
1518 (localp (string-match-p "\\<local\\>" value)))
1519 (org-ascii--build-toc info depth keyword localp)))
1520 ((string-match-p "\\<tables\\>" value)
1521 (org-ascii--list-tables keyword info))
1522 ((string-match-p "\\<listings\\>" value)
1523 (org-ascii--list-listings keyword info))))
1524 keyword info)))))
1527 ;;;; Latex Environment
1529 (defun org-ascii-latex-environment (latex-environment _contents info)
1530 "Transcode a LATEX-ENVIRONMENT element from Org to ASCII.
1531 CONTENTS is nil. INFO is a plist holding contextual
1532 information."
1533 (when (plist-get info :with-latex)
1534 (org-ascii--justify-element
1535 (org-remove-indentation (org-element-property :value latex-environment))
1536 latex-environment info)))
1539 ;;;; Latex Fragment
1541 (defun org-ascii-latex-fragment (latex-fragment _contents info)
1542 "Transcode a LATEX-FRAGMENT object from Org to ASCII.
1543 CONTENTS is nil. INFO is a plist holding contextual
1544 information."
1545 (when (plist-get info :with-latex)
1546 (org-element-property :value latex-fragment)))
1549 ;;;; Line Break
1551 (defun org-ascii-line-break (_line-break _contents _info)
1552 "Transcode a LINE-BREAK object from Org to ASCII.
1553 CONTENTS is nil. INFO is a plist holding contextual
1554 information." hard-newline)
1557 ;;;; Link
1559 (defun org-ascii-link (link desc info)
1560 "Transcode a LINK object from Org to ASCII.
1562 DESC is the description part of the link, or the empty string.
1563 INFO is a plist holding contextual information."
1564 (let ((type (org-element-property :type link)))
1565 (cond
1566 ((org-export-custom-protocol-maybe link desc 'ascii))
1567 ((string= type "coderef")
1568 (let ((ref (org-element-property :path link)))
1569 (format (org-export-get-coderef-format ref desc)
1570 (org-export-resolve-coderef ref info))))
1571 ;; Do not apply a special syntax on radio links. Though, use
1572 ;; transcoded target's contents as output.
1573 ((string= type "radio") desc)
1574 ((member type '("custom-id" "fuzzy" "id"))
1575 (let ((destination (if (string= type "fuzzy")
1576 (org-export-resolve-fuzzy-link link info)
1577 (org-export-resolve-id-link link info))))
1578 (pcase (org-element-type destination)
1579 ((guard desc)
1580 (if (plist-get info :ascii-links-to-notes)
1581 (format "[%s]" desc)
1582 (concat desc
1583 (format " (%s)"
1584 (org-ascii--describe-datum destination info)))))
1585 ;; External file.
1586 (`plain-text destination)
1587 (`headline
1588 (if (org-export-numbered-headline-p destination info)
1589 (mapconcat #'number-to-string
1590 (org-export-get-headline-number destination info)
1591 ".")
1592 (org-export-data (org-element-property :title destination) info)))
1593 ;; Handle enumerable elements and targets within them.
1594 ((and (let number (org-export-get-ordinal
1595 destination info nil #'org-ascii--has-caption-p))
1596 (guard number))
1597 (if (atom number) (number-to-string number)
1598 (mapconcat #'number-to-string number ".")))
1599 ;; Don't know what to do. Signal it.
1600 (_ "???"))))
1602 (let ((raw-link (org-element-property :raw-link link)))
1603 (if (not (org-string-nw-p desc)) (format "[%s]" raw-link)
1604 (concat (format "[%s]" desc)
1605 (and (not (plist-get info :ascii-links-to-notes))
1606 (format " (%s)" raw-link)))))))))
1609 ;;;; Node Properties
1611 (defun org-ascii-node-property (node-property _contents _info)
1612 "Transcode a NODE-PROPERTY element from Org to ASCII.
1613 CONTENTS is nil. INFO is a plist holding contextual
1614 information."
1615 (format "%s:%s"
1616 (org-element-property :key node-property)
1617 (let ((value (org-element-property :value node-property)))
1618 (if value (concat " " value) ""))))
1621 ;;;; Paragraph
1623 (defun org-ascii-paragraph (paragraph contents info)
1624 "Transcode a PARAGRAPH element from Org to ASCII.
1625 CONTENTS is the contents of the paragraph, as a string. INFO is
1626 the plist used as a communication channel."
1627 (org-ascii--justify-element
1628 (let ((indented-line-width (plist-get info :ascii-indented-line-width)))
1629 (if (not (wholenump indented-line-width)) contents
1630 (concat
1631 ;; Do not indent first paragraph in a section.
1632 (unless (and (not (org-export-get-previous-element paragraph info))
1633 (eq (org-element-type (org-export-get-parent paragraph))
1634 'section))
1635 (make-string indented-line-width ?\s))
1636 (replace-regexp-in-string "\\`[ \t]+" "" contents))))
1637 paragraph info))
1640 ;;;; Plain List
1642 (defun org-ascii-plain-list (plain-list contents info)
1643 "Transcode a PLAIN-LIST element from Org to ASCII.
1644 CONTENTS is the contents of the list. INFO is a plist holding
1645 contextual information."
1646 (let ((margin (plist-get info :ascii-list-margin)))
1647 (if (or (< margin 1)
1648 (eq (org-element-type (org-export-get-parent plain-list)) 'item))
1649 contents
1650 (org-ascii--indent-string contents margin))))
1653 ;;;; Plain Text
1655 (defun org-ascii-plain-text (text info)
1656 "Transcode a TEXT string from Org to ASCII.
1657 INFO is a plist used as a communication channel."
1658 (let ((utf8p (eq (plist-get info :ascii-charset) 'utf-8)))
1659 (when (and utf8p (plist-get info :with-smart-quotes))
1660 (setq text (org-export-activate-smart-quotes text :utf-8 info)))
1661 (if (not (plist-get info :with-special-strings)) text
1662 (setq text (replace-regexp-in-string "\\\\-" "" text))
1663 (if (not utf8p) text
1664 ;; Usual replacements in utf-8 with proper option set.
1665 (replace-regexp-in-string
1666 "\\.\\.\\." "…"
1667 (replace-regexp-in-string
1668 "--" "–"
1669 (replace-regexp-in-string "---" "—" text)))))))
1672 ;;;; Planning
1674 (defun org-ascii-planning (planning _contents info)
1675 "Transcode a PLANNING element from Org to ASCII.
1676 CONTENTS is nil. INFO is a plist used as a communication
1677 channel."
1678 (org-ascii--justify-element
1679 (mapconcat
1680 #'identity
1681 (delq nil
1682 (list (let ((closed (org-element-property :closed planning)))
1683 (when closed
1684 (concat org-closed-string " "
1685 (org-timestamp-translate closed))))
1686 (let ((deadline (org-element-property :deadline planning)))
1687 (when deadline
1688 (concat org-deadline-string " "
1689 (org-timestamp-translate deadline))))
1690 (let ((scheduled (org-element-property :scheduled planning)))
1691 (when scheduled
1692 (concat org-scheduled-string " "
1693 (org-timestamp-translate scheduled))))))
1694 " ")
1695 planning info))
1698 ;;;; Property Drawer
1700 (defun org-ascii-property-drawer (property-drawer contents info)
1701 "Transcode a PROPERTY-DRAWER element from Org to ASCII.
1702 CONTENTS holds the contents of the drawer. INFO is a plist
1703 holding contextual information."
1704 (and (org-string-nw-p contents)
1705 (org-ascii--justify-element contents property-drawer info)))
1708 ;;;; Quote Block
1710 (defun org-ascii-quote-block (_quote-block contents info)
1711 "Transcode a QUOTE-BLOCK element from Org to ASCII.
1712 CONTENTS holds the contents of the block. INFO is a plist
1713 holding contextual information."
1714 (org-ascii--indent-string contents (plist-get info :ascii-quote-margin)))
1717 ;;;; Radio Target
1719 (defun org-ascii-radio-target (_radio-target contents _info)
1720 "Transcode a RADIO-TARGET object from Org to ASCII.
1721 CONTENTS is the contents of the target. INFO is a plist holding
1722 contextual information."
1723 contents)
1726 ;;;; Section
1728 (defun org-ascii-section (section contents info)
1729 "Transcode a SECTION element from Org to ASCII.
1730 CONTENTS is the contents of the section. INFO is a plist holding
1731 contextual information."
1732 (let ((links
1733 (and (plist-get info :ascii-links-to-notes)
1734 ;; Take care of links in first section of the document.
1735 (not (org-element-lineage section '(headline)))
1736 (org-ascii--describe-links
1737 (org-ascii--unique-links section info)
1738 (org-ascii--current-text-width section info)
1739 info))))
1740 (org-ascii--indent-string
1741 (if (not (org-string-nw-p links)) contents
1742 (concat (org-element-normalize-string contents) "\n\n" links))
1743 ;; Do not apply inner margin if parent headline is low level.
1744 (let ((headline (org-export-get-parent-headline section)))
1745 (if (or (not headline) (org-export-low-level-p headline info)) 0
1746 (plist-get info :ascii-inner-margin))))))
1749 ;;;; Special Block
1751 (defun org-ascii-special-block (_special-block contents _info)
1752 "Transcode a SPECIAL-BLOCK element from Org to ASCII.
1753 CONTENTS holds the contents of the block. INFO is a plist
1754 holding contextual information."
1755 ;; "JUSTIFYLEFT" and "JUSTFYRIGHT" have already been taken care of
1756 ;; at a lower level. There is no other special block type to
1757 ;; handle.
1758 contents)
1761 ;;;; Src Block
1763 (defun org-ascii-src-block (src-block _contents info)
1764 "Transcode a SRC-BLOCK element from Org to ASCII.
1765 CONTENTS holds the contents of the item. INFO is a plist holding
1766 contextual information."
1767 (let ((caption (org-ascii--build-caption src-block info))
1768 (caption-above-p (plist-get info :ascii-caption-above))
1769 (code (org-export-format-code-default src-block info)))
1770 (if (equal code "") ""
1771 (org-ascii--justify-element
1772 (concat
1773 (and caption caption-above-p (concat caption "\n"))
1774 (org-ascii--box-string code info)
1775 (and caption (not caption-above-p) (concat "\n" caption)))
1776 src-block info))))
1779 ;;;; Statistics Cookie
1781 (defun org-ascii-statistics-cookie (statistics-cookie _contents _info)
1782 "Transcode a STATISTICS-COOKIE object from Org to ASCII.
1783 CONTENTS is nil. INFO is a plist holding contextual information."
1784 (org-element-property :value statistics-cookie))
1787 ;;;; Subscript
1789 (defun org-ascii-subscript (subscript contents _info)
1790 "Transcode a SUBSCRIPT object from Org to ASCII.
1791 CONTENTS is the contents of the object. INFO is a plist holding
1792 contextual information."
1793 (if (org-element-property :use-brackets-p subscript)
1794 (format "_{%s}" contents)
1795 (format "_%s" contents)))
1798 ;;;; Superscript
1800 (defun org-ascii-superscript (superscript contents _info)
1801 "Transcode a SUPERSCRIPT object from Org to ASCII.
1802 CONTENTS is the contents of the object. INFO is a plist holding
1803 contextual information."
1804 (if (org-element-property :use-brackets-p superscript)
1805 (format "^{%s}" contents)
1806 (format "^%s" contents)))
1809 ;;;; Strike-through
1811 (defun org-ascii-strike-through (_strike-through contents _info)
1812 "Transcode STRIKE-THROUGH from Org to ASCII.
1813 CONTENTS is text with strike-through markup. INFO is a plist
1814 holding contextual information."
1815 (format "+%s+" contents))
1818 ;;;; Table
1820 (defun org-ascii-table (table contents info)
1821 "Transcode a TABLE element from Org to ASCII.
1822 CONTENTS is the contents of the table. INFO is a plist holding
1823 contextual information."
1824 (let ((caption (org-ascii--build-caption table info))
1825 (caption-above-p (plist-get info :ascii-caption-above)))
1826 (org-ascii--justify-element
1827 (concat
1828 ;; Possibly add a caption string above.
1829 (and caption caption-above-p (concat caption "\n"))
1830 ;; Insert table. Note: "table.el" tables are left unmodified.
1831 (cond ((eq (org-element-property :type table) 'org) contents)
1832 ((and (plist-get info :ascii-table-use-ascii-art)
1833 (eq (plist-get info :ascii-charset) 'utf-8)
1834 (require 'ascii-art-to-unicode nil t))
1835 (with-temp-buffer
1836 (insert (org-remove-indentation
1837 (org-element-property :value table)))
1838 (goto-char (point-min))
1839 (aa2u)
1840 (goto-char (point-max))
1841 (skip-chars-backward " \r\t\n")
1842 (buffer-substring (point-min) (point))))
1843 (t (org-remove-indentation (org-element-property :value table))))
1844 ;; Possible add a caption string below.
1845 (and (not caption-above-p) caption))
1846 table info)))
1849 ;;;; Table Cell
1851 (defun org-ascii--table-cell-width (table-cell info)
1852 "Return width of TABLE-CELL.
1854 INFO is a plist used as a communication channel.
1856 Width of a cell is determined either by a width cookie in the
1857 same column as the cell, or by the maximum cell's length in that
1858 column.
1860 When `org-ascii-table-widen-columns' is non-nil, width cookies
1861 are ignored."
1862 (let* ((row (org-export-get-parent table-cell))
1863 (table (org-export-get-parent row))
1864 (col (let ((cells (org-element-contents row)))
1865 (- (length cells) (length (memq table-cell cells)))))
1866 (cache
1867 (or (plist-get info :ascii-table-cell-width-cache)
1868 (plist-get (setq info
1869 (plist-put info :ascii-table-cell-width-cache
1870 (make-hash-table :test 'equal)))
1871 :ascii-table-cell-width-cache)))
1872 (key (cons table col))
1873 (widenp (plist-get info :ascii-table-widen-columns)))
1874 (or (gethash key cache)
1875 (puthash
1877 (let ((cookie-width (org-export-table-cell-width table-cell info)))
1878 (or (and (not widenp) cookie-width)
1879 (let ((contents-width
1880 (let ((max-width 0))
1881 (org-element-map table 'table-row
1882 (lambda (row)
1883 (setq max-width
1884 (max (string-width
1885 (org-export-data
1886 (org-element-contents
1887 (elt (org-element-contents row) col))
1888 info))
1889 max-width)))
1890 info)
1891 max-width)))
1892 (cond ((not cookie-width) contents-width)
1893 (widenp (max cookie-width contents-width))
1894 (t cookie-width)))))
1895 cache))))
1897 (defun org-ascii-table-cell (table-cell contents info)
1898 "Transcode a TABLE-CELL object from Org to ASCII.
1899 CONTENTS is the cell contents. INFO is a plist used as
1900 a communication channel."
1901 ;; Determine column width. When `org-ascii-table-widen-columns'
1902 ;; is nil and some width cookie has set it, use that value.
1903 ;; Otherwise, compute the maximum width among transcoded data of
1904 ;; each cell in the column.
1905 (let ((width (org-ascii--table-cell-width table-cell info)))
1906 ;; When contents are too large, truncate them.
1907 (unless (or (plist-get info :ascii-table-widen-columns)
1908 (<= (string-width (or contents "")) width))
1909 (setq contents (concat (substring contents 0 (- width 2)) "=>")))
1910 ;; Align contents correctly within the cell.
1911 (let* ((indent-tabs-mode nil)
1912 (data
1913 (when contents
1914 (org-ascii--justify-lines
1915 contents width
1916 (org-export-table-cell-alignment table-cell info)))))
1917 (setq contents
1918 (concat data
1919 (make-string (- width (string-width (or data ""))) ?\s))))
1920 ;; Return cell.
1921 (concat (format " %s " contents)
1922 (when (memq 'right (org-export-table-cell-borders table-cell info))
1923 (if (eq (plist-get info :ascii-charset) 'utf-8) "│" "|")))))
1926 ;;;; Table Row
1928 (defun org-ascii-table-row (table-row contents info)
1929 "Transcode a TABLE-ROW element from Org to ASCII.
1930 CONTENTS is the row contents. INFO is a plist used as
1931 a communication channel."
1932 (when (eq (org-element-property :type table-row) 'standard)
1933 (let ((build-hline
1934 (function
1935 (lambda (lcorner horiz vert rcorner)
1936 (concat
1937 (apply
1938 'concat
1939 (org-element-map table-row 'table-cell
1940 (lambda (cell)
1941 (let ((width (org-ascii--table-cell-width cell info))
1942 (borders (org-export-table-cell-borders cell info)))
1943 (concat
1944 ;; In order to know if CELL starts the row, do
1945 ;; not compare it with the first cell in the
1946 ;; row as there might be a special column.
1947 ;; Instead, compare it with first exportable
1948 ;; cell, obtained with `org-element-map'.
1949 (when (and (memq 'left borders)
1950 (eq (org-element-map table-row 'table-cell
1951 'identity info t)
1952 cell))
1953 lcorner)
1954 (make-string (+ 2 width) (string-to-char horiz))
1955 (cond
1956 ((not (memq 'right borders)) nil)
1957 ((eq (car (last (org-element-contents table-row))) cell)
1958 rcorner)
1959 (t vert)))))
1960 info)) "\n"))))
1961 (utf8p (eq (plist-get info :ascii-charset) 'utf-8))
1962 (borders (org-export-table-cell-borders
1963 (org-element-map table-row 'table-cell 'identity info t)
1964 info)))
1965 (concat (cond
1966 ((and (memq 'top borders) (or utf8p (memq 'above borders)))
1967 (if utf8p (funcall build-hline "┍" "━" "┯" "┑")
1968 (funcall build-hline "+" "-" "+" "+")))
1969 ((memq 'above borders)
1970 (if utf8p (funcall build-hline "├" "─" "┼" "┤")
1971 (funcall build-hline "+" "-" "+" "+"))))
1972 (when (memq 'left borders) (if utf8p "│" "|"))
1973 contents "\n"
1974 (when (and (memq 'bottom borders) (or utf8p (memq 'below borders)))
1975 (if utf8p (funcall build-hline "┕" "━" "┷" "┙")
1976 (funcall build-hline "+" "-" "+" "+")))))))
1979 ;;;; Timestamp
1981 (defun org-ascii-timestamp (timestamp _contents info)
1982 "Transcode a TIMESTAMP object from Org to ASCII.
1983 CONTENTS is nil. INFO is a plist holding contextual information."
1984 (org-ascii-plain-text (org-timestamp-translate timestamp) info))
1987 ;;;; Underline
1989 (defun org-ascii-underline (_underline contents _info)
1990 "Transcode UNDERLINE from Org to ASCII.
1991 CONTENTS is the text with underline markup. INFO is a plist
1992 holding contextual information."
1993 (format "_%s_" contents))
1996 ;;;; Verbatim
1998 (defun org-ascii-verbatim (verbatim _contents info)
1999 "Return a VERBATIM object from Org to ASCII.
2000 CONTENTS is nil. INFO is a plist holding contextual information."
2001 (format (plist-get info :ascii-verbatim-format)
2002 (org-element-property :value verbatim)))
2005 ;;;; Verse Block
2007 (defun org-ascii-verse-block (verse-block contents info)
2008 "Transcode a VERSE-BLOCK element from Org to ASCII.
2009 CONTENTS is verse block contents. INFO is a plist holding
2010 contextual information."
2011 (org-ascii--indent-string
2012 (org-ascii--justify-element contents verse-block info)
2013 (plist-get info :ascii-quote-margin)))
2017 ;;; Filters
2019 (defun org-ascii-filter-headline-blank-lines (headline _backend info)
2020 "Filter controlling number of blank lines after a headline.
2022 HEADLINE is a string representing a transcoded headline. BACKEND
2023 is symbol specifying back-end used for export. INFO is plist
2024 containing the communication channel.
2026 This function only applies to `ascii' back-end. See
2027 `org-ascii-headline-spacing' for information."
2028 (let ((headline-spacing (plist-get info :ascii-headline-spacing)))
2029 (if (not headline-spacing) headline
2030 (let ((blanks (make-string (1+ (cdr headline-spacing)) ?\n)))
2031 (replace-regexp-in-string "\n\\(?:\n[ \t]*\\)*\\'" blanks headline)))))
2033 (defun org-ascii-filter-paragraph-spacing (tree _backend info)
2034 "Filter controlling number of blank lines between paragraphs.
2036 TREE is the parse tree. BACKEND is the symbol specifying
2037 back-end used for export. INFO is a plist used as
2038 a communication channel.
2040 See `org-ascii-paragraph-spacing' for information."
2041 (let ((paragraph-spacing (plist-get info :ascii-paragraph-spacing)))
2042 (when (wholenump paragraph-spacing)
2043 (org-element-map tree 'paragraph
2044 (lambda (p)
2045 (when (eq (org-element-type (org-export-get-next-element p info))
2046 'paragraph)
2047 (org-element-put-property p :post-blank paragraph-spacing))))))
2048 tree)
2050 (defun org-ascii-filter-comment-spacing (tree _backend info)
2051 "Filter removing blank lines between comments.
2052 TREE is the parse tree. BACKEND is the symbol specifying
2053 back-end used for export. INFO is a plist used as
2054 a communication channel."
2055 (org-element-map tree '(comment comment-block)
2056 (lambda (c)
2057 (when (memq (org-element-type (org-export-get-next-element c info))
2058 '(comment comment-block))
2059 (org-element-put-property c :post-blank 0))))
2060 tree)
2064 ;;; End-user functions
2066 ;;;###autoload
2067 (defun org-ascii-export-as-ascii
2068 (&optional async subtreep visible-only body-only ext-plist)
2069 "Export current buffer to a text buffer.
2071 If narrowing is active in the current buffer, only export its
2072 narrowed part.
2074 If a region is active, export that region.
2076 A non-nil optional argument ASYNC means the process should happen
2077 asynchronously. The resulting buffer should be accessible
2078 through the `org-export-stack' interface.
2080 When optional argument SUBTREEP is non-nil, export the sub-tree
2081 at point, extracting information from the headline properties
2082 first.
2084 When optional argument VISIBLE-ONLY is non-nil, don't export
2085 contents of hidden elements.
2087 When optional argument BODY-ONLY is non-nil, strip title and
2088 table of contents from output.
2090 EXT-PLIST, when provided, is a property list with external
2091 parameters overriding Org default settings, but still inferior to
2092 file-local settings.
2094 Export is done in a buffer named \"*Org ASCII Export*\", which
2095 will be displayed when `org-export-show-temporary-export-buffer'
2096 is non-nil."
2097 (interactive)
2098 (org-export-to-buffer 'ascii "*Org ASCII Export*"
2099 async subtreep visible-only body-only ext-plist (lambda () (text-mode))))
2101 ;;;###autoload
2102 (defun org-ascii-export-to-ascii
2103 (&optional async subtreep visible-only body-only ext-plist)
2104 "Export current buffer to a text file.
2106 If narrowing is active in the current buffer, only export its
2107 narrowed part.
2109 If a region is active, export that region.
2111 A non-nil optional argument ASYNC means the process should happen
2112 asynchronously. The resulting file should be accessible through
2113 the `org-export-stack' interface.
2115 When optional argument SUBTREEP is non-nil, export the sub-tree
2116 at point, extracting information from the headline properties
2117 first.
2119 When optional argument VISIBLE-ONLY is non-nil, don't export
2120 contents of hidden elements.
2122 When optional argument BODY-ONLY is non-nil, strip title and
2123 table of contents from output.
2125 EXT-PLIST, when provided, is a property list with external
2126 parameters overriding Org default settings, but still inferior to
2127 file-local settings.
2129 Return output file's name."
2130 (interactive)
2131 (let ((file (org-export-output-file-name ".txt" subtreep)))
2132 (org-export-to-file 'ascii file
2133 async subtreep visible-only body-only ext-plist)))
2135 ;;;###autoload
2136 (defun org-ascii-publish-to-ascii (plist filename pub-dir)
2137 "Publish an Org file to ASCII.
2139 FILENAME is the filename of the Org file to be published. PLIST
2140 is the property list for the given project. PUB-DIR is the
2141 publishing directory.
2143 Return output file name."
2144 (org-publish-org-to
2145 'ascii filename ".txt" `(:ascii-charset ascii ,@plist) pub-dir))
2147 ;;;###autoload
2148 (defun org-ascii-publish-to-latin1 (plist filename pub-dir)
2149 "Publish an Org file to Latin-1.
2151 FILENAME is the filename of the Org file to be published. PLIST
2152 is the property list for the given project. PUB-DIR is the
2153 publishing directory.
2155 Return output file name."
2156 (org-publish-org-to
2157 'ascii filename ".txt" `(:ascii-charset latin1 ,@plist) pub-dir))
2159 ;;;###autoload
2160 (defun org-ascii-publish-to-utf8 (plist filename pub-dir)
2161 "Publish an org file to UTF-8.
2163 FILENAME is the filename of the Org file to be published. PLIST
2164 is the property list for the given project. PUB-DIR is the
2165 publishing directory.
2167 Return output file name."
2168 (org-publish-org-to
2169 'ascii filename ".txt" `(:ascii-charset utf-8 ,@plist) pub-dir))
2172 (provide 'ox-ascii)
2174 ;; Local variables:
2175 ;; generated-autoload-file: "org-loaddefs.el"
2176 ;; coding: utf-8
2177 ;; End:
2179 ;;; ox-ascii.el ends here