1 ;;; ox-ascii.el --- ASCII Back-End for Org Export Engine
3 ;; Copyright (C) 2012-2014 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/>.
25 ;; This library implements an ASCII back-end for Org generic exporter.
26 ;; See Org manual for more information.
30 (eval-when-compile (require 'cl
))
34 (declare-function aa2u
"ext:ascii-art-to-unicode" ())
38 ;; The following setting won't allow to modify preferred charset
39 ;; through a buffer keyword or an option item, but, since the property
40 ;; will appear in communication channel nonetheless, it allows to
41 ;; override `org-ascii-charset' variable on the fly by the ext-plist
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 (comment .
(lambda (&rest args
) ""))
53 (comment-block .
(lambda (&rest args
) ""))
54 (drawer . org-ascii-drawer
)
55 (dynamic-block . org-ascii-dynamic-block
)
56 (entity . org-ascii-entity
)
57 (example-block . org-ascii-example-block
)
58 (export-block . org-ascii-export-block
)
59 (export-snippet . org-ascii-export-snippet
)
60 (fixed-width . org-ascii-fixed-width
)
61 (footnote-reference . org-ascii-footnote-reference
)
62 (headline . org-ascii-headline
)
63 (horizontal-rule . org-ascii-horizontal-rule
)
64 (inline-src-block . org-ascii-inline-src-block
)
65 (inlinetask . org-ascii-inlinetask
)
66 (inner-template . org-ascii-inner-template
)
67 (italic . org-ascii-italic
)
68 (item . org-ascii-item
)
69 (keyword . org-ascii-keyword
)
70 (latex-environment . org-ascii-latex-environment
)
71 (latex-fragment . org-ascii-latex-fragment
)
72 (line-break . org-ascii-line-break
)
73 (link . org-ascii-link
)
74 (node-property . org-ascii-node-property
)
75 (paragraph . org-ascii-paragraph
)
76 (plain-list . org-ascii-plain-list
)
77 (plain-text . org-ascii-plain-text
)
78 (planning . org-ascii-planning
)
79 (property-drawer . org-ascii-property-drawer
)
80 (quote-block . org-ascii-quote-block
)
81 (radio-target . org-ascii-radio-target
)
82 (section . org-ascii-section
)
83 (special-block . org-ascii-special-block
)
84 (src-block . org-ascii-src-block
)
85 (statistics-cookie . org-ascii-statistics-cookie
)
86 (strike-through . org-ascii-strike-through
)
87 (subscript . org-ascii-subscript
)
88 (superscript . org-ascii-superscript
)
89 (table . org-ascii-table
)
90 (table-cell . org-ascii-table-cell
)
91 (table-row . org-ascii-table-row
)
92 (target . org-ascii-target
)
93 (template . org-ascii-template
)
94 (timestamp . org-ascii-timestamp
)
95 (underline . org-ascii-underline
)
96 (verbatim . org-ascii-verbatim
)
97 (verse-block . org-ascii-verse-block
))
100 '(?t
"Export to Plain Text"
101 ((?A
"As ASCII buffer"
103 (org-ascii-export-as-ascii a s v b
'(:ascii-charset ascii
))))
106 (org-ascii-export-to-ascii a s v b
'(:ascii-charset ascii
))))
107 (?L
"As Latin1 buffer"
109 (org-ascii-export-as-ascii a s v b
'(:ascii-charset latin1
))))
112 (org-ascii-export-to-ascii a s v b
'(:ascii-charset latin1
))))
113 (?U
"As UTF-8 buffer"
115 (org-ascii-export-as-ascii a s v b
'(:ascii-charset utf-8
))))
118 (org-ascii-export-to-ascii a s v b
'(:ascii-charset utf-8
))))))
119 :filters-alist
'((:filter-headline . org-ascii-filter-headline-blank-lines
)
120 (:filter-parse-tree org-ascii-filter-paragraph-spacing
121 org-ascii-filter-comment-spacing
)
122 (:filter-section . org-ascii-filter-headline-blank-lines
))
123 :options-alist
'((:ascii-charset nil nil org-ascii-charset
)))
127 ;;; User Configurable Variables
129 (defgroup org-export-ascii nil
130 "Options for exporting Org mode files to ASCII."
131 :tag
"Org Export ASCII"
134 (defcustom org-ascii-text-width
72
135 "Maximum width of exported text.
136 This number includes margin size, as set in
137 `org-ascii-global-margin'."
138 :group
'org-export-ascii
140 :package-version
'(Org .
"8.0")
143 (defcustom org-ascii-global-margin
0
144 "Width of the left margin, in number of characters."
145 :group
'org-export-ascii
147 :package-version
'(Org .
"8.0")
150 (defcustom org-ascii-inner-margin
2
151 "Width of the inner margin, in number of characters.
152 Inner margin is applied between each headline."
153 :group
'org-export-ascii
155 :package-version
'(Org .
"8.0")
158 (defcustom org-ascii-quote-margin
6
159 "Width of margin used for quoting text, in characters.
160 This margin is applied on both sides of the text."
161 :group
'org-export-ascii
163 :package-version
'(Org .
"8.0")
166 (defcustom org-ascii-inlinetask-width
30
167 "Width of inline tasks, in number of characters.
168 This number ignores any margin."
169 :group
'org-export-ascii
171 :package-version
'(Org .
"8.0")
174 (defcustom org-ascii-headline-spacing
'(1 .
2)
175 "Number of blank lines inserted around headlines.
177 This variable can be set to a cons cell. In that case, its car
178 represents the number of blank lines present before headline
179 contents whereas its cdr reflects the number of blank lines after
182 A nil value replicates the number of blank lines found in the
183 original Org buffer at the same place."
184 :group
'org-export-ascii
186 :package-version
'(Org .
"8.0")
188 (const :tag
"Replicate original spacing" nil
)
189 (cons :tag
"Set an uniform spacing"
190 (integer :tag
"Number of blank lines before contents")
191 (integer :tag
"Number of blank lines after contents"))))
193 (defcustom org-ascii-indented-line-width
'auto
194 "Additional indentation width for the first line in a paragraph.
195 If the value is an integer, indent the first line of each
196 paragraph by this width, unless it is located at the beginning of
197 a section, in which case indentation is removed from that line.
198 If it is the symbol `auto' preserve indentation from original
200 :group
'org-export-ascii
202 :package-version
'(Org .
"8.0")
204 (integer :tag
"Number of white spaces characters")
205 (const :tag
"Preserve original width" auto
)))
207 (defcustom org-ascii-paragraph-spacing
'auto
208 "Number of white lines between paragraphs.
209 If the value is an integer, add this number of blank lines
210 between contiguous paragraphs. If is it the symbol `auto', keep
211 the same number of blank lines as in the original document."
212 :group
'org-export-ascii
214 :package-version
'(Org .
"8.0")
216 (integer :tag
"Number of blank lines")
217 (const :tag
"Preserve original spacing" auto
)))
219 (defcustom org-ascii-charset
'ascii
220 "The charset allowed to represent various elements and objects.
222 `ascii' Only use plain ASCII characters
223 `latin1' Include Latin-1 characters
224 `utf-8' Use all UTF-8 characters"
225 :group
'org-export-ascii
227 :package-version
'(Org .
"8.0")
229 (const :tag
"ASCII" ascii
)
230 (const :tag
"Latin-1" latin1
)
231 (const :tag
"UTF-8" utf-8
)))
233 (defcustom org-ascii-underline
'((ascii ?
= ?~ ?-
)
235 (utf-8 ?═ ?─ ?╌ ?┄ ?┈
))
236 "Characters for underlining headings in ASCII export.
238 Alist whose key is a symbol among `ascii', `latin1' and `utf-8'
239 and whose value is a list of characters.
241 For each supported charset, this variable associates a sequence
242 of underline characters. In a sequence, the characters will be
243 used in order for headlines level 1, 2, ... If no character is
244 available for a given level, the headline won't be underlined."
245 :group
'org-export-ascii
247 :package-version
'(Org .
"8.0")
249 (cons :tag
"Underline characters sequence"
250 (const :tag
"ASCII charset" ascii
)
252 (cons :tag
"Underline characters sequence"
253 (const :tag
"Latin-1 charset" latin1
)
255 (cons :tag
"Underline characters sequence"
256 (const :tag
"UTF-8 charset" utf-8
)
257 (repeat character
))))
259 (defcustom org-ascii-bullets
'((ascii ?
* ?
+ ?-
)
262 "Bullet characters for headlines converted to lists in ASCII export.
264 Alist whose key is a symbol among `ascii', `latin1' and `utf-8'
265 and whose value is a list of characters.
267 The first character is used for the first level considered as low
268 level, and so on. If there are more levels than characters given
269 here, the list will be repeated.
271 Note that this variable doesn't affect plain lists
273 :group
'org-export-ascii
275 :package-version
'(Org .
"8.0")
277 (cons :tag
"Bullet characters for low level headlines"
278 (const :tag
"ASCII charset" ascii
)
280 (cons :tag
"Bullet characters for low level headlines"
281 (const :tag
"Latin-1 charset" latin1
)
283 (cons :tag
"Bullet characters for low level headlines"
284 (const :tag
"UTF-8 charset" utf-8
)
285 (repeat character
))))
287 (defcustom org-ascii-links-to-notes t
288 "Non-nil means convert links to notes before the next headline.
289 When nil, the link will be exported in place. If the line
290 becomes long in this way, it will be wrapped."
291 :group
'org-export-ascii
293 :package-version
'(Org .
"8.0")
296 (defcustom org-ascii-table-keep-all-vertical-lines nil
297 "Non-nil means keep all vertical lines in ASCII tables.
298 When nil, vertical lines will be removed except for those needed
299 for column grouping."
300 :group
'org-export-ascii
302 :package-version
'(Org .
"8.0")
305 (defcustom org-ascii-table-widen-columns t
306 "Non-nil means widen narrowed columns for export.
307 When nil, narrowed columns will look in ASCII export just like in
308 Org mode, i.e. with \"=>\" as ellipsis."
309 :group
'org-export-ascii
311 :package-version
'(Org .
"8.0")
314 (defcustom org-ascii-table-use-ascii-art nil
315 "Non-nil means table.el tables are turned into ascii-art.
317 It only makes sense when export charset is `utf-8'. It is nil by
318 default since it requires ascii-art-to-unicode.el package. You
319 can download it here:
321 http://gnuvola.org/software/j/aa2u/ascii-art-to-unicode.el."
322 :group
'org-export-ascii
324 :package-version
'(Org .
"8.0")
327 (defcustom org-ascii-caption-above nil
328 "When non-nil, place caption string before the element.
329 Otherwise, place it right after it."
330 :group
'org-export-ascii
332 :package-version
'(Org .
"8.0")
335 (defcustom org-ascii-verbatim-format
"`%s'"
336 "Format string used for verbatim text and inline code."
337 :group
'org-export-ascii
339 :package-version
'(Org .
"8.0")
342 (defcustom org-ascii-format-drawer-function
343 (lambda (name contents width
) contents
)
344 "Function called to format a drawer in ASCII.
346 The function must accept three parameters:
347 NAME the drawer name, like \"LOGBOOK\"
348 CONTENTS the contents of the drawer.
349 WIDTH the text width within the drawer.
351 The function should return either the string to be exported or
352 nil to ignore the drawer.
354 The default value simply returns the value of CONTENTS."
355 :group
'org-export-ascii
357 :package-version
'(Org .
"8.0")
360 (defcustom org-ascii-format-inlinetask-function
361 'org-ascii-format-inlinetask-default
362 "Function called to format an inlinetask in ASCII.
364 The function must accept nine parameters:
365 TODO the todo keyword, as a string
366 TODO-TYPE the todo type, a symbol among `todo', `done' and nil.
367 PRIORITY the inlinetask priority, as a string
368 NAME the inlinetask name, as a string.
369 TAGS the inlinetask tags, as a list of strings.
370 CONTENTS the contents of the inlinetask, as a string.
371 WIDTH the width of the inlinetask, as a number.
372 INLINETASK the inlinetask itself.
373 INFO the info channel.
375 The function should return either the string to be exported or
376 nil to ignore the inline task."
377 :group
'org-export-ascii
379 :package-version
'(Org .
"8.3")
384 ;;; Internal Functions
386 ;; Internal functions fall into three categories.
388 ;; The first one is about text formatting. The core functions are
389 ;; `org-ascii--current-text-width' and
390 ;; `org-ascii--current-justification', which determine, respectively,
391 ;; the current text width allowed to a given element and its expected
392 ;; justification. Once this information is known,
393 ;; `org-ascii--fill-string', `org-ascii--justify-lines',
394 ;; `org-ascii--justify-element' `org-ascii--box-string' and
395 ;; `org-ascii--indent-string' can operate on a given output string.
396 ;; In particular, justification happens at the regular (i.e.,
397 ;; non-greater) element level, which means that when the exporting
398 ;; process reaches a container (e.g., a center block) content are
399 ;; already justified.
401 ;; The second category contains functions handling elements listings,
402 ;; triggered by "#+TOC:" keyword. As such, `org-ascii--build-toc'
403 ;; returns a complete table of contents, `org-ascii--list-listings'
404 ;; returns a list of referenceable src-block elements, and
405 ;; `org-ascii--list-tables' does the same for table elements.
407 ;; The third category includes general helper functions.
408 ;; `org-ascii--build-title' creates the title for a given headline
409 ;; or inlinetask element. `org-ascii--build-caption' returns the
410 ;; caption string associated to a table or a src-block.
411 ;; `org-ascii--describe-links' creates notes about links for
412 ;; insertion at the end of a section. It uses
413 ;; `org-ascii--unique-links' to get the list of links to describe.
414 ;; Eventually, `org-ascii--translate' translates a string according
415 ;; to language and charset specification.
418 (defun org-ascii--fill-string (s text-width info
&optional justify
)
419 "Fill a string with specified text-width and return it.
421 S is the string being filled. TEXT-WIDTH is an integer
422 specifying maximum length of a line. INFO is the plist used as
423 a communication channel.
425 Optional argument JUSTIFY can specify any type of justification
426 among `left', `center', `right' or `full'. A nil value is
427 equivalent to `left'. For a justification that doesn't also fill
428 string, see `org-ascii--justify-lines' and
429 `org-ascii--justify-block'.
431 Return nil if S isn't a string."
432 ;; Don't fill paragraph when break should be preserved.
433 (cond ((not (stringp s
)) nil
)
434 ((plist-get info
:preserve-breaks
) s
)
435 (t (let ((double-space-p sentence-end-double-space
))
437 (let ((fill-column text-width
)
438 (use-hard-newlines t
)
439 (sentence-end-double-space double-space-p
))
441 (fill-region (point-min) (point-max) justify
))
444 (defun org-ascii--justify-lines (s text-width how
)
445 "Justify all lines in string S.
446 TEXT-WIDTH is an integer specifying maximum length of a line.
447 HOW determines the type of justification: it can be `left',
448 `right', `full' or `center'."
451 (goto-char (point-min))
452 (let ((fill-column text-width
)
453 ;; Disable `adaptive-fill-mode' so it doesn't prevent
454 ;; filling lines matching `adaptive-fill-regexp'.
455 (adaptive-fill-mode nil
))
456 (while (< (point) (point-max))
457 (justify-current-line how
)
461 (defun org-ascii--justify-element (contents element info
)
462 "Justify CONTENTS of ELEMENT.
463 INFO is a plist used as a communication channel. Justification
464 is done according to the type of element. More accurately,
465 paragraphs are filled and other elements are justified as blocks,
466 that is according to the widest non blank line in CONTENTS."
467 (if (not (org-string-nw-p contents
)) contents
468 (let ((text-width (org-ascii--current-text-width element info
))
469 (how (org-ascii--current-justification element
)))
470 (if (eq how
'left
) contents
471 ;; Paragraphs are treated specially as they also need to be
473 (if (eq (org-element-type element
) 'paragraph
)
474 (org-ascii--fill-string contents text-width info how
)
477 (goto-char (point-min))
480 ;; Compute maximum width. Bail out if it is greater
481 ;; than page width, since no justification is
485 (unless (org-looking-at-p "[ \t]*$")
487 (let ((column (current-column)))
489 ((>= column text-width
) (throw 'exit contents
))
490 ((> column max-width
) (setq max-width column
)))))
492 ;; Justify every line according to TEXT-WIDTH and
494 (let ((offset (/ (- text-width max-width
)
495 (if (eq how
'right
) 1 2))))
496 (if (zerop offset
) (throw 'exit contents
)
498 (unless (org-looking-at-p "[ \t]*$")
499 (org-indent-to-column offset
))
501 (buffer-string))))))))
503 (defun org-ascii--indent-string (s width
)
504 "Indent string S by WIDTH white spaces.
505 Empty lines are not indented."
507 (replace-regexp-in-string
508 "\\(^\\)[ \t]*\\S-" (make-string width ?\s
) s nil nil
1)))
510 (defun org-ascii--box-string (s info
)
511 "Return string S with a partial box to its left.
512 INFO is a plist used as a communication channel."
513 (let ((utf8p (eq (plist-get info
:ascii-charset
) 'utf-8
)))
514 (format (if utf8p
"╭────\n%s\n╰────" ",----\n%s\n`----")
515 (replace-regexp-in-string
516 "^" (if utf8p
"│ " "| ")
517 ;; Remove last newline character.
518 (replace-regexp-in-string "\n[ \t]*\\'" "" s
)))))
520 (defun org-ascii--current-text-width (element info
)
521 "Return maximum text width for ELEMENT's contents.
522 INFO is a plist used as a communication channel."
523 (case (org-element-type element
)
524 ;; Elements with an absolute width: `headline' and `inlinetask'.
525 (inlinetask org-ascii-inlinetask-width
)
527 (- org-ascii-text-width
528 (let ((low-level-rank (org-export-low-level-p element info
)))
529 (if low-level-rank
(* low-level-rank
2) org-ascii-global-margin
))))
530 ;; Elements with a relative width: store maximum text width in
533 (let* ((genealogy (cons element
(org-export-get-genealogy element
)))
534 ;; Total width is determined by the presence, or not, of an
535 ;; inline task among ELEMENT parents.
537 (if (loop for parent in genealogy
538 thereis
(eq (org-element-type parent
) 'inlinetask
))
539 org-ascii-inlinetask-width
540 ;; No inlinetask: Remove global margin from text width.
541 (- org-ascii-text-width
542 org-ascii-global-margin
543 (let ((parent (org-export-get-parent-headline element
)))
544 ;; Inner margin doesn't apply to text before first
547 (let ((low-level-rank
548 (org-export-low-level-p parent info
)))
549 ;; Inner margin doesn't apply to contents of
550 ;; low level headlines, since they've got their
551 ;; own indentation mechanism.
552 (if low-level-rank
(* low-level-rank
2)
553 org-ascii-inner-margin
))))))))
555 ;; Each `quote-block' and `verse-block' above narrows text
556 ;; width by twice the standard margin size.
557 (+ (* (loop for parent in genealogy
558 when
(memq (org-element-type parent
)
559 '(quote-block verse-block
))
561 2 org-ascii-quote-margin
)
562 ;; Text width within a plain-list is restricted by
563 ;; indentation of current item. If that's the case,
564 ;; compute it with the help of `:structure' property from
565 ;; parent item, if any.
567 (if (eq (org-element-type element
) 'item
) element
568 (loop for parent in genealogy
569 when
(eq (org-element-type parent
) 'item
)
571 (if (not parent-item
) 0
572 ;; Compute indentation offset of the current item,
573 ;; that is the sum of the difference between its
574 ;; indentation and the indentation of the top item in
575 ;; the list and current item bullet's length. Also
576 ;; remove checkbox length, and tag length (for
577 ;; description lists) or bullet length.
578 (let ((struct (org-element-property :structure parent-item
))
579 (beg-item (org-element-property :begin parent-item
)))
580 (+ (- (org-list-get-ind beg-item struct
)
582 (org-list-get-top-point struct
) struct
))
583 (string-width (or (org-ascii--checkbox parent-item info
)
586 (or (org-list-get-tag beg-item struct
)
587 (org-list-get-bullet beg-item struct
)))))))))))))
589 (defun org-ascii--current-justification (element)
590 "Return expected justification for ELEMENT's contents.
591 Return value is a symbol among `left', `center', `right' and
594 (while (and (not justification
)
595 (setq element
(org-element-property :parent element
)))
596 (case (org-element-type element
)
597 (center-block (setq justification
'center
))
599 (let ((name (org-element-property :type element
)))
600 (cond ((string= name
"JUSTIFYRIGHT") (setq justification
'right
))
601 ((string= name
"JUSTIFYLEFT") (setq justification
'left
)))))))
602 (or justification
'left
)))
604 (defun org-ascii--build-title
605 (element info text-width
&optional underline notags toc
)
606 "Format ELEMENT title and return it.
608 ELEMENT is either an `headline' or `inlinetask' element. INFO is
609 a plist used as a communication channel. TEXT-WIDTH is an
610 integer representing the maximum length of a line.
612 When optional argument UNDERLINE is non-nil, underline title,
613 without the tags, according to `org-ascii-underline'
616 If optional argument NOTAGS is non-nil, no tags will be added to
619 When optional argument TOC is non-nil, use optional title if
620 possible. It doesn't apply to `inlinetask' elements."
621 (let* ((headlinep (eq (org-element-type element
) 'headline
))
623 ;; Numbering is specific to headlines.
624 (and headlinep
(org-export-numbered-headline-p element info
)
625 ;; All tests passed: build numbering string.
629 (org-export-get-headline-number element info
) ".")
634 (if (and toc headlinep
) (org-export-get-alt-title element info
)
635 (org-element-property :title element
))
638 (and (plist-get info
:with-todo-keywords
)
639 (let ((todo (org-element-property :todo-keyword element
)))
640 (and todo
(concat (org-export-data todo info
) " ")))))
641 (tags (and (not notags
)
642 (plist-get info
:with-tags
)
643 (let ((tag-list (org-export-get-tags element info
)))
646 (mapconcat 'identity tag-list
":"))))))
648 (and (plist-get info
:with-priority
)
649 (let ((char (org-element-property :priority element
)))
650 (and char
(format "(#%c) " char
)))))
651 (first-part (concat numbers todo priority text
)))
654 ;; Align tags, if any.
658 (max (- text-width
(1+ (string-width first-part
)))
659 (string-width tags
)))
661 ;; Maybe underline text, if ELEMENT type is `headline' and an
662 ;; underline character has been defined.
663 (when (and underline headlinep
)
665 (nth (1- (org-export-get-relative-level element info
))
666 (cdr (assq (plist-get info
:ascii-charset
)
667 org-ascii-underline
)))))
670 (make-string (/ (string-width first-part
)
671 (char-width under-char
))
674 (defun org-ascii--has-caption-p (element info
)
675 "Non-nil when ELEMENT has a caption affiliated keyword.
676 INFO is a plist used as a communication channel. This function
677 is meant to be used as a predicate for `org-export-get-ordinal'."
678 (org-element-property :caption element
))
680 (defun org-ascii--build-caption (element info
)
681 "Return caption string for ELEMENT, if applicable.
683 INFO is a plist used as a communication channel.
685 The caption string contains the sequence number of ELEMENT along
686 with its real caption. Return nil when ELEMENT has no affiliated
688 (let ((caption (org-export-get-caption element
)))
690 ;; Get sequence number of current src-block among every
691 ;; src-block with a caption.
693 (org-export-get-ordinal
694 element info nil
'org-ascii--has-caption-p
))
695 (title-fmt (org-ascii--translate
696 (case (org-element-type element
)
698 (src-block "Listing %d:"))
700 (org-ascii--fill-string
701 (concat (format title-fmt reference
)
703 (org-export-data caption info
))
704 (org-ascii--current-text-width element info
) info
)))))
706 (defun org-ascii--build-toc (info &optional n keyword
)
707 "Return a table of contents.
709 INFO is a plist used as a communication channel.
711 Optional argument N, when non-nil, is an integer specifying the
714 Optional argument KEYWORD specifies the TOC keyword, if any, from
715 which the table of contents generation has been initiated."
716 (let ((title (org-ascii--translate "Table of Contents" info
)))
719 (make-string (string-width title
)
720 (if (eq (plist-get info
:ascii-charset
) 'utf-8
) ?─ ?_
))
723 (if keyword
(org-ascii--current-text-width keyword info
)
724 (- org-ascii-text-width org-ascii-global-margin
))))
727 (let* ((level (org-export-get-relative-level headline info
))
728 (indent (* (1- level
) 3)))
730 (unless (zerop indent
) (concat (make-string (1- indent
) ?.
) " "))
731 (org-ascii--build-title
732 headline info
(- text-width indent
) nil
733 (or (not (plist-get info
:with-tags
))
734 (eq (plist-get info
:with-tags
) 'not-in-toc
))
736 (org-export-collect-headlines info n
) "\n")))))
738 (defun org-ascii--list-listings (keyword info
)
739 "Return a list of listings.
741 KEYWORD is the keyword that initiated the list of listings
742 generation. INFO is a plist used as a communication channel."
743 (let ((title (org-ascii--translate "List of Listings" info
)))
746 (make-string (string-width title
)
747 (if (eq (plist-get info
:ascii-charset
) 'utf-8
) ?─ ?_
))
750 (if keyword
(org-ascii--current-text-width keyword info
)
751 (- org-ascii-text-width org-ascii-global-margin
)))
752 ;; Use a counter instead of retrieving ordinal of each
757 ;; Store initial text so its length can be computed. This is
758 ;; used to properly align caption right to it in case of
759 ;; filling (like contents of a description list item).
761 (format (org-ascii--translate "Listing %d:" info
)
763 (initial-width (string-width initial-text
)))
767 (org-ascii--indent-string
768 (org-ascii--fill-string
769 ;; Use short name in priority, if available.
770 (let ((caption (or (org-export-get-caption src-block t
)
771 (org-export-get-caption src-block
))))
772 (org-export-data caption info
))
773 (- text-width initial-width
) info
)
775 (org-export-collect-listings info
) "\n")))))
777 (defun org-ascii--list-tables (keyword info
)
778 "Return a list of tables.
780 KEYWORD is the keyword that initiated the list of tables
781 generation. INFO is a plist used as a communication channel."
782 (let ((title (org-ascii--translate "List of Tables" info
)))
785 (make-string (string-width title
)
786 (if (eq (plist-get info
:ascii-charset
) 'utf-8
) ?─ ?_
))
789 (if keyword
(org-ascii--current-text-width keyword info
)
790 (- org-ascii-text-width org-ascii-global-margin
)))
791 ;; Use a counter instead of retrieving ordinal of each
796 ;; Store initial text so its length can be computed. This is
797 ;; used to properly align caption right to it in case of
798 ;; filling (like contents of a description list item).
800 (format (org-ascii--translate "Table %d:" info
)
802 (initial-width (string-width initial-text
)))
806 (org-ascii--indent-string
807 (org-ascii--fill-string
808 ;; Use short name in priority, if available.
809 (let ((caption (or (org-export-get-caption table t
)
810 (org-export-get-caption table
))))
811 (org-export-data caption info
))
812 (- text-width initial-width
) info
)
814 (org-export-collect-tables info
) "\n")))))
816 (defun org-ascii--unique-links (element info
)
817 "Return a list of unique link references in ELEMENT.
818 ELEMENT is either a headline element or a section element. INFO
819 is a plist used as a communication channel."
823 ;; Return LINK if it wasn't referenced so far, or nil.
824 ;; Update SEEN links along the way.
827 ;; Normalize description in footprints.
828 (cons (org-element-property :raw-link link
)
829 (let ((contents (org-element-contents link
)))
831 (replace-regexp-in-string
834 (org-element-interpret-data contents
))))))))
835 ;; Ignore LINK if it hasn't been translated already.
836 ;; It can happen if it is located in an affiliated
837 ;; keyword that was ignored.
838 (when (and (org-string-nw-p
839 (gethash link
(plist-get info
:exported-data
)))
840 (not (member footprint seen
)))
841 (push footprint seen
) link
)))))
842 ;; If at a section, find parent headline, if any, in order to
843 ;; count links that might be in the title.
845 (if (eq (org-element-type element
) 'headline
) element
846 (or (org-export-get-parent-headline element
) element
))))
847 ;; Get all links in HEADLINE.
848 (org-element-map headline
'link
849 (lambda (l) (funcall unique-link-p l
)) info nil nil t
)))
851 (defun org-ascii--describe-links (links width info
)
852 "Return a string describing a list of links.
854 LINKS is a list of link type objects, as returned by
855 `org-ascii--unique-links'. WIDTH is the text width allowed for
856 the output string. INFO is a plist used as a communication
860 (let ((type (org-element-property :type link
))
861 (anchor (let ((desc (org-element-contents link
)))
862 (if desc
(org-export-data desc info
)
863 (org-element-property :raw-link link
)))))
865 ;; Coderefs, radio links and fuzzy links are ignored.
866 ((member type
'("coderef" "radio" "fuzzy")) nil
)
867 ;; Id and custom-id links: Headlines refer to their numbering.
868 ((member type
'("custom-id" "id"))
869 (let ((dest (org-export-resolve-id-link link info
)))
871 (org-ascii--fill-string
875 (if (not dest
) (org-ascii--translate "Unknown reference" info
)
877 (org-ascii--translate "See section %s" info
)
878 (mapconcat 'number-to-string
879 (org-export-get-headline-number dest info
) "."))))
880 width info
) "\n\n")))
881 ;; Do not add a link that cannot be resolved and doesn't have
882 ;; any description: destination is already visible in the
884 ((not (org-element-contents link
)) nil
)
887 (org-ascii--fill-string
888 (format "[%s] %s" anchor
(org-element-property :raw-link link
))
893 (defun org-ascii--checkbox (item info
)
894 "Return checkbox string for ITEM or nil.
895 INFO is a plist used as a communication channel."
896 (let ((utf8p (eq (plist-get info
:ascii-charset
) 'utf-8
)))
897 (case (org-element-property :checkbox item
)
898 (on (if utf8p
"☑ " "[X] "))
899 (off (if utf8p
"☐ " "[ ] "))
900 (trans (if utf8p
"☒ " "[-] ")))))
906 (defun org-ascii-template--document-title (info)
907 "Return document title, as a string.
908 INFO is a plist used as a communication channel."
909 (let* ((text-width org-ascii-text-width
)
910 ;; Links in the title will not be resolved later, so we make
911 ;; sure their path is located right after them.
912 (org-ascii-links-to-notes nil
)
913 (title (org-export-data (plist-get info
:title
) info
))
914 (author (and (plist-get info
:with-author
)
915 (let ((auth (plist-get info
:author
)))
916 (and auth
(org-export-data auth info
)))))
917 (email (and (plist-get info
:with-email
)
918 (org-export-data (plist-get info
:email
) info
)))
919 (date (and (plist-get info
:with-date
)
920 (org-export-data (org-export-get-date info
) info
))))
921 ;; There are two types of title blocks depending on the presence
922 ;; of a title to display.
923 (if (string= title
"")
924 ;; Title block without a title. DATE is positioned at the top
925 ;; right of the document, AUTHOR to the top left and EMAIL
928 ((and (org-string-nw-p date
) (org-string-nw-p author
))
931 (make-string (- text-width
(string-width date
) (string-width author
))
934 (when (org-string-nw-p email
) (concat "\n" email
))
936 ((and (org-string-nw-p date
) (org-string-nw-p email
))
939 (make-string (- text-width
(string-width date
) (string-width email
))
942 ((org-string-nw-p date
)
944 (org-ascii--justify-lines date text-width
'right
)
946 ((and (org-string-nw-p author
) (org-string-nw-p email
))
947 (concat author
"\n" email
"\n\n\n"))
948 ((org-string-nw-p author
) (concat author
"\n\n\n"))
949 ((org-string-nw-p email
) (concat email
"\n\n\n")))
950 ;; Title block with a title. Document's TITLE, along with the
951 ;; AUTHOR and its EMAIL are both overlined and an underlined,
952 ;; centered. Date is just below, also centered.
953 (let* ((utf8p (eq (plist-get info
:ascii-charset
) 'utf-8
))
954 ;; Format TITLE. It may be filled if it is too wide,
955 ;; that is wider than the two thirds of the total width.
956 (title-len (min (length title
) (/ (* 2 text-width
) 3)))
957 (formatted-title (org-ascii--fill-string title title-len info
))
960 (min (+ (max title-len
961 (string-width (or author
""))
962 (string-width (or email
"")))
964 text-width
) (if utf8p ?━ ?_
))))
965 (org-ascii--justify-lines
968 (upcase formatted-title
)
970 ((and (org-string-nw-p author
) (org-string-nw-p email
))
971 (concat (if utf8p
"\n\n\n" "\n\n") author
"\n" email
))
972 ((org-string-nw-p author
)
973 (concat (if utf8p
"\n\n\n" "\n\n") author
))
974 ((org-string-nw-p email
)
975 (concat (if utf8p
"\n\n\n" "\n\n") email
)))
977 (when (org-string-nw-p date
) (concat "\n\n\n" date
))
978 "\n\n\n") text-width
'center
)))))
980 (defun org-ascii-inner-template (contents info
)
981 "Return complete document string after ASCII conversion.
982 CONTENTS is the transcoded contents string. INFO is a plist
983 holding export options."
984 (org-element-normalize-string
985 (org-ascii--indent-string
987 ;; 1. Document's body.
989 ;; 2. Footnote definitions.
990 (let ((definitions (org-export-collect-footnote-definitions
991 (plist-get info
:parse-tree
) info
))
992 ;; Insert full links right inside the footnote definition
993 ;; as they have no chance to be inserted later.
994 (org-ascii-links-to-notes nil
))
998 (let ((title (org-ascii--translate "Footnotes" info
)))
1002 (string-width title
)
1003 (if (eq (plist-get info
:ascii-charset
) 'utf-8
) ?─ ?_
))))
1005 (let ((text-width (- org-ascii-text-width org-ascii-global-margin
)))
1008 (let ((id (format "[%s] " (car ref
))))
1009 ;; Distinguish between inline definitions and
1010 ;; full-fledged definitions.
1012 (let ((def (nth 2 ref
)))
1013 (if (eq (org-element-type def
) 'org-data
)
1014 ;; Full-fledged definition: footnote ID is
1015 ;; inserted inside the first parsed paragraph
1016 ;; (FIRST), if any, to be sure filling will
1017 ;; take it into consideration.
1018 (let ((first (car (org-element-contents def
))))
1019 (if (not (eq (org-element-type first
) 'paragraph
))
1020 (concat id
"\n" (org-export-data def info
))
1021 (push id
(nthcdr 2 first
))
1022 (org-export-data def info
)))
1023 ;; Fill paragraph once footnote ID is inserted
1024 ;; in order to have a correct length for first
1026 (org-ascii--fill-string
1027 (concat id
(org-export-data def info
))
1028 text-width info
))))))
1029 definitions
"\n\n"))))))
1030 org-ascii-global-margin
)))
1032 (defun org-ascii-template (contents info
)
1033 "Return complete document string after ASCII conversion.
1034 CONTENTS is the transcoded contents string. INFO is a plist
1035 holding export options."
1037 ;; 1. Build title block.
1038 (org-ascii--indent-string
1039 (concat (org-ascii-template--document-title info
)
1040 ;; 2. Table of contents.
1041 (let ((depth (plist-get info
:with-toc
)))
1044 (org-ascii--build-toc info
(and (wholenump depth
) depth
))
1046 org-ascii-global-margin
)
1047 ;; 3. Document's body.
1049 ;; 4. Creator. Ignore `comment' value as there are no comments in
1050 ;; ASCII. Justify it to the bottom right.
1051 (org-ascii--indent-string
1052 (let ((creator-info (plist-get info
:with-creator
))
1053 (text-width (- org-ascii-text-width org-ascii-global-margin
)))
1054 (unless (or (not creator-info
) (eq creator-info
'comment
))
1057 (org-ascii--fill-string
1058 (plist-get info
:creator
) text-width info
'right
))))
1059 org-ascii-global-margin
)))
1061 (defun org-ascii--translate (s info
)
1062 "Translate string S according to specified language and charset.
1063 INFO is a plist used as a communication channel."
1064 (let ((charset (intern (format ":%s" (plist-get info
:ascii-charset
)))))
1065 (org-export-translate s charset info
)))
1069 ;;; Transcode Functions
1073 (defun org-ascii-bold (bold contents info
)
1074 "Transcode BOLD from Org to ASCII.
1075 CONTENTS is the text with bold markup. INFO is a plist holding
1076 contextual information."
1077 (format "*%s*" contents
))
1082 (defun org-ascii-center-block (center-block contents info
)
1083 "Transcode a CENTER-BLOCK element from Org to ASCII.
1084 CONTENTS holds the contents of the block. INFO is a plist
1085 holding contextual information."
1086 ;; Center has already been taken care of at a lower level, so
1087 ;; there's nothing left to do.
1093 (defun org-ascii-clock (clock contents info
)
1094 "Transcode a CLOCK object from Org to ASCII.
1095 CONTENTS is nil. INFO is a plist holding contextual
1097 (org-ascii--justify-element
1098 (concat org-clock-string
" "
1100 (org-element-property :raw-value
1101 (org-element-property :value clock
)))
1102 (let ((time (org-element-property :duration clock
)))
1107 (org-split-string time
":"))))))
1113 (defun org-ascii-code (code contents info
)
1114 "Return a CODE object from Org to ASCII.
1115 CONTENTS is nil. INFO is a plist holding contextual
1117 (format org-ascii-verbatim-format
(org-element-property :value code
)))
1122 (defun org-ascii-drawer (drawer contents info
)
1123 "Transcode a DRAWER element from Org to ASCII.
1124 CONTENTS holds the contents of the block. INFO is a plist
1125 holding contextual information."
1126 (let ((name (org-element-property :drawer-name drawer
))
1127 (width (org-ascii--current-text-width drawer info
)))
1128 (funcall org-ascii-format-drawer-function name contents width
)))
1133 (defun org-ascii-dynamic-block (dynamic-block contents info
)
1134 "Transcode a DYNAMIC-BLOCK element from Org to ASCII.
1135 CONTENTS holds the contents of the block. INFO is a plist
1136 holding contextual information."
1142 (defun org-ascii-entity (entity contents info
)
1143 "Transcode an ENTITY object from Org to ASCII.
1144 CONTENTS are the definition itself. INFO is a plist holding
1145 contextual information."
1146 (org-element-property
1147 (intern (concat ":" (symbol-name (plist-get info
:ascii-charset
))))
1153 (defun org-ascii-example-block (example-block contents info
)
1154 "Transcode a EXAMPLE-BLOCK element from Org to ASCII.
1155 CONTENTS is nil. INFO is a plist holding contextual information."
1156 (org-ascii--justify-element
1157 (org-ascii--box-string
1158 (org-export-format-code-default example-block info
) info
)
1159 example-block info
))
1164 (defun org-ascii-export-snippet (export-snippet contents info
)
1165 "Transcode a EXPORT-SNIPPET object from Org to ASCII.
1166 CONTENTS is nil. INFO is a plist holding contextual information."
1167 (when (eq (org-export-snippet-backend export-snippet
) 'ascii
)
1168 (org-element-property :value export-snippet
)))
1173 (defun org-ascii-export-block (export-block contents info
)
1174 "Transcode a EXPORT-BLOCK element from Org to ASCII.
1175 CONTENTS is nil. INFO is a plist holding contextual information."
1176 (when (string= (org-element-property :type export-block
) "ASCII")
1177 (org-ascii--justify-element
1178 (org-element-property :value export-block
) export-block info
)))
1183 (defun org-ascii-fixed-width (fixed-width contents info
)
1184 "Transcode a FIXED-WIDTH element from Org to ASCII.
1185 CONTENTS is nil. INFO is a plist holding contextual information."
1186 (org-ascii--justify-element
1187 (org-ascii--box-string
1188 (org-remove-indentation
1189 (org-element-property :value fixed-width
)) info
)
1193 ;;;; Footnote Definition
1195 ;; Footnote Definitions are ignored. They are compiled at the end of
1196 ;; the document, by `org-ascii-inner-template'.
1199 ;;;; Footnote Reference
1201 (defun org-ascii-footnote-reference (footnote-reference contents info
)
1202 "Transcode a FOOTNOTE-REFERENCE element from Org to ASCII.
1203 CONTENTS is nil. INFO is a plist holding contextual information."
1204 (format "[%s]" (org-export-get-footnote-number footnote-reference info
)))
1209 (defun org-ascii-headline (headline contents info
)
1210 "Transcode a HEADLINE element from Org to ASCII.
1211 CONTENTS holds the contents of the headline. INFO is a plist
1212 holding contextual information."
1213 ;; Don't export footnote section, which will be handled at the end
1215 (unless (org-element-property :footnote-section-p headline
)
1216 (let* ((low-level-rank (org-export-low-level-p headline info
))
1217 (width (org-ascii--current-text-width headline info
))
1218 ;; Blank lines between headline and its contents.
1219 ;; `org-ascii-headline-spacing', when set, overwrites
1220 ;; original buffer's spacing.
1223 (if org-ascii-headline-spacing
(car org-ascii-headline-spacing
)
1224 (org-element-property :pre-blank headline
)) ?
\n))
1225 ;; Even if HEADLINE has no section, there might be some
1226 ;; links in its title that we shouldn't forget to describe.
1228 (unless (or (eq (caar (org-element-contents headline
)) 'section
))
1229 (let ((title (org-element-property :title headline
)))
1231 (org-ascii--describe-links
1232 (org-ascii--unique-links title info
) width info
))))))
1233 ;; Deep subtree: export it as a list item.
1237 (let ((bullets (cdr (assq (plist-get info
:ascii-charset
)
1238 org-ascii-bullets
))))
1240 (nth (mod (1- low-level-rank
) (length bullets
)) bullets
)))
1243 (org-ascii--build-title headline info width
) "\n"
1244 ;; Contents, indented by length of bullet.
1246 (org-ascii--indent-string
1248 (when (org-string-nw-p links
) (concat "\n\n" links
)))
1250 ;; Else: Standard headline.
1252 (org-ascii--build-title headline info width
'underline
)
1254 (concat (when (org-string-nw-p links
) links
) contents
))))))
1257 ;;;; Horizontal Rule
1259 (defun org-ascii-horizontal-rule (horizontal-rule contents info
)
1260 "Transcode an HORIZONTAL-RULE object from Org to ASCII.
1261 CONTENTS is nil. INFO is a plist holding contextual
1263 (let ((text-width (org-ascii--current-text-width horizontal-rule info
))
1265 (org-export-read-attribute :attr_ascii horizontal-rule
:width
)))
1266 (org-ascii--justify-lines
1267 (make-string (if (and spec-width
(string-match "^[0-9]+$" spec-width
))
1268 (string-to-number spec-width
)
1270 (if (eq (plist-get info
:ascii-charset
) 'utf-8
) ?― ?-
))
1271 text-width
'center
)))
1274 ;;;; Inline Src Block
1276 (defun org-ascii-inline-src-block (inline-src-block contents info
)
1277 "Transcode an INLINE-SRC-BLOCK element from Org to ASCII.
1278 CONTENTS holds the contents of the item. INFO is a plist holding
1279 contextual information."
1280 (format org-ascii-verbatim-format
1281 (org-element-property :value inline-src-block
)))
1286 (defun org-ascii-format-inlinetask-default
1287 (todo type priority name tags contents width inlinetask info
)
1288 "Format an inline task element for ASCII export.
1289 See `org-ascii-format-inlinetask-function' for a description
1291 (let* ((utf8p (eq (plist-get info
:ascii-charset
) 'utf-8
))
1292 (width (or width org-ascii-inlinetask-width
)))
1293 (org-ascii--indent-string
1295 ;; Top line, with an additional blank line if not in UTF-8.
1296 (make-string width
(if utf8p ?━ ?_
)) "\n"
1297 (unless utf8p
(concat (make-string width ?
) "\n"))
1298 ;; Add title. Fill it if wider than inlinetask.
1299 (let ((title (org-ascii--build-title inlinetask info width
)))
1300 (if (<= (string-width title
) width
) title
1301 (org-ascii--fill-string title width info
)))
1303 ;; If CONTENTS is not empty, insert it along with
1305 (when (org-string-nw-p contents
)
1306 (concat (make-string width
(if utf8p ?─ ?-
)) "\n" contents
))
1308 (make-string width
(if utf8p ?━ ?_
)))
1309 ;; Flush the inlinetask to the right.
1310 (- org-ascii-text-width org-ascii-global-margin
1311 (if (not (org-export-get-parent-headline inlinetask
)) 0
1312 org-ascii-inner-margin
)
1313 (org-ascii--current-text-width inlinetask info
)))))
1315 (defun org-ascii-inlinetask (inlinetask contents info
)
1316 "Transcode an INLINETASK element from Org to ASCII.
1317 CONTENTS holds the contents of the block. INFO is a plist
1318 holding contextual information."
1319 (let ((width (org-ascii--current-text-width inlinetask info
)))
1320 (funcall org-ascii-format-inlinetask-function
1322 (and (plist-get info
:with-todo-keywords
)
1323 (let ((todo (org-element-property
1324 :todo-keyword inlinetask
)))
1325 (and todo
(org-export-data todo info
))))
1327 (org-element-property :todo-type inlinetask
)
1329 (and (plist-get info
:with-priority
)
1330 (org-element-property :priority inlinetask
))
1332 (org-export-data (org-element-property :title inlinetask
) info
)
1334 (and (plist-get info
:with-tags
)
1335 (org-element-property :tags inlinetask
))
1336 ;; contents and width
1337 contents width inlinetask info
)))
1342 (defun org-ascii-italic (italic contents info
)
1343 "Transcode italic from Org to ASCII.
1344 CONTENTS is the text with italic markup. INFO is a plist holding
1345 contextual information."
1346 (format "/%s/" contents
))
1351 (defun org-ascii-item (item contents info
)
1352 "Transcode an ITEM element from Org to ASCII.
1353 CONTENTS holds the contents of the item. INFO is a plist holding
1354 contextual information."
1355 (let* ((utf8p (eq (plist-get info
:ascii-charset
) 'utf-8
))
1356 (checkbox (org-ascii--checkbox item info
))
1357 (list-type (org-element-property :type
(org-export-get-parent item
)))
1359 ;; First parent of ITEM is always the plain-list. Get
1360 ;; `:type' property from it.
1361 (org-list-bullet-string
1365 (org-export-data (org-element-property :tag item
) info
)
1368 ;; Return correct number for ITEM, paying attention to
1370 (let* ((struct (org-element-property :structure item
))
1371 (bul (org-element-property :bullet item
))
1372 (num (number-to-string
1373 (car (last (org-list-get-item-number
1374 (org-element-property :begin item
)
1376 (org-list-prevs-alist struct
)
1377 (org-list-parents-alist struct
)))))))
1378 (replace-regexp-in-string "[0-9]+" num bul
)))
1379 (t (let ((bul (org-element-property :bullet item
)))
1380 ;; Change bullets into more visible form if UTF-8 is active.
1382 (replace-regexp-in-string
1384 (replace-regexp-in-string
1386 (replace-regexp-in-string "*" "‣" bul
))))))))))
1389 (unless (eq list-type
'descriptive
) checkbox
)
1390 ;; Contents: Pay attention to indentation. Note: check-boxes are
1391 ;; already taken care of at the paragraph level so they don't
1392 ;; interfere with indentation.
1393 (let ((contents (org-ascii--indent-string contents
(string-width bullet
))))
1394 (if (eq (org-element-type (car (org-element-contents item
))) 'paragraph
)
1396 (concat "\n" contents
))))))
1401 (defun org-ascii-keyword (keyword contents info
)
1402 "Transcode a KEYWORD element from Org to ASCII.
1403 CONTENTS is nil. INFO is a plist holding contextual
1405 (let ((key (org-element-property :key keyword
)))
1407 ((string= key
"ASCII")
1408 (org-ascii--justify-element
1409 (org-element-property :value keyword
) keyword info
))
1410 ((string= key
"TOC")
1411 (org-ascii--justify-element
1412 (let ((value (downcase (org-element-property :value keyword
))))
1414 ((string-match "\\<headlines\\>" value
)
1415 (let ((depth (or (and (string-match "[0-9]+" value
)
1416 (string-to-number (match-string 0 value
)))
1417 (plist-get info
:with-toc
))))
1418 (org-ascii--build-toc
1419 info
(and (wholenump depth
) depth
) keyword
)))
1420 ((string= "tables" value
)
1421 (org-ascii--list-tables keyword info
))
1422 ((string= "listings" value
)
1423 (org-ascii--list-listings keyword info
))))
1427 ;;;; Latex Environment
1429 (defun org-ascii-latex-environment (latex-environment contents info
)
1430 "Transcode a LATEX-ENVIRONMENT element from Org to ASCII.
1431 CONTENTS is nil. INFO is a plist holding contextual
1433 (when (plist-get info
:with-latex
)
1434 (org-ascii--justify-element
1435 (org-remove-indentation (org-element-property :value latex-environment
))
1436 latex-environment info
)))
1441 (defun org-ascii-latex-fragment (latex-fragment contents info
)
1442 "Transcode a LATEX-FRAGMENT object from Org to ASCII.
1443 CONTENTS is nil. INFO is a plist holding contextual
1445 (when (plist-get info
:with-latex
)
1446 (org-element-property :value latex-fragment
)))
1451 (defun org-ascii-line-break (line-break contents info
)
1452 "Transcode a LINE-BREAK object from Org to ASCII.
1453 CONTENTS is nil. INFO is a plist holding contextual
1454 information." hard-newline
)
1459 (defun org-ascii-link (link desc info
)
1460 "Transcode a LINK object from Org to ASCII.
1462 DESC is the description part of the link, or the empty string.
1463 INFO is a plist holding contextual information."
1464 (let ((raw-link (org-element-property :raw-link link
))
1465 (type (org-element-property :type link
)))
1467 ((string= type
"coderef")
1468 (let ((ref (org-element-property :path link
)))
1469 (format (org-export-get-coderef-format ref desc
)
1470 (org-export-resolve-coderef ref info
))))
1471 ;; Do not apply a special syntax on radio links. Though, use
1472 ;; transcoded target's contents as output.
1473 ((string= type
"radio") desc
)
1474 ;; Do not apply a special syntax on fuzzy links pointing to
1476 ((string= type
"fuzzy")
1477 (let ((destination (org-export-resolve-fuzzy-link link info
)))
1478 (if (org-string-nw-p desc
) desc
1481 (org-export-get-ordinal
1482 destination info nil
'org-ascii--has-caption-p
)))
1484 (if (atom number
) (number-to-string number
)
1485 (mapconcat 'number-to-string number
"."))))))))
1487 (if (not (org-string-nw-p desc
)) (format "[%s]" raw-link
)
1489 (format "[%s]" desc
)
1490 (unless org-ascii-links-to-notes
(format " (%s)" raw-link
))))))))
1493 ;;;; Node Properties
1495 (defun org-ascii-node-property (node-property contents info
)
1496 "Transcode a NODE-PROPERTY element from Org to ASCII.
1497 CONTENTS is nil. INFO is a plist holding contextual
1500 (org-element-property :key node-property
)
1501 (let ((value (org-element-property :value node-property
)))
1502 (if value
(concat " " value
) ""))))
1507 (defun org-ascii-paragraph (paragraph contents info
)
1508 "Transcode a PARAGRAPH element from Org to ASCII.
1509 CONTENTS is the contents of the paragraph, as a string. INFO is
1510 the plist used as a communication channel."
1511 (org-ascii--justify-element
1512 (if (not (wholenump org-ascii-indented-line-width
)) contents
1514 ;; Do not indent first paragraph in a section.
1515 (unless (and (not (org-export-get-previous-element paragraph info
))
1516 (eq (org-element-type (org-export-get-parent paragraph
))
1518 (make-string org-ascii-indented-line-width ?\s
))
1519 (replace-regexp-in-string "\\`[ \t]+" "" contents
)))
1525 (defun org-ascii-plain-list (plain-list contents info
)
1526 "Transcode a PLAIN-LIST element from Org to ASCII.
1527 CONTENTS is the contents of the list. INFO is a plist holding
1528 contextual information."
1534 (defun org-ascii-plain-text (text info
)
1535 "Transcode a TEXT string from Org to ASCII.
1536 INFO is a plist used as a communication channel."
1537 (let ((utf8p (eq (plist-get info
:ascii-charset
) 'utf-8
)))
1538 (when (and utf8p
(plist-get info
:with-smart-quotes
))
1539 (setq text
(org-export-activate-smart-quotes text
:utf-8 info
)))
1540 (if (not (plist-get info
:with-special-strings
)) text
1541 (setq text
(replace-regexp-in-string "\\\\-" "" text
))
1542 (if (not utf8p
) text
1543 ;; Usual replacements in utf-8 with proper option set.
1544 (replace-regexp-in-string
1546 (replace-regexp-in-string
1548 (replace-regexp-in-string "---" "—" text
)))))))
1553 (defun org-ascii-planning (planning contents info
)
1554 "Transcode a PLANNING element from Org to ASCII.
1555 CONTENTS is nil. INFO is a plist used as a communication
1557 (org-ascii--justify-element
1561 (list (let ((closed (org-element-property :closed planning
)))
1563 (concat org-closed-string
" "
1565 (org-element-property :raw-value closed
)))))
1566 (let ((deadline (org-element-property :deadline planning
)))
1568 (concat org-deadline-string
" "
1570 (org-element-property :raw-value deadline
)))))
1571 (let ((scheduled (org-element-property :scheduled planning
)))
1573 (concat org-scheduled-string
" "
1575 (org-element-property :raw-value scheduled
)))))))
1580 ;;;; Property Drawer
1582 (defun org-ascii-property-drawer (property-drawer contents info
)
1583 "Transcode a PROPERTY-DRAWER element from Org to ASCII.
1584 CONTENTS holds the contents of the drawer. INFO is a plist
1585 holding contextual information."
1586 (and (org-string-nw-p contents
)
1587 (org-ascii--justify-element contents property-drawer info
)))
1592 (defun org-ascii-quote-block (quote-block contents info
)
1593 "Transcode a QUOTE-BLOCK element from Org to ASCII.
1594 CONTENTS holds the contents of the block. INFO is a plist
1595 holding contextual information."
1596 (org-ascii--indent-string contents org-ascii-quote-margin
))
1601 (defun org-ascii-radio-target (radio-target contents info
)
1602 "Transcode a RADIO-TARGET object from Org to ASCII.
1603 CONTENTS is the contents of the target. INFO is a plist holding
1604 contextual information."
1610 (defun org-ascii-section (section contents info
)
1611 "Transcode a SECTION element from Org to ASCII.
1612 CONTENTS is the contents of the section. INFO is a plist holding
1613 contextual information."
1614 (org-ascii--indent-string
1617 (when org-ascii-links-to-notes
1618 ;; Add list of links at the end of SECTION.
1619 (let ((links (org-ascii--describe-links
1620 (org-ascii--unique-links section info
)
1621 (org-ascii--current-text-width section info
) info
)))
1622 ;; Separate list of links and section contents.
1623 (when (org-string-nw-p links
) (concat "\n\n" links
)))))
1624 ;; Do not apply inner margin if parent headline is low level.
1625 (let ((headline (org-export-get-parent-headline section
)))
1626 (if (or (not headline
) (org-export-low-level-p headline info
)) 0
1627 org-ascii-inner-margin
))))
1632 (defun org-ascii-special-block (special-block contents info
)
1633 "Transcode a SPECIAL-BLOCK element from Org to ASCII.
1634 CONTENTS holds the contents of the block. INFO is a plist
1635 holding contextual information."
1636 ;; "JUSTIFYLEFT" and "JUSTFYRIGHT" have already been taken care of
1637 ;; at a lower level. There is no other special block type to
1644 (defun org-ascii-src-block (src-block contents info
)
1645 "Transcode a SRC-BLOCK element from Org to ASCII.
1646 CONTENTS holds the contents of the item. INFO is a plist holding
1647 contextual information."
1648 (let ((caption (org-ascii--build-caption src-block info
))
1649 (code (org-export-format-code-default src-block info
)))
1650 (if (equal code
"") ""
1651 (org-ascii--justify-element
1653 (when (and caption org-ascii-caption-above
) (concat caption
"\n"))
1654 (org-ascii--box-string code info
)
1655 (when (and caption
(not org-ascii-caption-above
))
1656 (concat "\n" caption
)))
1660 ;;;; Statistics Cookie
1662 (defun org-ascii-statistics-cookie (statistics-cookie contents info
)
1663 "Transcode a STATISTICS-COOKIE object from Org to ASCII.
1664 CONTENTS is nil. INFO is a plist holding contextual information."
1665 (org-element-property :value statistics-cookie
))
1670 (defun org-ascii-subscript (subscript contents info
)
1671 "Transcode a SUBSCRIPT object from Org to ASCII.
1672 CONTENTS is the contents of the object. INFO is a plist holding
1673 contextual information."
1674 (if (org-element-property :use-brackets-p subscript
)
1675 (format "_{%s}" contents
)
1676 (format "_%s" contents
)))
1681 (defun org-ascii-superscript (superscript contents info
)
1682 "Transcode a SUPERSCRIPT object from Org to ASCII.
1683 CONTENTS is the contents of the object. INFO is a plist holding
1684 contextual information."
1685 (if (org-element-property :use-brackets-p superscript
)
1686 (format "^{%s}" contents
)
1687 (format "^%s" contents
)))
1692 (defun org-ascii-strike-through (strike-through contents info
)
1693 "Transcode STRIKE-THROUGH from Org to ASCII.
1694 CONTENTS is text with strike-through markup. INFO is a plist
1695 holding contextual information."
1696 (format "+%s+" contents
))
1701 (defun org-ascii-table (table contents info
)
1702 "Transcode a TABLE element from Org to ASCII.
1703 CONTENTS is the contents of the table. INFO is a plist holding
1704 contextual information."
1705 (let ((caption (org-ascii--build-caption table info
)))
1706 (org-ascii--justify-element
1708 ;; Possibly add a caption string above.
1709 (when (and caption org-ascii-caption-above
) (concat caption
"\n"))
1710 ;; Insert table. Note: "table.el" tables are left unmodified.
1711 (cond ((eq (org-element-property :type table
) 'org
) contents
)
1712 ((and org-ascii-table-use-ascii-art
1713 (eq (plist-get info
:ascii-charset
) 'utf-8
)
1714 (require 'ascii-art-to-unicode nil t
))
1716 (insert (org-remove-indentation
1717 (org-element-property :value table
)))
1718 (goto-char (point-min))
1720 (goto-char (point-max))
1721 (skip-chars-backward " \r\t\n")
1722 (buffer-substring (point-min) (point))))
1723 (t (org-remove-indentation (org-element-property :value table
))))
1724 ;; Possible add a caption string below.
1725 (and (not org-ascii-caption-above
) caption
))
1731 (defun org-ascii--table-cell-width (table-cell info
)
1732 "Return width of TABLE-CELL.
1734 INFO is a plist used as a communication channel.
1736 Width of a cell is determined either by a width cookie in the
1737 same column as the cell, or by the maximum cell's length in that
1740 When `org-ascii-table-widen-columns' is non-nil, width cookies
1742 (let* ((row (org-export-get-parent table-cell
))
1743 (table (org-export-get-parent row
))
1744 (col (let ((cells (org-element-contents row
)))
1745 (- (length cells
) (length (memq table-cell cells
)))))
1747 (or (plist-get info
:ascii-table-cell-width-cache
)
1748 (plist-get (setq info
1749 (plist-put info
:ascii-table-cell-width-cache
1750 (make-hash-table :test
'equal
)))
1751 :ascii-table-cell-width-cache
)))
1752 (key (cons table col
)))
1753 (or (gethash key cache
)
1756 (or (and (not org-ascii-table-widen-columns
)
1757 (org-export-table-cell-width table-cell info
))
1758 (let* ((max-width 0))
1759 (org-element-map table
'table-row
1764 (org-element-contents
1765 (elt (org-element-contents row
) col
))
1772 (defun org-ascii-table-cell (table-cell contents info
)
1773 "Transcode a TABLE-CELL object from Org to ASCII.
1774 CONTENTS is the cell contents. INFO is a plist used as
1775 a communication channel."
1776 ;; Determine column width. When `org-ascii-table-widen-columns'
1777 ;; is nil and some width cookie has set it, use that value.
1778 ;; Otherwise, compute the maximum width among transcoded data of
1779 ;; each cell in the column.
1780 (let ((width (org-ascii--table-cell-width table-cell info
)))
1781 ;; When contents are too large, truncate them.
1782 (unless (or org-ascii-table-widen-columns
1783 (<= (string-width (or contents
"")) width
))
1784 (setq contents
(concat (substring contents
0 (- width
2)) "=>")))
1785 ;; Align contents correctly within the cell.
1786 (let* ((indent-tabs-mode nil
)
1789 (org-ascii--justify-lines
1791 (org-export-table-cell-alignment table-cell info
)))))
1794 (make-string (- width
(string-width (or data
""))) ?\s
))))
1796 (concat (format " %s " contents
)
1797 (when (memq 'right
(org-export-table-cell-borders table-cell info
))
1798 (if (eq (plist-get info
:ascii-charset
) 'utf-8
) "│" "|")))))
1803 (defun org-ascii-table-row (table-row contents info
)
1804 "Transcode a TABLE-ROW element from Org to ASCII.
1805 CONTENTS is the row contents. INFO is a plist used as
1806 a communication channel."
1807 (when (eq (org-element-property :type table-row
) 'standard
)
1810 (lambda (lcorner horiz vert rcorner
)
1814 (org-element-map table-row
'table-cell
1816 (let ((width (org-ascii--table-cell-width cell info
))
1817 (borders (org-export-table-cell-borders cell info
)))
1819 ;; In order to know if CELL starts the row, do
1820 ;; not compare it with the first cell in the
1821 ;; row as there might be a special column.
1822 ;; Instead, compare it with first exportable
1823 ;; cell, obtained with `org-element-map'.
1824 (when (and (memq 'left borders
)
1825 (eq (org-element-map table-row
'table-cell
1829 (make-string (+ 2 width
) (string-to-char horiz
))
1831 ((not (memq 'right borders
)) nil
)
1832 ((eq (car (last (org-element-contents table-row
))) cell
)
1836 (utf8p (eq (plist-get info
:ascii-charset
) 'utf-8
))
1837 (borders (org-export-table-cell-borders
1838 (org-element-map table-row
'table-cell
'identity info t
)
1841 ((and (memq 'top borders
) (or utf8p
(memq 'above borders
)))
1842 (if utf8p
(funcall build-hline
"┍" "━" "┯" "┑")
1843 (funcall build-hline
"+" "-" "+" "+")))
1844 ((memq 'above borders
)
1845 (if utf8p
(funcall build-hline
"├" "─" "┼" "┤")
1846 (funcall build-hline
"+" "-" "+" "+"))))
1847 (when (memq 'left borders
) (if utf8p
"│" "|"))
1849 (when (and (memq 'bottom borders
) (or utf8p
(memq 'below borders
)))
1850 (if utf8p
(funcall build-hline
"┕" "━" "┷" "┙")
1851 (funcall build-hline
"+" "-" "+" "+")))))))
1856 (defun org-ascii-timestamp (timestamp contents info
)
1857 "Transcode a TIMESTAMP object from Org to ASCII.
1858 CONTENTS is nil. INFO is a plist holding contextual information."
1859 (org-ascii-plain-text (org-timestamp-translate timestamp
) info
))
1864 (defun org-ascii-underline (underline contents info
)
1865 "Transcode UNDERLINE from Org to ASCII.
1866 CONTENTS is the text with underline markup. INFO is a plist
1867 holding contextual information."
1868 (format "_%s_" contents
))
1873 (defun org-ascii-verbatim (verbatim contents info
)
1874 "Return a VERBATIM object from Org to ASCII.
1875 CONTENTS is nil. INFO is a plist holding contextual information."
1876 (format org-ascii-verbatim-format
1877 (org-element-property :value verbatim
)))
1882 (defun org-ascii-verse-block (verse-block contents info
)
1883 "Transcode a VERSE-BLOCK element from Org to ASCII.
1884 CONTENTS is verse block contents. INFO is a plist holding
1885 contextual information."
1886 (let ((verse-width (org-ascii--current-text-width verse-block info
)))
1887 (org-ascii--indent-string
1888 (org-ascii--justify-element contents verse-block info
)
1889 org-ascii-quote-margin
)))
1895 (defun org-ascii-filter-headline-blank-lines (headline back-end info
)
1896 "Filter controlling number of blank lines after a headline.
1898 HEADLINE is a string representing a transcoded headline.
1899 BACK-END is symbol specifying back-end used for export. INFO is
1900 plist containing the communication channel.
1902 This function only applies to `ascii' back-end. See
1903 `org-ascii-headline-spacing' for information."
1904 (if (not org-ascii-headline-spacing
) headline
1905 (let ((blanks (make-string (1+ (cdr org-ascii-headline-spacing
)) ?
\n)))
1906 (replace-regexp-in-string "\n\\(?:\n[ \t]*\\)*\\'" blanks headline
))))
1908 (defun org-ascii-filter-paragraph-spacing (tree back-end info
)
1909 "Filter controlling number of blank lines between paragraphs.
1911 TREE is the parse tree. BACK-END is the symbol specifying
1912 back-end used for export. INFO is a plist used as
1913 a communication channel.
1915 See `org-ascii-paragraph-spacing' for information."
1916 (when (wholenump org-ascii-paragraph-spacing
)
1917 (org-element-map tree
'paragraph
1919 (when (eq (org-element-type (org-export-get-next-element p info
))
1921 (org-element-put-property
1922 p
:post-blank org-ascii-paragraph-spacing
)))))
1925 (defun org-ascii-filter-comment-spacing (tree backend info
)
1926 "Filter removing blank lines between comments.
1927 TREE is the parse tree. BACK-END is the symbol specifying
1928 back-end used for export. INFO is a plist used as
1929 a communication channel."
1930 (org-element-map tree
'(comment comment-block
)
1932 (when (memq (org-element-type (org-export-get-next-element c info
))
1933 '(comment comment-block
))
1934 (org-element-put-property c
:post-blank
0))))
1939 ;;; End-user functions
1942 (defun org-ascii-export-as-ascii
1943 (&optional async subtreep visible-only body-only ext-plist
)
1944 "Export current buffer to a text buffer.
1946 If narrowing is active in the current buffer, only export its
1949 If a region is active, export that region.
1951 A non-nil optional argument ASYNC means the process should happen
1952 asynchronously. The resulting buffer should be accessible
1953 through the `org-export-stack' interface.
1955 When optional argument SUBTREEP is non-nil, export the sub-tree
1956 at point, extracting information from the headline properties
1959 When optional argument VISIBLE-ONLY is non-nil, don't export
1960 contents of hidden elements.
1962 When optional argument BODY-ONLY is non-nil, strip title and
1963 table of contents from output.
1965 EXT-PLIST, when provided, is a property list with external
1966 parameters overriding Org default settings, but still inferior to
1967 file-local settings.
1969 Export is done in a buffer named \"*Org ASCII Export*\", which
1970 will be displayed when `org-export-show-temporary-export-buffer'
1973 (org-export-to-buffer 'ascii
"*Org ASCII Export*"
1974 async subtreep visible-only body-only ext-plist
(lambda () (text-mode))))
1977 (defun org-ascii-export-to-ascii
1978 (&optional async subtreep visible-only body-only ext-plist
)
1979 "Export current buffer to a text file.
1981 If narrowing is active in the current buffer, only export its
1984 If a region is active, export that region.
1986 A non-nil optional argument ASYNC means the process should happen
1987 asynchronously. The resulting file should be accessible through
1988 the `org-export-stack' interface.
1990 When optional argument SUBTREEP is non-nil, export the sub-tree
1991 at point, extracting information from the headline properties
1994 When optional argument VISIBLE-ONLY is non-nil, don't export
1995 contents of hidden elements.
1997 When optional argument BODY-ONLY is non-nil, strip title and
1998 table of contents from output.
2000 EXT-PLIST, when provided, is a property list with external
2001 parameters overriding Org default settings, but still inferior to
2002 file-local settings.
2004 Return output file's name."
2006 (let ((file (org-export-output-file-name ".txt" subtreep
)))
2007 (org-export-to-file 'ascii file
2008 async subtreep visible-only body-only ext-plist
)))
2011 (defun org-ascii-publish-to-ascii (plist filename pub-dir
)
2012 "Publish an Org file to ASCII.
2014 FILENAME is the filename of the Org file to be published. PLIST
2015 is the property list for the given project. PUB-DIR is the
2016 publishing directory.
2018 Return output file name."
2020 'ascii filename
".txt" `(:ascii-charset ascii
,@plist
) pub-dir
))
2023 (defun org-ascii-publish-to-latin1 (plist filename pub-dir
)
2024 "Publish an Org file to Latin-1.
2026 FILENAME is the filename of the Org file to be published. PLIST
2027 is the property list for the given project. PUB-DIR is the
2028 publishing directory.
2030 Return output file name."
2032 'ascii filename
".txt" `(:ascii-charset latin1
,@plist
) pub-dir
))
2035 (defun org-ascii-publish-to-utf8 (plist filename pub-dir
)
2036 "Publish an org file to UTF-8.
2038 FILENAME is the filename of the Org file to be published. PLIST
2039 is the property list for the given project. PUB-DIR is the
2040 publishing directory.
2042 Return output file name."
2044 'ascii filename
".txt" `(:ascii-charset utf-8
,@plist
) pub-dir
))
2050 ;; generated-autoload-file: "org-loaddefs.el"
2051 ;; coding: utf-8-emacs
2054 ;;; ox-ascii.el ends here