Allow Org exporter packages to follow a different namespace convention

[kaushalmodi]

Following the examples of in-built Org exporters, for an Org exporter ox-FOO, the namespace prefix used by the variables and functions in the package is org-FOO.

An example from ox-html:

(defconst org-html-html5-elements
  '("article" "aside" "audio" "canvas" "details" "figcaption"
    "figure" "footer" "header" "menu" "meter" "nav" "output"
    "progress" "section" "video")
  "New elements in html5.

For blocks that should contain headlines, use the HTML_CONTAINER
property on the headline itself.")

(defconst org-html-special-string-regexps
  '(("\\\\-" . "­")		; shy
    ("---\\([^-]\\)" . "—\\1")	; mdash
    ("--\\([^-]\\)" . "–\\1")	; ndash
    ("\\.\\.\\." . "…"))		; hellip
  "Regular expressions for special string conversion.")

(defconst org-html-scripts

[Link]

Without this namespace prefix rule exception, I get these errors on doing package-link-current-buffer on my recent ox-hugo submission:

48 issues found:

28:1: error: "org-hugo--draft-state" doesn't start with package's prefix "ox-hugo".
31:1: error: "org-hugo--tags-list" doesn't start with package's prefix "ox-hugo".
38:1: error: "org-hugo--categories-list" doesn't start with package's prefix "ox-hugo".
45:1: error: "org-hugo--subtree-coord" doesn't start with package's prefix "ox-hugo".
50:1: error: "org-hugo--subtree-count" doesn't start with package's prefix "ox-hugo".
54:1: error: "org-hugo-allow-export-after-save" doesn't start with package's prefix "ox-hugo".
68:1: error: "org-hugo-blackfriday-options" doesn't start with package's prefix "ox-hugo".
165:1: error: "org-hugo-blackfriday-extensions" doesn't start with package's prefix "ox-hugo".
314:1: error: "org-hugo--internal-tag-separator" doesn't start with package's prefix "ox-hugo".
328:1: error: "org-hugo-front-matter-format" doesn't start with package's prefix "ox-hugo".
336:1: error: "org-hugo-default-section-directory" doesn't start with package's prefix "ox-hugo".
345:1: error: "org-hugo-footer" doesn't start with package's prefix "ox-hugo".
353:1: error: "org-hugo-use-code-for-kbd" doesn't start with package's prefix "ox-hugo".
359:1: error: "org-hugo-prefer-hyphen-in-tags" doesn't start with package's prefix "ox-hugo".
370:1: error: "org-hugo-allow-spaces-in-tags" doesn't start with package's prefix "ox-hugo".
381:1: error: "org-hugo-langs-no-descr-in-code-fences" doesn't start with package's prefix "ox-hugo".
508:1: error: "org-hugo--plist-value-true-p" doesn't start with package's prefix "ox-hugo".
531:1: error: "org-hugo-kbd-tags-maybe" doesn't start with package's prefix "ox-hugo".
541:1: error: "org-hugo-headline" doesn't start with package's prefix "ox-hugo".
592:1: error: "org-hugo-slug" doesn't start with package's prefix "ox-hugo".
638:1: error: "org-hugo--headline-title" doesn't start with package's prefix "ox-hugo".
660:1: error: "org-hugo-inner-template" doesn't start with package's prefix "ox-hugo".
670:1: error: "org-hugo-keyword" doesn't start with package's prefix "ox-hugo".
686:1: error: "org-hugo-link" doesn't start with package's prefix "ox-hugo".
793:1: error: "org-hugo--attachment-rewrite" doesn't start with package's prefix "ox-hugo".
822:1: error: "org-hugo-src-block" doesn't start with package's prefix "ox-hugo".
856:1: error: "org-hugo-body-filter" doesn't start with package's prefix "ox-hugo".
878:1: error: "org-hugo--quote-string" doesn't start with package's prefix "ox-hugo".
905:1: error: "org-hugo--parse-property-arguments" doesn't start with package's prefix "ox-hugo".
920:1: error: "org-hugo--front-matter-value-booleanize" doesn't start with package's prefix "ox-hugo".
937:1: error: "org-hugo--parse-blackfriday-prop-to-alist" doesn't start with package's prefix "ox-hugo".
966:1: error: "org-hugo--return-valid-blackfriday-extension" doesn't start with package's prefix "ox-hugo".
981:1: error: "org-hugo--parse-menu-prop-to-alist" doesn't start with package's prefix "ox-hugo".
995:1: error: "org-hugo--sanitize-title" doesn't start with package's prefix "ox-hugo".
1011:1: error: "org-hugo--transform-org-tags" doesn't start with package's prefix "ox-hugo".
1071:1: error: "org-hugo--transform-org-tags-str" doesn't start with package's prefix "ox-hugo".
1102:1: error: "org-hugo--get-front-matter" doesn't start with package's prefix "ox-hugo".
1212:1: error: "org-hugo--calc-weight" doesn't start with package's prefix "ox-hugo".
1222:1: error: "org-hugo--gen-front-matter" doesn't start with package's prefix "ox-hugo".
1363:1: error: "org-hugo--selective-property-inheritance" doesn't start with package's prefix "ox-hugo".
1389:1: error: "org-hugo--get-valid-subtree" doesn't start with package's prefix "ox-hugo".
1410:1: error: "org-hugo--get-post-subtree-coordinates" doesn't start with package's prefix "ox-hugo".
1455:1: error: "org-hugo-export-as-md" doesn't start with package's prefix "ox-hugo".
1484:1: error: "org-hugo-export-to-md" doesn't start with package's prefix "ox-hugo".
1526:1: error: "org-hugo-publish-to-md" doesn't start with package's prefix "ox-hugo".
1539:1: error: "org-hugo-export-subtree-to-md" doesn't start with package's prefix "ox-hugo".
1647:1: error: "org-hugo-export-subtree-to-md-after-save" doesn't start with package's prefix "ox-hugo".
1667:1: error: "org-hugo-debug-info" doesn't start with package's prefix "ox-hugo".

[purcell]

Thanks for filing this. I'm not super keen to consider a PR for this, because whatever the example in org itself, I don't think there's any compelling reason why all the symbols in ox-FOO couldn't use the prefix ox-FOO-. Or maybe I'm missing something.

[kaushalmodi]

I'd like to do the right thing too. So I have raised this question on the Org mailing list.

[alphapapa]

From Nicolas's reply:

"ox" stands for "org-export-". This is so to limit file name size. Some systems are very limited (e.g. MS-DOS).

I don't understand that reason. Does anyone run Org on DOS? Org filenames already exceed 8.3, so what systems would break with org-export-hugo.el as opposed to ox-hugo.el?

[kaushalmodi]

I don't understand that reason.

I agree. Though, I like the convention of ox- and ob- prefixes as it's now used in dozens of inbuilt+3rd party exporter and babel packages.

And about why to use the org- prefix for variables and functions, this was Nicolas' reply:

The "org" prefix is mandatory for Org variables and
functions. "ox" would be misleading.

[purcell]

DOS is absolutely not a compelling reason, but if the Org guys want to stick to that, then fine. The wider community doesn't need to. I read the "org" prefix is mandatory for Org variables and functions comment as "this is the prefix we use for everything that's part of org itself," so it needn't apply to third-party work.

[kaushalmodi]

The org- prefix is not just a preference.. it is a functional requirement as I learned a while back.

For instance, in org-export--generate-copy-script, all Org related variables (starting with org- and orgtbl-), default directory, buffer-file-name buffer-file-coding-system and any variable defined as
a BIND keyword, provided their value is `read'-able (e.g., not a hash table) are copied over during export.

	 ;; Copy specific buffer local variables and variables set
	 ;; through BIND keywords.
	 ,@(let ((bound-variables (org-export--list-bound-variables))
		 vars)
	     (dolist (entry (buffer-local-variables (buffer-base-buffer)) vars)
	       (when (consp entry)
		 (let ((var (car entry))
		       (val (cdr entry)))
		   (and (not (memq var org-export-ignored-local-variables))
			(or (memq var
				  '(default-directory
				     buffer-file-name
				     buffer-file-coding-system))
			    (assq var bound-variables)
			    (string-match "^\\(org-\\|orgtbl-\\)"
					  (symbol-name var)))
			;; Skip unreadable values, as they cannot be
			;; sent to external process.
			(or (not val) (ignore-errors (read (format "%S" val))))
			(push `(set (make-local-variable (quote ,var))
				    (quote ,val))
			      vars))))))

That's only one place I know where having a variable with org- prefix holds special powers. Not sure where else in Org this is the case.

[kaushalmodi]

so it needn't apply to third-party work.

I was suggesting this exception for Org exporter (ox-) and Org Babel (ob-) packages, even if they are third party.

[Fuco1]

I also have this problem with smartparens where I use sp- prefix. It is something I'm not really able to change at this point where there is tons of packages depending on smartparens for their own features (at least 4 evil integrations, many many "starter kits" and other refactoring tools).

I use

(defgroup smartparens ()
  "Smartparens minor mode."
  :group 'editing
  :prefix "sp-")

Maybe if this is defined we could pick up the :prefix value and accept that as the prefix?

[purcell]

Maybe if this is defined we could pick up the :prefix value and accept that as the prefix?

The prefix defined like that should still match the overall conventions, though, so I'm not keen to do anything special with it. I don't really want to add a user-defined back door that could be used to work around unconventional prefixes.

Several popular packages have historical prefixes that we shouldn't now encourage: smartparens (sp-), multiple-cursors (mc/ - ugh!), auto-complete (ac-) etc. New elisp authors look to these packages to learn best practices, and I've often had their examples cited to me when I've given review feedback on new packages. I was really happy that yasnippet went to the trouble of switching from yas/ to yas-, but yasnippet- would have been even better. And yes, it's longer in theory, but identifiers like yas-snippet-dirs could then be yasnippet-dirs.

Having reflected on this specific issue, though, I would be happy to have a PR that allowed org-XXX to use the ox-XXX- and ob-XXX- prefixes for its symbols.