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