ox-publish.el 50.7 KB
Newer Older
Rasmus's avatar
Rasmus committed
1
;;; ox-publish.el --- Publish Related Org Mode Files as a Website -*- lexical-binding: t; -*-
Paul Eggert's avatar
Paul Eggert committed
2
;; Copyright (C) 2006-2020 Free Software Foundation, Inc.
Bastien Guerry's avatar
Bastien Guerry committed
3 4

;; Author: David O'Toole <dto@gnu.org>
5
;; Maintainer: Carsten Dominik <carsten at orgmode dot org>
Bastien Guerry's avatar
Bastien Guerry committed
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
;; Keywords: hypermedia, outlines, wp

;; This file is part of GNU Emacs.
;;
;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
21
;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
Bastien Guerry's avatar
Bastien Guerry committed
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40

;;; Commentary:

;; This program allow configurable publishing of related sets of
;; Org mode files as a complete website.
;;
;; ox-publish.el can do the following:
;;
;; + Publish all one's Org files to a given export back-end
;; + Upload HTML, images, attachments and other files to a web server
;; + Exclude selected private pages from publishing
;; + Publish a clickable sitemap of pages
;; + Manage local timestamps for publishing only changed files
;; + Accept plugin functions to extend range of publishable content
;;
;; Documentation for publishing is in the manual.

;;; Code:

Rasmus's avatar
Rasmus committed
41
(require 'cl-lib)
Bastien Guerry's avatar
Bastien Guerry committed
42 43 44 45 46 47 48 49 50 51 52 53
(require 'format-spec)
(require 'ox)



;;; Variables

;; Here, so you find the variable right before it's used the first time:
(defvar org-publish-cache nil
  "This will cache timestamps and titles for files in publishing projects.
Blocks could hash sha1 values here.")

Rasmus's avatar
Rasmus committed
54 55 56 57 58 59
(defvar org-publish-after-publishing-hook nil
  "Hook run each time a file is published.
Every function in this hook will be called with two arguments:
the name of the original file and the name of the file
produced.")

Rasmus's avatar
Rasmus committed
60
(defgroup org-export-publish nil
Rasmus's avatar
Rasmus committed
61
  "Options for publishing a set of files."
Bastien Guerry's avatar
Bastien Guerry committed
62
  :tag "Org Publishing"
Rasmus's avatar
Rasmus committed
63
  :group 'org-export)
Bastien Guerry's avatar
Bastien Guerry committed
64 65 66

(defcustom org-publish-project-alist nil
  "Association list to control publishing behavior.
Rasmus's avatar
Rasmus committed
67 68
\\<org-mode-map>
Each element of the alist is a publishing project.  The car of
Bastien Guerry's avatar
Bastien Guerry committed
69
each element is a string, uniquely identifying the project.  The
Rasmus's avatar
Rasmus committed
70
cdr of each element is in one of the following forms:
Bastien Guerry's avatar
Bastien Guerry committed
71 72 73 74 75

1. A well-formed property list with an even number of elements,
   alternating keys and values, specifying parameters for the
   publishing process.

76
     (:property value :property value ... )
Bastien Guerry's avatar
Bastien Guerry committed
77 78 79 80

2. A meta-project definition, specifying of a list of
   sub-projects:

81
     (:components (\"project-1\" \"project-2\" ...))
Bastien Guerry's avatar
Bastien Guerry committed
82 83 84 85 86

When the CDR of an element of org-publish-project-alist is in
this second form, the elements of the list after `:components'
are taken to be components of the project, which group together
files requiring different publishing options.  When you publish
Rasmus's avatar
Rasmus committed
87
such a project with `\\[org-publish]', the components all publish.
Bastien Guerry's avatar
Bastien Guerry committed
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103

When a property is given a value in `org-publish-project-alist',
its setting overrides the value of the corresponding user
variable (if any) during publishing.  However, options set within
a file override everything.

Most properties are optional, but some should always be set:

  `:base-directory'

    Directory containing publishing source files.

  `:base-extension'

    Extension (without the dot!) of source files.  This can be
    a regular expression.  If not given, \"org\" will be used as
Rasmus's avatar
Rasmus committed
104 105
    default extension.  If it is `any', include all the files,
    even without extension.
Bastien Guerry's avatar
Bastien Guerry committed
106 107 108 109 110 111

  `:publishing-directory'

    Directory (possibly remote) where output files will be
    published.

Rasmus's avatar
Rasmus committed
112 113 114
If `:recursive' is non-nil files in sub-directories of
`:base-directory' are considered.

Bastien Guerry's avatar
Bastien Guerry committed
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145
The `:exclude' property may be used to prevent certain files from
being published.  Its value may be a string or regexp matching
file names you don't want to be published.

The `:include' property may be used to include extra files.  Its
value may be a list of filenames to include.  The filenames are
considered relative to the base directory.

When both `:include' and `:exclude' properties are given values,
the exclusion step happens first.

One special property controls which back-end function to use for
publishing files in the project.  This can be used to extend the
set of file types publishable by `org-publish', as well as the
set of output formats.

  `:publishing-function'

    Function to publish file.  Each back-end may define its
    own (i.e. `org-latex-publish-to-pdf',
    `org-html-publish-to-html').  May be a list of functions, in
    which case each function in the list is invoked in turn.

Another property allows you to insert code that prepares
a project for publishing.  For example, you could call GNU Make
on a certain makefile, to ensure published files are built up to
date.

  `:preparation-function'

    Function to be called before publishing this project.  This
Rasmus's avatar
Rasmus committed
146 147 148
    may also be a list of functions.  Preparation functions are
    called with the project properties list as their sole
    argument.
Bastien Guerry's avatar
Bastien Guerry committed
149 150 151 152

  `:completion-function'

    Function to be called after publishing this project.  This
Rasmus's avatar
Rasmus committed
153 154 155
    may also be a list of functions.  Completion functions are
    called with the project properties list as their sole
    argument.
Bastien Guerry's avatar
Bastien Guerry committed
156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183

Some properties control details of the Org publishing process,
and are equivalent to the corresponding user variables listed in
the right column.  Back-end specific properties may also be
included.  See the back-end documentation for more information.

  :author                   `user-full-name'
  :creator                  `org-export-creator-string'
  :email                    `user-mail-address'
  :exclude-tags             `org-export-exclude-tags'
  :headline-levels          `org-export-headline-levels'
  :language                 `org-export-default-language'
  :preserve-breaks          `org-export-preserve-breaks'
  :section-numbers          `org-export-with-section-numbers'
  :select-tags              `org-export-select-tags'
  :time-stamp-file          `org-export-time-stamp-file'
  :with-archived-trees      `org-export-with-archived-trees'
  :with-author              `org-export-with-author'
  :with-creator             `org-export-with-creator'
  :with-date                `org-export-with-date'
  :with-drawers             `org-export-with-drawers'
  :with-email               `org-export-with-email'
  :with-emphasize           `org-export-with-emphasize'
  :with-entities            `org-export-with-entities'
  :with-fixed-width         `org-export-with-fixed-width'
  :with-footnotes           `org-export-with-footnotes'
  :with-inlinetasks         `org-export-with-inlinetasks'
  :with-latex               `org-export-with-latex'
Rasmus's avatar
Rasmus committed
184
  :with-planning            `org-export-with-planning'
Bastien Guerry's avatar
Bastien Guerry committed
185
  :with-priority            `org-export-with-priority'
Rasmus's avatar
Rasmus committed
186
  :with-properties          `org-export-with-properties'
Bastien Guerry's avatar
Bastien Guerry committed
187 188 189 190 191 192 193 194 195
  :with-smart-quotes        `org-export-with-smart-quotes'
  :with-special-strings     `org-export-with-special-strings'
  :with-statistics-cookies' `org-export-with-statistics-cookies'
  :with-sub-superscript     `org-export-with-sub-superscripts'
  :with-toc                 `org-export-with-toc'
  :with-tables              `org-export-with-tables'
  :with-tags                `org-export-with-tags'
  :with-tasks               `org-export-with-tasks'
  :with-timestamps          `org-export-with-timestamps'
Rasmus's avatar
Rasmus committed
196
  :with-title               `org-export-with-title'
Bastien Guerry's avatar
Bastien Guerry committed
197 198 199 200 201 202 203 204 205 206 207 208
  :with-todo-keywords       `org-export-with-todo-keywords'

The following properties may be used to control publishing of
a site-map of files or summary page for a given project.

  `:auto-sitemap'

    Whether to publish a site-map during
    `org-publish-current-project' or `org-publish-all'.

  `:sitemap-filename'

Rasmus's avatar
Rasmus committed
209
    Filename for output of site-map.  Defaults to \"sitemap.org\".
Bastien Guerry's avatar
Bastien Guerry committed
210 211 212 213 214 215 216 217 218 219 220 221

  `:sitemap-title'

    Title of site-map page.  Defaults to name of file.

  `:sitemap-style'

    Can be `list' (site-map is just an itemized list of the
    titles of the files involved) or `tree' (the directory
    structure of the source files is reflected in the site-map).
    Defaults to `tree'.

Rasmus's avatar
Rasmus committed
222 223 224 225 226 227
  `:sitemap-format-entry'

    Plugin function used to format entries in the site-map.  It
    is called with three arguments: the file or directory name
    relative to base directory, the site map style and the
    current project.  It has to return a string.
Bastien Guerry's avatar
Bastien Guerry committed
228

Rasmus's avatar
Rasmus committed
229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246
    Defaults to `org-publish-sitemap-default-entry', which turns
    file names into links and use document titles as
    descriptions.  For specific formatting needs, one can use
    `org-publish-find-date', `org-publish-find-title' and
    `org-publish-find-property', to retrieve additional
    information about published documents.

  `:sitemap-function'

    Plugin function to use for generation of site-map.  It is
    called with two arguments: the title of the site-map, as
    a string, and a representation of the files involved in the
    project, as returned by `org-list-to-lisp'.  The latter can
    further be transformed using `org-list-to-generic',
    `org-list-to-subtree' and alike.  It has to return a string.

    Defaults to `org-publish-sitemap-default', which generates
    a plain list of links to all files in the project.
Bastien Guerry's avatar
Bastien Guerry committed
247 248 249 250 251 252

If you create a site-map file, adjust the sorting like this:

  `:sitemap-sort-folders'

    Where folders should appear in the site-map.  Set this to
Rasmus's avatar
Rasmus committed
253 254 255 256 257
    `first' or `last' to display folders first or last,
    respectively.  When set to `ignore' (default), folders are
    ignored altogether.  Any other value will mix files and
    folders.  This variable has no effect when site-map style is
    `tree'.
Bastien Guerry's avatar
Bastien Guerry committed
258 259 260 261

  `:sitemap-sort-files'

    The site map is normally sorted alphabetically.  You can
Paul Eggert's avatar
Paul Eggert committed
262
    change this behavior setting this to `anti-chronologically',
Bastien Guerry's avatar
Bastien Guerry committed
263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318
    `chronologically', or nil.

  `:sitemap-ignore-case'

    Should sorting be case-sensitive?  Default nil.

The following property control the creation of a concept index.

  `:makeindex'

    Create a concept index.  The file containing the index has to
    be called \"theindex.org\".  If it doesn't exist in the
    project, it will be generated.  Contents of the index are
    stored in the file \"theindex.inc\", which can be included in
    \"theindex.org\".

Other properties affecting publication.

  `:body-only'

    Set this to t to publish only the body of the documents."
  :group 'org-export-publish
  :type 'alist)

(defcustom org-publish-use-timestamps-flag t
  "Non-nil means use timestamp checking to publish only changed files.
When nil, do no timestamp checking and always publish all files."
  :group 'org-export-publish
  :type 'boolean)

(defcustom org-publish-timestamp-directory
  (convert-standard-filename "~/.org-timestamps/")
  "Name of directory in which to store publishing timestamps."
  :group 'org-export-publish
  :type 'directory)

(defcustom org-publish-list-skipped-files t
  "Non-nil means show message about files *not* published."
  :group 'org-export-publish
  :type 'boolean)

(defcustom org-publish-sitemap-sort-files 'alphabetically
  "Method to sort files in site-maps.
Possible values are `alphabetically', `chronologically',
`anti-chronologically' and nil.

If `alphabetically', files will be sorted alphabetically.  If
`chronologically', files will be sorted with older modification
time first.  If `anti-chronologically', files will be sorted with
newer modification time first.  nil won't sort files.

You can overwrite this default per project in your
`org-publish-project-alist', using `:sitemap-sort-files'."
  :group 'org-export-publish
  :type 'symbol)

Rasmus's avatar
Rasmus committed
319 320 321 322
(defcustom org-publish-sitemap-sort-folders 'ignore
  "A symbol, denoting if folders are sorted first in site-maps.

Possible values are `first', `last', `ignore' and nil.
Bastien Guerry's avatar
Bastien Guerry committed
323 324
If `first', folders will be sorted before files.
If `last', folders are sorted to the end after the files.
Rasmus's avatar
Rasmus committed
325 326
If `ignore', folders do not appear in the site-map.
Any other value will mix files and folders.
Bastien Guerry's avatar
Bastien Guerry committed
327 328

You can overwrite this default per project in your
Rasmus's avatar
Rasmus committed
329 330 331
`org-publish-project-alist', using `:sitemap-sort-folders'.

This variable is ignored when site-map style is `tree'."
Bastien Guerry's avatar
Bastien Guerry committed
332
  :group 'org-export-publish
Rasmus's avatar
Rasmus committed
333 334 335 336 337 338 339 340
  :type '(choice
	  (const :tag "Folders before files" first)
	  (const :tag "Folders after files" last)
	  (const :tag "No folder in site-map" ignore)
	  (const :tag "Mix folders and files" nil))
  :version "26.1"
  :package-version '(Org . "9.1")
  :safe #'symbolp)
Bastien Guerry's avatar
Bastien Guerry committed
341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360

(defcustom org-publish-sitemap-sort-ignore-case nil
  "Non-nil when site-map sorting should ignore case.

You can overwrite this default per project in your
`org-publish-project-alist', using `:sitemap-ignore-case'."
  :group 'org-export-publish
  :type 'boolean)



;;; Timestamp-related functions

(defun org-publish-timestamp-filename (filename &optional pub-dir pub-func)
  "Return path to timestamp file for filename FILENAME."
  (setq filename (concat filename "::" (or pub-dir "") "::"
			 (format "%s" (or pub-func ""))))
  (concat "X" (if (fboundp 'sha1) (sha1 filename) (md5 filename))))

(defun org-publish-needed-p
Rasmus's avatar
Rasmus committed
361
  (filename &optional pub-dir pub-func _true-pub-dir base-dir)
Bastien Guerry's avatar
Bastien Guerry committed
362 363 364 365 366 367 368 369 370 371 372 373
  "Non-nil if FILENAME should be published in PUB-DIR using PUB-FUNC.
TRUE-PUB-DIR is where the file will truly end up.  Currently we
are not using this - maybe it can eventually be used to check if
the file is present at the target location, and how old it is.
Right now we cannot do this, because we do not know under what
file name the file will be stored - the publishing function can
still decide about that independently."
  (let ((rtn (if (not org-publish-use-timestamps-flag) t
	       (org-publish-cache-file-needs-publishing
		filename pub-dir pub-func base-dir))))
    (if rtn (message "Publishing file %s using `%s'" filename pub-func)
      (when org-publish-list-skipped-files
Rasmus's avatar
Rasmus committed
374
	(message "Skipping unmodified file %s" filename)))
Bastien Guerry's avatar
Bastien Guerry committed
375 376 377
    rtn))

(defun org-publish-update-timestamp
Rasmus's avatar
Rasmus committed
378
  (filename &optional pub-dir pub-func _base-dir)
Bastien Guerry's avatar
Bastien Guerry committed
379 380 381 382 383 384 385 386
  "Update publishing timestamp for file FILENAME.
If there is no timestamp, create one."
  (let ((key (org-publish-timestamp-filename filename pub-dir pub-func))
	(stamp (org-publish-cache-ctime-of-src filename)))
    (org-publish-cache-set key stamp)))

(defun org-publish-remove-all-timestamps ()
  "Remove all files in the timestamp directory."
Rasmus's avatar
Rasmus committed
387
  (let ((dir org-publish-timestamp-directory))
Bastien Guerry's avatar
Bastien Guerry committed
388
    (when (and (file-exists-p dir) (file-directory-p dir))
Rasmus's avatar
Rasmus committed
389
      (mapc #'delete-file (directory-files dir 'full "[^.]\\'"))
Bastien Guerry's avatar
Bastien Guerry committed
390 391 392 393 394 395
      (org-publish-reset-cache))))



;;; Getting project information out of `org-publish-project-alist'

Rasmus's avatar
Rasmus committed
396 397 398 399 400 401 402 403 404
(defun org-publish-property (property project &optional default)
  "Return value PROPERTY, as a symbol, in PROJECT.
DEFAULT is returned when PROPERTY is not actually set in PROJECT
definition."
  (let ((properties (cdr project)))
    (if (plist-member properties property)
	(plist-get properties property)
      default)))

Rasmus's avatar
Rasmus committed
405 406 407
(defun org-publish--expand-file-name (file project)
  "Return full file name for FILE in PROJECT.
When FILE is a relative file name, it is expanded according to
Rasmus's avatar
Rasmus committed
408 409 410
project base directory."
  (if (file-name-absolute-p file) file
    (expand-file-name file (org-publish-property :base-directory project))))
Rasmus's avatar
Rasmus committed
411

Bastien Guerry's avatar
Bastien Guerry committed
412 413 414 415 416 417 418
(defun org-publish-expand-projects (projects-alist)
  "Expand projects in PROJECTS-ALIST.
This splices all the components into the list."
  (let ((rest projects-alist) rtn p components)
    (while (setq p (pop rest))
      (if (setq components (plist-get (cdr p) :components))
	  (setq rest (append
Rasmus's avatar
Rasmus committed
419 420 421 422 423 424
		      (mapcar
		       (lambda (x)
			 (or (assoc x org-publish-project-alist)
			     (user-error "Unknown component %S in project %S"
					 x (car p))))
		       components)
Bastien Guerry's avatar
Bastien Guerry committed
425 426 427 428
		      rest))
	(push p rtn)))
    (nreverse (delete-dups (delq nil rtn)))))

Rasmus's avatar
Rasmus committed
429 430 431 432 433
(defun org-publish-get-base-files (project)
  "Return a list of all files in PROJECT."
  (let* ((base-dir (file-name-as-directory
		    (org-publish-property :base-directory project)))
	 (extension (or (org-publish-property :base-extension project) "org"))
Rasmus's avatar
Rasmus committed
434 435
	 (match (if (eq extension 'any) ""
		  (format "^[^\\.].*\\.\\(%s\\)$" extension)))
Rasmus's avatar
Rasmus committed
436
	 (base-files
Rasmus's avatar
Rasmus committed
437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462
	  (cond ((not (file-exists-p base-dir)) nil)
		((not (org-publish-property :recursive project))
		 (cl-remove-if #'file-directory-p
			       (directory-files base-dir t match t)))
		(t
		 ;; Find all files recursively.  Unlike to
		 ;; `directory-files-recursively', we follow symlinks
		 ;; to other directories.
		 (letrec ((files nil)
			  (walk-tree
			   (lambda (dir depth)
			     (when (> depth 100)
			       (error "Apparent cycle of symbolic links for %S"
				      base-dir))
			     (dolist (f (file-name-all-completions "" dir))
			       (pcase f
				 ((or "./" "../") nil)
				 ((pred directory-name-p)
				  (funcall walk-tree
					   (expand-file-name f dir)
					   (1+ depth)))
				 ((pred (string-match match))
				  (push (expand-file-name f dir) files))
				 (_ nil)))
			     files)))
		   (funcall walk-tree base-dir 0))))))
Rasmus's avatar
Rasmus committed
463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485
    (org-uniquify
     (append
      ;; Files from BASE-DIR.  Apply exclusion filter before adding
      ;; included files.
      (let ((exclude-regexp (org-publish-property :exclude project)))
	(if exclude-regexp
	    (cl-remove-if
	     (lambda (f)
	       ;; Match against relative names, yet BASE-DIR file
	       ;; names are absolute.
	       (string-match exclude-regexp
			     (file-relative-name f base-dir)))
	     base-files)
	  base-files))
      ;; Sitemap file.
      (and (org-publish-property :auto-sitemap project)
	   (list (expand-file-name
		  (or (org-publish-property :sitemap-filename project)
		      "sitemap.org")
		  base-dir)))
      ;; Included files.
      (mapcar (lambda (f) (expand-file-name f base-dir))
	      (org-publish-property :include project))))))
Bastien Guerry's avatar
Bastien Guerry committed
486 487

(defun org-publish-get-project-from-filename (filename &optional up)
Rasmus's avatar
Rasmus committed
488 489 490
  "Return a project that FILENAME belongs to.
When UP is non-nil, return a meta-project (i.e., with a :components part)
publishing FILENAME."
Rasmus's avatar
Rasmus committed
491
  (let* ((filename (expand-file-name filename))
Rasmus's avatar
Rasmus committed
492 493 494 495 496
	 (project
	  (cl-some
	   (lambda (p)
	     ;; Ignore meta-projects.
	     (unless (org-publish-property :components p)
Rasmus's avatar
Rasmus committed
497
	       (let ((base (expand-file-name
Rasmus's avatar
Rasmus committed
498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521
			    (org-publish-property :base-directory p))))
		 (cond
		  ;; Check if FILENAME is explicitly included in one
		  ;; project.
		  ((cl-some (lambda (f) (file-equal-p f filename))
			    (mapcar (lambda (f) (expand-file-name f base))
				    (org-publish-property :include p)))
		   p)
		  ;; Exclude file names matching :exclude property.
		  ((let ((exclude-re (org-publish-property :exclude p)))
		     (and exclude-re
			  (string-match-p exclude-re
					  (file-relative-name filename base))))
		   nil)
		  ;; Check :extension.  Handle special `any'
		  ;; extension.
		  ((let ((extension (org-publish-property :base-extension p)))
		     (not (or (eq extension 'any)
			      (string= (or extension "org")
				       (file-name-extension filename)))))
		   nil)
		  ;; Check if FILENAME belong to project's base
		  ;; directory, or some of its sub-directories
		  ;; if :recursive in non-nil.
Rasmus's avatar
Rasmus committed
522
		  ((member filename (org-publish-get-base-files p)) p)
Rasmus's avatar
Rasmus committed
523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540
		  (t nil)))))
	   org-publish-project-alist)))
    (cond
     ((not project) nil)
     ((not up) project)
     ;; When optional argument UP is non-nil, return the top-most
     ;; meta-project effectively publishing FILENAME.
     (t
      (letrec ((find-parent-project
		(lambda (project)
		  (or (cl-some
		       (lambda (p)
			 (and (member (car project)
				      (org-publish-property :components p))
			      (funcall find-parent-project p)))
		       org-publish-project-alist)
		      project))))
	(funcall find-parent-project project))))))
Bastien Guerry's avatar
Bastien Guerry committed
541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561



;;; Tools for publishing functions in back-ends

(defun org-publish-org-to (backend filename extension plist &optional pub-dir)
  "Publish an Org file to a specified back-end.

BACKEND is a symbol representing the back-end used for
transcoding.  FILENAME is the filename of the Org file to be
published.  EXTENSION is the extension used for the output
string, with the leading dot.  PLIST is the property list for the
given project.

Optional argument PUB-DIR, when non-nil is the publishing
directory.

Return output file name."
  (unless (or (not pub-dir) (file-exists-p pub-dir)) (make-directory pub-dir t))
  ;; Check if a buffer visiting FILENAME is already open.
  (let* ((org-inhibit-startup t)
Rasmus's avatar
Rasmus committed
562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582
	 (visiting (find-buffer-visiting filename))
	 (work-buffer (or visiting (find-file-noselect filename))))
    (unwind-protect
	(with-current-buffer work-buffer
	  (let ((output (org-export-output-file-name extension nil pub-dir)))
	    (org-export-to-file backend output
	      nil nil nil (plist-get plist :body-only)
	      ;; Add `org-publish--store-crossrefs' and
	      ;; `org-publish-collect-index' to final output filters.
	      ;; The latter isn't dependent on `:makeindex', since we
	      ;; want to keep it up-to-date in cache anyway.
	      (org-combine-plists
	       plist
	       `(:crossrefs
		 ,(org-publish-cache-get-file-property
		   ;; Normalize file names in cache.
		   (file-truename filename) :crossrefs nil t)
		 :filter-final-output
		 (org-publish--store-crossrefs
		  org-publish-collect-index
		  ,@(plist-get plist :filter-final-output)))))))
Bastien Guerry's avatar
Bastien Guerry committed
583
      ;; Remove opened buffer in the process.
Rasmus's avatar
Rasmus committed
584
      (unless visiting (kill-buffer work-buffer)))))
Bastien Guerry's avatar
Bastien Guerry committed
585

Rasmus's avatar
Rasmus committed
586
(defun org-publish-attachment (_plist filename pub-dir)
Bastien Guerry's avatar
Bastien Guerry committed
587 588 589 590 591 592 593 594 595
  "Publish a file with no transformation of any kind.

FILENAME is the filename of the Org file to be published.  PLIST
is the property list for the given project.  PUB-DIR is the
publishing directory.

Return output file name."
  (unless (file-directory-p pub-dir)
    (make-directory pub-dir t))
Rasmus's avatar
Rasmus committed
596 597 598 599 600 601
  (let ((output (expand-file-name (file-name-nondirectory filename) pub-dir)))
    (unless (file-equal-p (expand-file-name (file-name-directory filename))
			  (file-name-as-directory (expand-file-name pub-dir)))
      (copy-file filename output t))
    ;; Return file name.
    output))
Bastien Guerry's avatar
Bastien Guerry committed
602 603 604



Rasmus's avatar
Rasmus committed
605
;;; Publishing files, sets of files
Bastien Guerry's avatar
Bastien Guerry committed
606 607 608

(defun org-publish-file (filename &optional project no-cache)
  "Publish file FILENAME from PROJECT.
Rasmus's avatar
Rasmus committed
609 610 611 612
If NO-CACHE is not nil, do not initialize `org-publish-cache'.
This is needed, since this function is used to publish single
files, when entire projects are published (see
`org-publish-projects')."
Bastien Guerry's avatar
Bastien Guerry committed
613 614
  (let* ((project
	  (or project
Rasmus's avatar
Rasmus committed
615 616 617
	      (org-publish-get-project-from-filename filename)
	      (user-error "File %S is not part of any known project"
			  (abbreviate-file-name filename))))
Bastien Guerry's avatar
Bastien Guerry committed
618 619
	 (project-plist (cdr project))
	 (publishing-function
Rasmus's avatar
Rasmus committed
620
	  (pcase (org-publish-property :publishing-function project)
621
	    (`nil (user-error "No publishing function chosen"))
Rasmus's avatar
Rasmus committed
622 623
	    ((and f (pred listp)) f)
	    (f (list f))))
Bastien Guerry's avatar
Bastien Guerry committed
624 625
	 (base-dir
	  (file-name-as-directory
Rasmus's avatar
Rasmus committed
626 627 628 629
	   (or (org-publish-property :base-directory project)
	       (user-error "Project %S does not have :base-directory defined"
			   (car project)))))
	 (pub-base-dir
Bastien Guerry's avatar
Bastien Guerry committed
630
	  (file-name-as-directory
Rasmus's avatar
Rasmus committed
631 632 633 634 635 636 637 638
	   (or (org-publish-property :publishing-directory project)
	       (user-error
		"Project %S does not have :publishing-directory defined"
		(car project)))))
	 (pub-dir
	  (file-name-directory
	   (expand-file-name (file-relative-name filename base-dir)
			     pub-base-dir))))
Bastien Guerry's avatar
Bastien Guerry committed
639 640 641

    (unless no-cache (org-publish-initialize-cache (car project)))

Rasmus's avatar
Rasmus committed
642 643 644 645 646 647 648 649 650 651 652
    ;; Allow chain of publishing functions.
    (dolist (f publishing-function)
      (when (org-publish-needed-p filename pub-base-dir f pub-dir base-dir)
	(let ((output (funcall f project-plist filename pub-dir)))
	  (org-publish-update-timestamp filename pub-base-dir f base-dir)
	  (run-hook-with-args 'org-publish-after-publishing-hook
			      filename
			      output))))
    ;; Make sure to write cache to file after successfully publishing
    ;; a file, so as to minimize impact of a publishing failure.
    (org-publish-write-cache-file)))
653

Bastien Guerry's avatar
Bastien Guerry committed
654 655 656
(defun org-publish-projects (projects)
  "Publish all files belonging to the PROJECTS alist.
If `:auto-sitemap' is set, publish the sitemap too.  If
Rasmus's avatar
Rasmus committed
657 658
`:makeindex' is set, also produce a file \"theindex.org\"."
  (dolist (project (org-publish-expand-projects projects))
Rasmus's avatar
Rasmus committed
659 660 661 662 663
    (let ((plist (cdr project)))
      (let ((fun (org-publish-property :preparation-function project)))
	(cond
	 ((consp fun) (dolist (f fun) (funcall f plist)))
	 ((functionp fun) (funcall fun plist))))
Rasmus's avatar
Rasmus committed
664 665
      ;; Each project uses its own cache file.
      (org-publish-initialize-cache (car project))
Rasmus's avatar
Rasmus committed
666
      (when (org-publish-property :auto-sitemap project)
Rasmus's avatar
Rasmus committed
667
	(let ((sitemap-filename
Rasmus's avatar
Rasmus committed
668 669 670
	       (or (org-publish-property :sitemap-filename project)
		   "sitemap.org")))
	  (org-publish-sitemap project sitemap-filename)))
Rasmus's avatar
Rasmus committed
671 672 673 674
      ;; Publish all files from PROJECT except "theindex.org".  Its
      ;; publishing will be deferred until "theindex.inc" is
      ;; populated.
      (let ((theindex
Bastien Guerry's avatar
Bastien Guerry committed
675
	     (expand-file-name "theindex.org"
Rasmus's avatar
Rasmus committed
676 677
			       (org-publish-property :base-directory project))))
	(dolist (file (org-publish-get-base-files project))
Rasmus's avatar
Rasmus committed
678 679 680 681
	  (unless (file-equal-p file theindex)
	    (org-publish-file file project t)))
	;; Populate "theindex.inc", if needed, and publish
	;; "theindex.org".
Rasmus's avatar
Rasmus committed
682
	(when (org-publish-property :makeindex project)
Rasmus's avatar
Rasmus committed
683
	  (org-publish-index-generate-theindex
Rasmus's avatar
Rasmus committed
684
	   project (org-publish-property :base-directory project))
Rasmus's avatar
Rasmus committed
685
	  (org-publish-file theindex project t)))
Rasmus's avatar
Rasmus committed
686 687 688 689 690
      (let ((fun (org-publish-property :completion-function project)))
	(cond
	 ((consp fun) (dolist (f fun) (funcall f plist)))
	 ((functionp fun) (funcall fun plist)))))
    (org-publish-write-cache-file)))
Bastien Guerry's avatar
Bastien Guerry committed
691

Rasmus's avatar
Rasmus committed
692 693 694 695 696 697 698 699 700 701 702 703 704 705

;;; Site map generation

(defun org-publish--sitemap-files-to-lisp (files project style format-entry)
  "Represent FILES as a parsed plain list.
FILES is the list of files in the site map.  PROJECT is the
current project.  STYLE determines is either `list' or `tree'.
FORMAT-ENTRY is a function called on each file which should
return a string.  Return value is a list as returned by
`org-list-to-lisp'."
  (let ((root (expand-file-name
	       (file-name-as-directory
		(org-publish-property :base-directory project)))))
    (pcase style
706
      (`list
Rasmus's avatar
Rasmus committed
707 708 709 710 711 712 713 714
       (cons 'unordered
	     (mapcar
	      (lambda (f)
		(list (funcall format-entry
			       (file-relative-name f root)
			       style
			       project)))
	      files)))
715
      (`tree
Rasmus's avatar
Rasmus committed
716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750
       (letrec ((files-only (cl-remove-if #'directory-name-p files))
		(directories (cl-remove-if-not #'directory-name-p files))
		(subtree-to-list
		 (lambda (dir)
		   (cons 'unordered
			 (nconc
			  ;; Files in DIR.
			  (mapcar
			   (lambda (f)
			     (list (funcall format-entry
					    (file-relative-name f root)
					    style
					    project)))
			   (cl-remove-if-not
			    (lambda (f) (string= dir (file-name-directory f)))
			    files-only))
			  ;; Direct sub-directories.
			  (mapcar
			   (lambda (sub)
			     (list (funcall format-entry
					    (file-relative-name sub root)
					    style
					    project)
				   (funcall subtree-to-list sub)))
			   (cl-remove-if-not
			    (lambda (f)
			      (string=
			       dir
			       ;; Parent directory.
			       (file-name-directory (directory-file-name f))))
			    directories)))))))
	 (funcall subtree-to-list root)))
      (_ (user-error "Unknown site-map style: `%s'" style)))))

(defun org-publish-sitemap (project &optional sitemap-filename)
Bastien Guerry's avatar
Bastien Guerry committed
751 752
  "Create a sitemap of pages in set defined by PROJECT.
Optionally set the filename of the sitemap with SITEMAP-FILENAME.
753
Default for SITEMAP-FILENAME is `sitemap.org'."
Rasmus's avatar
Rasmus committed
754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780
  (let* ((root (expand-file-name
		(file-name-as-directory
		 (org-publish-property :base-directory project))))
	 (sitemap-filename (concat root (or sitemap-filename "sitemap.org")))
	 (title (or (org-publish-property :sitemap-title project)
		    (concat "Sitemap for project " (car project))))
	 (style (or (org-publish-property :sitemap-style project)
		    'tree))
	 (sitemap-builder (or (org-publish-property :sitemap-function project)
			      #'org-publish-sitemap-default))
	 (format-entry (or (org-publish-property :sitemap-format-entry project)
			   #'org-publish-sitemap-default-entry))
	 (sort-folders
	  (org-publish-property :sitemap-sort-folders project
				org-publish-sitemap-sort-folders))
	 (sort-files
	  (org-publish-property :sitemap-sort-files project
				org-publish-sitemap-sort-files))
	 (ignore-case
	  (org-publish-property :sitemap-ignore-case project
				org-publish-sitemap-sort-ignore-case))
	 (org-file-p (lambda (f) (equal "org" (file-name-extension f))))
	 (sort-predicate
	  (lambda (a b)
	    (let ((retval t))
	      ;; First we sort files:
	      (pcase sort-files
781
		(`alphabetically
Rasmus's avatar
Rasmus committed
782 783 784 785 786 787 788 789 790 791 792 793
		 (let ((A (if (funcall org-file-p a)
			      (concat (file-name-directory a)
				      (org-publish-find-title a project))
			    a))
		       (B (if (funcall org-file-p b)
			      (concat (file-name-directory b)
				      (org-publish-find-title b project))
			    b)))
		   (setq retval
			 (if ignore-case
			     (not (string-lessp (upcase B) (upcase A)))
			   (not (string-lessp B A))))))
794
		((or `anti-chronologically `chronologically)
Rasmus's avatar
Rasmus committed
795
		 (let* ((adate (org-publish-find-date a project))
796
			(bdate (org-publish-find-date b project)))
Rasmus's avatar
Rasmus committed
797
		   (setq retval
798 799 800
			 (not (if (eq sort-files 'chronologically)
				  (time-less-p bdate adate)
				(time-less-p adate bdate))))))
801
		(`nil nil)
Rasmus's avatar
Rasmus committed
802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869
		(_ (user-error "Invalid sort value %s" sort-files)))
	      ;; Directory-wise wins:
	      (when (memq sort-folders '(first last))
		;; a is directory, b not:
		(cond
		 ((and (file-directory-p a) (not (file-directory-p b)))
		  (setq retval (eq sort-folders 'first)))
		 ;; a is not a directory, but b is:
		 ((and (not (file-directory-p a)) (file-directory-p b))
		  (setq retval (eq sort-folders 'last)))))
	      retval))))
    (message "Generating sitemap for %s" title)
    (with-temp-file sitemap-filename
      (insert
       (let ((files (remove sitemap-filename
			    (org-publish-get-base-files project))))
	 ;; Add directories, if applicable.
	 (unless (and (eq style 'list) (eq sort-folders 'ignore))
	   (setq files
		 (nconc (remove root (org-uniquify
				      (mapcar #'file-name-directory files)))
			files)))
	 ;; Eventually sort all entries.
	 (when (or sort-files (not (memq sort-folders 'ignore)))
	   (setq files (sort files sort-predicate)))
	 (funcall sitemap-builder
		  title
		  (org-publish--sitemap-files-to-lisp
		   files project style format-entry)))))))

(defun org-publish-find-property (file property project &optional backend)
  "Find the PROPERTY of FILE in project.

PROPERTY is a keyword referring to an export option, as defined
in `org-export-options-alist' or in export back-ends.  In the
latter case, optional argument BACKEND has to be set to the
back-end where the option is defined, e.g.,

  (org-publish-find-property file :subtitle 'latex)

Return value may be a string or a list, depending on the type of
PROPERTY, i.e. \"behavior\" parameter from `org-export-options-alist'."
  (let ((file (org-publish--expand-file-name file project)))
    (when (and (file-readable-p file) (not (directory-name-p file)))
      (let* ((org-inhibit-startup t)
	     (visiting (find-buffer-visiting file))
	     (buffer (or visiting (find-file-noselect file))))
	(unwind-protect
	    (plist-get (with-current-buffer buffer
			 (if (not visiting) (org-export-get-environment backend)
			   ;; Protect local variables in open buffers.
			   (org-export-with-buffer-copy
			    (org-export-get-environment backend))))
		       property)
	  (unless visiting (kill-buffer buffer)))))))

(defun org-publish-find-title (file project)
  "Find the title of FILE in PROJECT."
  (let ((file (org-publish--expand-file-name file project)))
    (or (org-publish-cache-get-file-property file :title nil t)
	(let* ((parsed-title (org-publish-find-property file :title project))
	       (title
		(if parsed-title
		    ;; Remove property so that the return value is
		    ;; cache-able (i.e., it can be `read' back).
		    (org-no-properties
		     (org-element-interpret-data parsed-title))
		  (file-name-nondirectory (file-name-sans-extension file)))))
Bastien's avatar
Bastien committed
870
	  (org-publish-cache-set-file-property file :title title)))))
Rasmus's avatar
Rasmus committed
871 872 873

(defun org-publish-find-date (file project)
  "Find the date of FILE in PROJECT.
Bastien Guerry's avatar
Bastien Guerry committed
874 875 876 877
This function assumes FILE is either a directory or an Org file.
If FILE is an Org file and provides a DATE keyword use it.  In
any other case use the file system's modification time.  Return
time in `current-time' format."
Rasmus's avatar
Rasmus committed
878
  (let ((file (org-publish--expand-file-name file project)))
Bastien's avatar
Bastien committed
879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895
    (or (org-publish-cache-get-file-property file :date nil t)
	(org-publish-cache-set-file-property
	 file :date
	 (if (file-directory-p file)
	     (file-attribute-modification-time (file-attributes file))
	   (let ((date (org-publish-find-property file :date project)))
	     ;; DATE is a secondary string.  If it contains
	     ;; a time-stamp, convert it to internal format.
	     ;; Otherwise, use FILE modification time.
	     (cond ((let ((ts (and (consp date) (assq 'timestamp date))))
		      (and ts
			   (let ((value (org-element-interpret-data ts)))
			     (and (org-string-nw-p value)
				  (org-time-string-to-time value))))))
		   ((file-exists-p file)
		    (file-attribute-modification-time (file-attributes file)))
		   (t (error "No such file: \"%s\"" file)))))))))
Rasmus's avatar
Rasmus committed
896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911

(defun org-publish-sitemap-default-entry (entry style project)
  "Default format for site map ENTRY, as a string.
ENTRY is a file name.  STYLE is the style of the sitemap.
PROJECT is the current project."
  (cond ((not (directory-name-p entry))
	 (format "[[file:%s][%s]]"
		 entry
		 (org-publish-find-title entry project)))
	((eq style 'tree)
	 ;; Return only last subdir.
	 (file-name-nondirectory (directory-file-name entry)))
	(t entry)))

(defun org-publish-sitemap-default (title list)
  "Default site map, as a string.
912
TITLE is the title of the site map.  LIST is an internal
Rasmus's avatar
Rasmus committed
913 914 915 916
representation for the files to include, as returned by
`org-list-to-lisp'.  PROJECT is the current project."
  (concat "#+TITLE: " title "\n\n"
	  (org-list-to-org list)))
Bastien Guerry's avatar
Bastien Guerry committed
917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934


;;; Interactive publishing functions

;;;###autoload
(defalias 'org-publish-project 'org-publish)

;;;###autoload
(defun org-publish (project &optional force async)
  "Publish PROJECT.

PROJECT is either a project name, as a string, or a project
alist (see `org-publish-project-alist' variable).

When optional argument FORCE is non-nil, force publishing all
files in PROJECT.  With a non-nil optional argument ASYNC,
publishing will be done asynchronously, in another process."
  (interactive
Rasmus's avatar
Rasmus committed
935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956
   (list (assoc (completing-read "Publish project: "
				 org-publish-project-alist nil t)
		org-publish-project-alist)
	 current-prefix-arg))
  (let ((project (if (not (stringp project)) project
		   ;; If this function is called in batch mode,
		   ;; PROJECT is still a string here.
		   (assoc project org-publish-project-alist))))
    (cond
     ((not project))
     (async
      (org-export-async-start (lambda (_) nil)
	`(let ((org-publish-use-timestamps-flag
		,(and (not force) org-publish-use-timestamps-flag)))
	   ;; Expand components right now as external process may not
	   ;; be aware of complete `org-publish-project-alist'.
	   (org-publish-projects
	    ',(org-publish-expand-projects (list project))))))
     (t (save-window-excursion
	  (let ((org-publish-use-timestamps-flag
		 (and (not force) org-publish-use-timestamps-flag)))
	    (org-publish-projects (list project))))))))
Bastien Guerry's avatar
Bastien Guerry committed
957 958 959 960 961 962 963 964 965 966

;;;###autoload
(defun org-publish-all (&optional force async)
  "Publish all projects.
With prefix argument FORCE, remove all files in the timestamp
directory and force publishing all projects.  With a non-nil
optional argument ASYNC, publishing will be done asynchronously,
in another process."
  (interactive "P")
  (if async
Rasmus's avatar
Rasmus committed
967
      (org-export-async-start (lambda (_) nil)
Bastien Guerry's avatar
Bastien Guerry committed
968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988
	`(progn
	   (when ',force (org-publish-remove-all-timestamps))
	   (let ((org-publish-use-timestamps-flag
		  (if ',force nil ,org-publish-use-timestamps-flag)))
	     (org-publish-projects ',org-publish-project-alist))))
    (when force (org-publish-remove-all-timestamps))
    (save-window-excursion
      (let ((org-publish-use-timestamps-flag
	     (if force nil org-publish-use-timestamps-flag)))
	(org-publish-projects org-publish-project-alist)))))


;;;###autoload
(defun org-publish-current-file (&optional force async)
  "Publish the current file.
With prefix argument FORCE, force publish the file.  When
optional argument ASYNC is non-nil, publishing will be done
asynchronously, in another process."
  (interactive "P")
  (let ((file (buffer-file-name (buffer-base-buffer))))
    (if async
Rasmus's avatar
Rasmus committed
989
	(org-export-async-start (lambda (_) nil)
Bastien Guerry's avatar
Bastien Guerry committed
990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014
	  `(let ((org-publish-use-timestamps-flag
		  (if ',force nil ,org-publish-use-timestamps-flag)))
	     (org-publish-file ,file)))
      (save-window-excursion
	(let ((org-publish-use-timestamps-flag
	       (if force nil org-publish-use-timestamps-flag)))
	  (org-publish-file file))))))

;;;###autoload
(defun org-publish-current-project (&optional force async)
  "Publish the project associated with the current file.
With a prefix argument, force publishing of all files in
the project."
  (interactive "P")
  (save-window-excursion
    (let ((project (org-publish-get-project-from-filename
		    (buffer-file-name (buffer-base-buffer)) 'up)))
      (if project (org-publish project force async)
	(error "File %s is not part of any known project"
	       (buffer-file-name (buffer-base-buffer)))))))



;;; Index generation

Rasmus's avatar
Rasmus committed
1015
(defun org-publish-collect-index (output _backend info)
Bastien Guerry's avatar
Bastien Guerry committed
1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029
  "Update index for a file in cache.

OUTPUT is the output from transcoding current file.  BACKEND is
the back-end that was used for transcoding.  INFO is a plist
containing publishing and export options.

The index relative to current file is stored as an alist.  An
association has the following shape: (TERM FILE-NAME PARENT),
where TERM is the indexed term, as a string, FILE-NAME is the
original full path of the file where the term in encountered, and
PARENT is a reference to the headline, if any, containing the
original index keyword.  When non-nil, this reference is a cons
cell.  Its CAR is a symbol among `id', `custom-id' and `name' and
its CDR is a string."
Rasmus's avatar
Rasmus committed
1030
  (let ((file (file-truename (plist-get info :input-file))))
Bastien Guerry's avatar
Bastien Guerry committed
1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058
    (org-publish-cache-set-file-property
     file :index
     (delete-dups
      (org-element-map (plist-get info :parse-tree) 'keyword
	(lambda (k)
	  (when (equal (org-element-property :key k) "INDEX")
	    (let ((parent (org-export-get-parent-headline k)))
	      (list (org-element-property :value k)
		    file
		    (cond
		     ((not parent) nil)
		     ((let ((id (org-element-property :ID parent)))
			(and id (cons 'id id))))
		     ((let ((id (org-element-property :CUSTOM_ID parent)))
			(and id (cons 'custom-id id))))
		     (t (cons 'name
			      ;; Remove statistics cookie.
			      (replace-regexp-in-string
			       "\\[[0-9]+%\\]\\|\\[[0-9]+/[0-9]+\\]" ""
			       (org-element-property :raw-value parent)))))))))
	info))))
  ;; Return output unchanged.
  output)

(defun org-publish-index-generate-theindex (project directory)
  "Retrieve full index from cache and build \"theindex.org\".
PROJECT is the project the index relates to.  DIRECTORY is the
publishing directory."
Rasmus's avatar
Rasmus committed
1059
  (let ((all-files (org-publish-get-base-files project))
Bastien Guerry's avatar
Bastien Guerry committed
1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086
	full-index)
    ;; Compile full index and sort it alphabetically.
    (dolist (file all-files
		  (setq full-index
			(sort (nreverse full-index)
			      (lambda (a b) (string< (downcase (car a))
						(downcase (car b)))))))
      (let ((index (org-publish-cache-get-file-property file :index)))
	(dolist (term index)
	  (unless (member term full-index) (push term full-index)))))
    ;; Write "theindex.inc" in DIRECTORY.
    (with-temp-file (expand-file-name "theindex.inc" directory)
      (let ((current-letter nil) (last-entry nil))
	(dolist (idx full-index)
	  (let* ((entry (org-split-string (car idx) "!"))
		 (letter (upcase (substring (car entry) 0 1)))
		 ;; Transform file into a path relative to publishing
		 ;; directory.
		 (file (file-relative-name
			(nth 1 idx)
			(plist-get (cdr project) :base-directory))))
	    ;; Check if another letter has to be inserted.
	    (unless (string= letter current-letter)
	      (insert (format "* %s\n" letter)))
	    ;; Compute the first difference between last entry and
	    ;; current one: it tells the level at which new items
	    ;; should be added.
Rasmus's avatar
Rasmus committed
1087 1088 1089 1090 1091
	    (let* ((rank
		    (if (equal entry last-entry) (1- (length entry))
		      (cl-loop for n from 0 to (length entry)
			       unless (equal (nth n entry) (nth n last-entry))
			       return n)))
Bastien Guerry's avatar
Bastien Guerry committed
1092 1093 1094 1095 1096 1097 1098
		   (len (length (nthcdr rank entry))))
	      ;; For each term after the first difference, create
	      ;; a new sub-list with the term as body.  Moreover,
	      ;; linkify the last term.
	      (dotimes (n len)
		(insert
		 (concat
Rasmus's avatar
Rasmus committed
1099
		  (make-string (* (+ rank n) 2) ?\s) "  - "
Bastien Guerry's avatar
Bastien Guerry committed
1100 1101 1102 1103 1104 1105
		  (if (not (= (1- len) n)) (nth (+ rank n) entry)
		    ;; Last term: Link it to TARGET, if possible.
		    (let ((target (nth 2 idx)))
		      (format
		       "[[%s][%s]]"
		       ;; Destination.
Rasmus's avatar
Rasmus committed
1106
		       (pcase (car target)
1107 1108 1109
			 (`nil (format "file:%s" file))
			 (`id (format "id:%s" (cdr target)))
			 (`custom-id (format "file:%s::#%s" file (cdr target)))
Rasmus's avatar
Rasmus committed
1110
			 (_ (format "file:%s::*%s" file (cdr target))))
Bastien Guerry's avatar
Bastien Guerry committed
1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128
		       ;; Description.
		       (car (last entry)))))
		  "\n"))))
	    (setq current-letter letter last-entry entry))))
      ;; Create "theindex.org", if it doesn't exist yet, and provide
      ;; a default index file.
      (let ((index.org (expand-file-name "theindex.org" directory)))
	(unless (file-exists-p index.org)
	  (with-temp-file index.org
	    (insert "#+TITLE: Index\n\n#+INCLUDE: \"theindex.inc\"\n\n")))))))



;;; External Fuzzy Links Resolution
;;
;; This part implements tools to resolve [[file.org::*Some headline]]
;; links, where "file.org" belongs to the current project.

Rasmus's avatar
Rasmus committed
1129 1130 1131
(defun org-publish--store-crossrefs (output _backend info)
  "Store cross-references for current published file.

Paul Eggert's avatar
Paul Eggert committed
1132
OUTPUT is the produced output, as a string.  BACKEND is the export
Rasmus's avatar
Rasmus committed
1133 1134 1135 1136 1137
back-end used, as a symbol.  INFO is the final export state, as
a plist.

This function is meant to be used as a final output filter.  See
`org-publish-org-to'."
Bastien Guerry's avatar
Bastien Guerry committed
1138
  (org-publish-cache-set-file-property
Rasmus's avatar
Rasmus committed
1139 1140 1141 1142 1143 1144 1145 1146
   (file-truename (plist-get info :input-file))
   :crossrefs
   ;; Update `:crossrefs' so as to remove unused references and search
   ;; cells.  Actually used references are extracted from
   ;; `:internal-references', with references as strings removed.  See
   ;; `org-export-get-reference' for details.
   (cl-remove-if (lambda (pair) (stringp (car pair)))
		 (plist-get info :internal-references)))
Bastien Guerry's avatar
Bastien Guerry committed
1147 1148 1149
  ;; Return output unchanged.
  output)

Bastien's avatar
Bastien committed
1150
(defun org-publish-resolve-external-link (search file &optional prefer-custom)
Rasmus's avatar
Rasmus committed
1151 1152 1153 1154 1155 1156 1157
  "Return reference for element matching string SEARCH in FILE.

Return value is an internal reference, as a string.

This function allows resolving external links with a search
option, e.g.,

Bastien's avatar
Bastien committed
1158 1159 1160 1161 1162 1163
  [[file:file.org::*heading][description]]
  [[file:file.org::#custom-id][description]]
  [[file:file.org::fuzzy][description]]

When PREFER-CUSTOM is non-nil, and SEARCH targets a headline in
FILE, return its custom ID, if any.
Rasmus's avatar
Rasmus committed
1164 1165 1166

It only makes sense to use this if export back-end builds
references with `org-export-get-reference'."
Bastien's avatar
Bastien committed
1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186
  (cond
   ((and prefer-custom
	 (if (string-prefix-p "#" search)
	     (substring search 1)
	   (with-current-buffer (find-file-noselect file)
	     (org-with-point-at 1
	       (let ((org-link-search-must-match-exact-headline t))
		 (condition-case err
		     (org-link-search search nil t)
		   (error
		    (signal 'org-link-broken (cdr err)))))
	       (and (org-at-heading-p)
		    (org-string-nw-p (org-entry-get (point) "CUSTOM_ID"))))))))
   ((not org-publish-cache)
    (progn
      (message "Reference %S in file %S cannot be resolved without publishing"
	       search
	       file)
      "MissingReference"))
   (t
Rasmus's avatar
Rasmus committed
1187 1188 1189
    (let* ((filename (file-truename file))
	   (crossrefs
	    (org-publish-cache-get-file-property filename :crossrefs nil t))
Bastien's avatar
Bastien committed
1190
	   (cells (org-export-string-to-search-cell search)))
Rasmus's avatar
Rasmus committed
1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202
      (or
       ;; Look for reference associated to search cells triggered by
       ;; LINK.  It can match when targeted file has been published
       ;; already.
       (let ((known (cdr (cl-some (lambda (c) (assoc c crossrefs)) cells))))
	 (and known (org-export-format-reference known)))
       ;; Search cell is unknown so far.  Generate a new internal
       ;; reference that will be used when the targeted file will be
       ;; published.
       (let ((new (org-export-new-reference crossrefs)))
	 (dolist (cell cells) (push (cons cell new) crossrefs))
	 (org-publish-cache-set-file-property filename :crossrefs crossrefs)
Bastien's avatar
Bastien committed
1203
	 (org-export-format-reference new)))))))
Bastien Guerry's avatar
Bastien Guerry committed
1204

Rasmus's avatar
Rasmus committed
1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215
(defun org-publish-file-relative-name (filename info)
  "Convert FILENAME to be relative to current project's base directory.
INFO is the plist containing the current export state.  The
function does not change relative file names."
  (let ((base (plist-get info :base-directory)))
    (if (and base
	     (file-name-absolute-p filename)
	     (file-in-directory-p filename base))
	(file-relative-name filename base)
      filename)))

Bastien Guerry's avatar
Bastien Guerry committed
1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230


;;; Caching functions

(defun org-publish-write-cache-file (&optional free-cache)
  "Write `org-publish-cache' to file.
If FREE-CACHE, empty the cache."
  (unless org-publish-cache
    (error "`org-publish-write-cache-file' called, but no cache present"))

  (let ((cache-file (org-publish-cache-get ":cache-file:")))
    (unless cache-file
      (error "Cannot find cache-file name in `org-publish-write-cache-file'"))
    (with-temp-file cache-file
      (let (print-level print-length)
Rasmus's avatar
Rasmus committed
1231 1232
	(insert "(setq org-publish-cache \
\(make-hash-table :test 'equal :weakness nil :size 100))\n")
Bastien Guerry's avatar
Bastien Guerry committed
1233 1234
	(maphash (lambda (k v)
		   (insert
Rasmus's avatar
Rasmus committed
1235 1236
		    (format "(puthash %S %s%S org-publish-cache)\n"
			    k (if (or (listp v) (symbolp v)) "'" "") v)))
Bastien Guerry's avatar
Bastien Guerry committed
1237 1238 1239 1240 1241 1242 1243
		 org-publish-cache)))
    (when free-cache (org-publish-reset-cache))))

(defun org-publish-initialize-cache (project-name)
  "Initialize the projects cache if not initialized yet and return it."

  (unless project-name
Rasmus's avatar
Rasmus committed
1244 1245
    (error "Cannot initialize `org-publish-cache' without projects name in \
`org-publish-initialize-cache'"))
Bastien Guerry's avatar
Bastien Guerry committed
1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278

  (unless (file-exists-p org-publish-timestamp-directory)
    (make-directory org-publish-timestamp-directory t))
  (unless (file-directory-p org-publish-timestamp-directory)
    (error "Org publish timestamp: %s is not a directory"
	   org-publish-timestamp-directory))

  (unless (and org-publish-cache
	       (string= (org-publish-cache-get ":project:") project-name))
    (let* ((cache-file
	    (concat
	     (expand-file-name org-publish-timestamp-directory)
	     project-name ".cache"))
	   (cexists (file-exists-p cache-file)))

      (when org-publish-cache (org-publish-reset-cache))

      (if cexists (load-file cache-file)
	(setq org-publish-cache
	      (make-hash-table :test 'equal :weakness nil :size 100))
	(org-publish-cache-set ":project:" project-name)
	(org-publish-cache-set ":cache-file:" cache-file))
      (unless cexists (org-publish-write-cache-file nil))))
  org-publish-cache)

(defun org-publish-reset-cache ()
  "Empty org-publish-cache and reset it nil."
  (message "%s" "Resetting org-publish-cache")
  (when (hash-table-p org-publish-cache)
    (clrhash org-publish-cache))
  (setq org-publish-cache nil))

(defun org-publish-cache-file-needs-publishing
Rasmus's avatar
Rasmus committed
1279
    (filename &optional pub-dir pub-func _base-dir)
Bastien Guerry's avatar
Bastien Guerry committed
1280 1281 1282 1283 1284 1285 1286
  "Check the timestamp of the last publishing of FILENAME.
Return non-nil if the file needs publishing.  Also check if
any included files have been more recently published, so that
the file including them will be republished as well."
  (unless org-publish-cache
    (error
     "`org-publish-cache-file-needs-publishing' called, but no cache present"))
Rasmus's avatar
Rasmus committed
1287
  (let* ((key (org-publish-timestamp-filename filename pub-dir pub-func))
Bastien Guerry's avatar
Bastien Guerry committed
1288 1289
	 (pstamp (org-publish-cache-get key))
	 (org-inhibit-startup t)
Rasmus's avatar
Rasmus committed
1290
	 included-files-ctime)
Bastien Guerry's avatar
Bastien Guerry committed
1291
    (when (equal (file-name-extension filename) "org")
Rasmus's avatar
Rasmus committed
1292 1293 1294 1295 1296 1297 1298
      (let ((visiting (find-buffer-visiting filename))
	    (buf (find-file-noselect filename))
	    (case-fold-search t))
	(unwind-protect
	    (with-current-buffer buf
	      (goto-char (point-min))
	      (while (re-search-forward "^[ \t]*#\\+INCLUDE:" nil t)
Rasmus's avatar
Rasmus committed
1299 1300 1301 1302 1303
		(let ((element (org-element-at-point)))
		  (when (eq 'keyword (org-element-type element))
		    (let* ((value (org-element-property :value element))
			   (filename
			    (and (string-match "\\`\\(\".+?\"\\|\\S-+\\)" value)
Bastien's avatar
Bastien committed
1304 1305
				 (let ((m (org-strip-quotes
					   (match-string 1 value))))
Rasmus's avatar
Rasmus committed
1306 1307 1308 1309 1310 1311 1312 1313
				   ;; Ignore search suffix.
				   (if (string-match "::.*?\\'" m)
				       (substring m 0 (match-beginning 0))
				     m)))))
		      (when filename
			(push (org-publish-cache-ctime-of-src
			       (expand-file-name filename))
			      included-files-ctime)))))))
Rasmus's avatar
Rasmus committed
1314 1315 1316
	  (unless visiting (kill-buffer buf)))))
    (or (null pstamp)
	(let ((ctime (org-publish-cache-ctime-of-src filename)))
Bastien's avatar
Bastien committed
1317 1318 1319
	  (or (time-less-p pstamp ctime)
	      (cl-some (lambda (ct) (time-less-p ctime ct))
		       included-files-ctime))))))
Bastien Guerry's avatar
Bastien Guerry committed
1320 1321 1322 1323 1324 1325 1326

(defun org-publish-cache-set-file-property
  (filename property value &optional project-name)
  "Set the VALUE for a PROPERTY of file FILENAME in publishing cache to VALUE.
Use cache file of PROJECT-NAME.  If the entry does not exist, it
will be created.  Return VALUE."
  ;; Evtl. load the requested cache file:
Bastien's avatar
Bastien committed
1327
  (when project-name (org-publish-initialize-cache project-name))
Bastien Guerry's avatar
Bastien Guerry committed
1328 1329 1330 1331 1332 1333
  (let ((pl (org-publish-cache-get filename)))
    (if pl (progn (plist-put pl property value) value)
      (org-publish-cache-get-file-property
       filename property value nil project-name))))

(defun org-publish-cache-get-file-property
Rasmus's avatar
Rasmus committed
1334
    (filename property &optional default no-create project-name)
Bastien Guerry's avatar
Bastien Guerry committed
1335
  "Return the value for a PROPERTY of file FILENAME in publishing cache.
Rasmus's avatar
Rasmus committed
1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346
Use cache file of PROJECT-NAME.  Return the value of that PROPERTY,
or DEFAULT, if the value does not yet exist.  Create the entry,
if necessary, unless NO-CREATE is non-nil."
  (when project-name (org-publish-initialize-cache project-name))
  (let ((properties (org-publish-cache-get filename)))
    (cond ((null properties)
	   (unless no-create
	     (org-publish-cache-set filename (list property default)))
	   default)
	  ((plist-member properties property) (plist-get properties property))
	  (t default))))
Bastien Guerry's avatar
Bastien Guerry committed
1347 1348 1349

(defun org-publish-cache-get (key)
  "Return the value stored in `org-publish-cache' for key KEY.
Rasmus's avatar
Rasmus committed
1350 1351
Return nil, if no value or nil is found.  Raise an error if the
cache does not exist."
Bastien Guerry's avatar
Bastien Guerry committed
1352 1353 1354 1355 1356 1357
  (unless org-publish-cache
    (error "`org-publish-cache-get' called, but no cache present"))
  (gethash key org-publish-cache))

(defun org-publish-cache-set (key value)
  "Store KEY VALUE pair in `org-publish-cache'.
Rasmus's avatar
Rasmus committed
1358 1359
Returns value on success, else nil.  Raise an error if the cache
does not exist."
Bastien Guerry's avatar
Bastien Guerry committed
1360 1361 1362 1363 1364 1365 1366 1367 1368
  (unless org-publish-cache
    (error "`org-publish-cache-set' called, but no cache present"))
  (puthash key value org-publish-cache))

(defun org-publish-cache-ctime-of-src (file)
  "Get the ctime of FILE as an integer."
  (let ((attr (file-attributes
	       (expand-file-name (or (file-symlink-p file) file)
				 (file-name-directory file)))))
Bastien's avatar
Bastien committed
1369 1370
    (if attr (file-attribute-modification-time attr)
      (error "No such file: %S" file))))
Bastien Guerry's avatar
Bastien Guerry committed
1371 1372 1373 1374 1375 1376 1377 1378 1379


(provide 'ox-publish)

;; Local variables:
;; generated-autoload-file: "org-loaddefs.el"
;; End:

;;; ox-publish.el ends here