New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow Org exporter packages to follow a different namespace convention #89

Open
kaushalmodi opened this Issue Sep 7, 2017 · 9 comments

Comments

Projects
None yet
4 participants
@kaushalmodi
Copy link

kaushalmodi commented Sep 7, 2017

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

This comment has been minimized.

Copy link
Owner

purcell commented Sep 9, 2017

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

This comment has been minimized.

Copy link
Author

kaushalmodi commented Sep 9, 2017

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

@alphapapa

This comment has been minimized.

Copy link
Contributor

alphapapa commented Sep 10, 2017

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

This comment has been minimized.

Copy link
Author

kaushalmodi commented Sep 10, 2017

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

This comment has been minimized.

Copy link
Owner

purcell commented Sep 10, 2017

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

This comment has been minimized.

Copy link
Author

kaushalmodi commented Sep 10, 2017

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

This comment has been minimized.

Copy link
Author

kaushalmodi commented Sep 10, 2017

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

This comment has been minimized.

Copy link

Fuco1 commented Nov 3, 2017

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

This comment has been minimized.

Copy link
Owner

purcell commented Nov 4, 2017

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment