Function: hywiki-add-page

hywiki-add-page is an interactive and byte-compiled function defined in hywiki.el.

Signature

(hywiki-add-page PAGE-NAME &optional FORCE-FLAG DEBUG-FLAG)

Documentation

Add a new or return any existing HyWiki page path for PAGE-NAME.

Returned format is: '(page . "<absolute-page-file-path>") or nil when none. <absolute-page-file-path> follows the path formatting conventions from the documentation string for hpath:find. PAGE-NAME must be the HyWikiWord reference that can link to the page (no pathname directory nor file extension).

With optional FORCE-FLAG prefix arg non-nil, force an update to the page's modification time. If PAGE-NAME is invalid, trigger a user-error if called interactively or return nil if not.

By default, create any non-existent page. When not in batch or ert test results mode, if this is the first HyWiki page in hywiki-directory, prompt to create it.

After successfully adding a page, run hywiki-add-page-hook.

Use hywiki-get-referent to determine whether a HyWiki page exists.

Key Bindings

Source Code

;; Defined in ~/.emacs.d/elpa/hyperbole-20260822.1645/hywiki.el
(defun hywiki-add-page (page-name &optional force-flag debug-flag)
  "Add a new or return any existing HyWiki page path for PAGE-NAME.
Returned format is: \\='(page . \"<absolute-page-file-path>\") or nil when
none.  <absolute-page-file-path> follows the path formatting conventions
from the documentation string for `hpath:find'.  PAGE-NAME must be the
HyWikiWord reference that can link to the page (no pathname directory nor
file extension).

With optional FORCE-FLAG prefix arg non-nil, force an update to
the page's modification time.  If PAGE-NAME is invalid, trigger a
`user-error' if called interactively or return nil if not.

By default, create any non-existent page.  When not in batch or
ert test results mode, if this is the first HyWiki page in
`hywiki-directory', prompt to create it.

After successfully adding a page, run `hywiki-add-page-hook'.

Use `hywiki-get-referent' to determine whether a HyWiki page exists."
  (interactive (list (or (hywiki-word-at)
			 (hywiki-page-read-new "Add/Edit HyWiki page: "))
		     current-prefix-arg))
  (if (hywiki-word-is-p page-name)
      (when (or noninteractive
		(hyperb:stack-frame '(ert-run-test))
		(not (hash-empty-p (hywiki-get-referent-hasht)))
		(y-or-n-p (concat "Create new HyWiki page `" page-name "'? ")))
	(let* ((case-fold-search nil)
               (page-name-with-suffix page-name)
	       ;; Remove any #section suffix in PAGE-NAME.
	       (page-name-singular (hywiki-get-singular-wikiword page-name))
               (page-file (hywiki-get-page-file page-name-singular))
	       (page-file-readable (file-readable-p page-file))
	       (referent-hasht (hywiki-get-referent-hasht))
	       (page-in-hasht (hywiki-page-exists-p page-name-singular))
               referent)
	  (unless page-file-readable
	    (if (file-writable-p page-file)
		(write-region "" nil page-file nil 0)
	      (user-error "(hywiki-add-page): No permission to write HyWikiWord page file:\n  \"%s\"" page-name-singular)))
	  (if (or force-flag (not page-in-hasht))
	      (progn
		(hash-add (cons 'page (file-name-nondirectory page-file))
			  page-name-singular referent-hasht)
		(setq hywiki--any-wikiword-regexp-list nil)
		(when (called-interactively-p 'interactive)
		  (message "Added HyWikiWord page: \"%s\"" page-file)))
	    (when (called-interactively-p 'interactive)
	      (message "HyWikiWord page exists: \"%s\"" page-file)))
	  (unless (or (hyperb:stack-frame '(hywiki-maybe-highlight-wikiwords-in-frame))
		      (and (not force-flag) page-file-readable page-in-hasht))
	    (hywiki-cache-save)
	    (hywiki-maybe-highlight-wikiwords-in-frame t))
	  (run-hooks 'hywiki-add-page-hook)
	  (when page-file
            ;; Ensure the referent returned has any wikiword suffix and the
            ;; path part of the referent is absolute
            (setq referent (hywiki-get-referent page-name-with-suffix t))
            (or referent (when debug-flag (debug))))))
    (when (called-interactively-p 'interactive)
      (user-error "(hywiki-add-page): Invalid HyWikiWord: '%s'; must be capitalized, all alpha" page-name))))