From 88ae5c8c65a4f0d401b450338cf8bb36c47684fc Mon Sep 17 00:00:00 2001 From: Kaushal Modi Date: Thu, 7 Apr 2022 21:48:15 -0400 Subject: [PATCH] feat!: `EXPORT_HUGO_SECTION_FRAG` replaces `EXPORT_HUGO_SECTION*` This commit is marked as a "feature" because now you can view/edit Hugo section fragments easily in Org Column view. If you are an ox-hugo user affected by this breaking change, simply replace all instances of "EXPORT_HUGO_SECTION*" with "EXPORT_HUGO_SECTION_FRAG" in your Org files. See https://ox-hugo.scripter.co/doc/deprecation-notices/#export-hugo-section-frag for details. Fixes https://github.com/kaushalmodi/ox-hugo/issues/615. --- CONTRIBUTING.org | 2 +- README.org | 2 +- doc/doc-setupfile.org | 1 + doc/ox-hugo-manual.org | 66 ++++++++++++------- ox-hugo.el | 14 ++-- test/ert/tslug.el | 8 +-- test/site/content-org/all-posts.org | 12 ++-- ...ugo-section-frag-post-in-articles-emacs.md | 2 +- 8 files changed, 65 insertions(+), 42 deletions(-) diff --git a/CONTRIBUTING.org b/CONTRIBUTING.org index 8e4be6f6..99da7dbe 100644 --- a/CONTRIBUTING.org +++ b/CONTRIBUTING.org @@ -60,7 +60,7 @@ error backtrace, Steps to run tests on your machine: 1. Clone this repo. -2. Ensure that ~pandoc~ (at least version [[https://github.com/jgm/pandoc/releases/tag/2.16.2][*2.16.2*]]) are +2. Ensure that ~pandoc~ (at least version [[https://github.com/jgm/pandoc/releases/tag/2.16.2][*2.16.2*]]) is installed (more info [[https://ox-hugo.scripter.co/doc/contributing-guide/#contribute-to-code][here]]). 3. Run ~make -j1 test~. This runs all the tests from the two kinds of diff --git a/README.org b/README.org index 3f101bee..c2c12a99 100644 --- a/README.org +++ b/README.org @@ -161,7 +161,7 @@ Before you export check that these properties are set as you need: [fn:-1-section_more] The ~HUGO_SECTION~ is the bare-minimum requirement to specify the destination path. That path can be further tweaked using ~HUGO_BUNDLE~ key (and the associated ~EXPORT_HUGO_BUNDLE~ -property), and the ~EXPORT_HUGO_SECTION*~ property (only for +property), and the ~EXPORT_HUGO_SECTION_FRAG~ property (only for /per-subtree/ exports). ** Export bindings The common =ox-hugo= export bindings are: diff --git a/doc/doc-setupfile.org b/doc/doc-setupfile.org index 3619074f..da8005ae 100644 --- a/doc/doc-setupfile.org +++ b/doc/doc-setupfile.org @@ -6,6 +6,7 @@ #+macro: commit commit [[https://github.com/kaushalmodi/ox-hugo/commit/$1][$1]] #+macro: issue #[[https://github.com/kaushalmodi/ox-hugo/issues/$1][$1]] +#+macro: pr PR #[[https://github.com/kaushalmodi/ox-hugo/pull/$1][$1]] #+macro: bfissue Blackfriday #[[https://github.com/russross/blackfriday/issues/$1][$1]] #+macro: hugoissue Hugo #[[https://github.com/gohugoio/hugo/issues/$1][$1]] #+macro: ox-hugo-test-file [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/main/test/site/content-org/all-posts.org][=all-posts.org=]] diff --git a/doc/ox-hugo-manual.org b/doc/ox-hugo-manual.org index 3371db18..ec4e5dee 100644 --- a/doc/ox-hugo-manual.org +++ b/doc/ox-hugo-manual.org @@ -174,7 +174,7 @@ Before you export check that these properties are set as you need: [fn:section_more] The ~HUGO_SECTION~ is the bare-minimum requirement to specify the destination path. That path can be further tweaked using ~HUGO_BUNDLE~ key (and the associated ~EXPORT_HUGO_BUNDLE~ -property), and the ~EXPORT_HUGO_SECTION*~ property (only for +property), and the ~EXPORT_HUGO_SECTION_FRAG~ property (only for /per-subtree/ exports). *** Export bindings The common =ox-hugo= export bindings are: @@ -444,8 +444,24 @@ have the exported Markdown files. :PROPERTIES: :EXPORT_FILE_NAME: deprecation-notices :END: +**** ~EXPORT_HUGO_SECTION*~ property is now ~EXPORT_HUGO_SECTION_FRAG~ -- <2022-04-07 Thu> +:PROPERTIES: +:CUSTOM_ID: export-hugo-section-frag +:END: +***** Reason for this change +The earlier ~EXPORT_HUGO_SECTION*~ property name was not a canonical +Org property name because it had an \ast{} in its name. It came to light in +{{{issue(615)}}} that an Org built-in feature [[info:org#Column View][Org Column]] was unable to +filter/edit that property. + +Once that property was renamed to an asterisk-less name: +~EXPORT_HUGO_SECTION_FRAG~, Org Column started working (see the +screenshot in {{{pr(616)}}}). +***** Changes needed in user Org files +Replace all instances of "EXPORT_HUGO_SECTION*" with +"*EXPORT_HUGO_SECTION_FRAG*" in all Org files. **** Org Hugo Auto Export feature now a /minor mode/ -- <2019-01-03 Thu> -***** Changes needed to be done in user config +***** Changes needed in user config 1. Do *not* require ~ox-hugo-auto-export~ any more! - For now, you will get a warning each time you do that /require/. But in few weeks, the old ~ox-hugo-auto-export.el~ @@ -3211,34 +3227,35 @@ But this is Emacs, and with the help of Emacs-Lisp and kind help from to this! #+begin_verse -> /Introducing *~EXPORT_HUGO_SECTION*~* (with that asterisk)/ :tada: +> /Introducing *~EXPORT_HUGO_SECTION_FRAG~*/ :tada: #+end_verse -If a subtree has the ~EXPORT_HUGO_SECTION*~ property set, it is -treated as a section path *fragment*. Such fragment properties will be -concatenated with the *same* fragment properties further up in the -parent hierarchy. +If a subtree has the ~EXPORT_HUGO_SECTION_FRAG~ property set[fn:11], +it is treated as a section path *fragment*. Such fragment properties +will be concatenated with the *same* fragment properties further up in +the parent hierarchy. -The collective concatenated value of ~EXPORT_HUGO_SECTION*~ properties -is further prefixed with the value of the good old ~HUGO_SECTION~ -keyword/property that's effective in that subtree. +The collective concatenated value of ~EXPORT_HUGO_SECTION_FRAG~ +properties is further prefixed with the value of the good old +~HUGO_SECTION~ keyword/property that's effective in that subtree. #+begin_note -~EXPORT_HUGO_SECTION*~ *has* to be set as a subtree property. There is -no Org keyword equivalent for this, because this property is designed -only for /per-subtree/ flow (and it makes sense only for this flow). +~EXPORT_HUGO_SECTION_FRAG~ *has to be set as a subtree +property*. There is no Org keyword equivalent for this, because this +property is designed (and makes sense) only for the /per-subtree/ +flow. #+end_note So the final *section path* looks like this: -#+begin_example -/content/// - └───────────────────── section path ──────────────────────┘ -#+end_example +#+begin_src goat +/content/// + └───────────────────── section path ─────────────────────────┘ +#+end_src See the below example to get further clarity on this logic. #+name: code__using_hugo_section_fragments -#+caption: Using ~EXPORT_HUGO_SECTION*~ in conjunction to ~EXPORT_HUGO_SECTION~ +#+caption: Using ~EXPORT_HUGO_SECTION_FRAG~ with ~EXPORT_HUGO_SECTION~ #+begin_src org ,* Main section :PROPERTIES: @@ -3247,22 +3264,22 @@ See the below example to get further clarity on this logic. The /section path/ derived at this level is ~"main/"~. ,** Sub section 1 :PROPERTIES: -:EXPORT_HUGO_SECTION*: sub1 +:EXPORT_HUGO_SECTION_FRAG: sub1 :END: The /section path/ derived at this level is ~"main/sub1/"~. ,*** Sub section 1.1 :PROPERTIES: -:EXPORT_HUGO_SECTION*: p1 +:EXPORT_HUGO_SECTION_FRAG: p1 :END: The /section path/ derived at this level is ~"main/sub1/p1/"~. ,*** Sub section 1.2 :PROPERTIES: -:EXPORT_HUGO_SECTION*: p2 +:EXPORT_HUGO_SECTION_FRAG: p2 :END: The /section path/ derived at this level is ~"main/sub1/p2/"~. ,** Sub section 2 :PROPERTIES: -:EXPORT_HUGO_SECTION*: sub2 +:EXPORT_HUGO_SECTION_FRAG: sub2 :END: The /section path/ derived at this level is ~"main/sub2/"~. #+end_src @@ -4643,6 +4660,11 @@ Categories,)}}}. maintaining global variables. * Footnotes + +[fn:11] If you are looking for ~EXPORT_HUGO_SECTION*~ property, that +has been deprecated; please see {{{titleref(Deprecation +Notices#export-hugo-section-frag)}}}. + [fn:10] You can find the same (or similar) ~author.html~ partial used in the [[https://github.com/kaushalmodi/hugo-onyx-theme][Hugo theme]] used for this doc site. diff --git a/ox-hugo.el b/ox-hugo.el index aa29927b..3eb820a5 100644 --- a/ox-hugo.el +++ b/ox-hugo.el @@ -1563,9 +1563,9 @@ Search is case-insensitive." "Return the Hugo section path. This is the path relative to the Hugo \"content\" directory. -If the EXPORT_HUGO_SECTION* keyword is set in the current or a +If the EXPORT_HUGO_SECTION_FRAG keyword is set in the current or a parent subtree, return the concatenation of the \"HUGO_SECTION\" -and the concatenated \"EXPORT_HUGO_SECTION*\" values as a path. +and the concatenated \"EXPORT_HUGO_SECTION_FRAG\" values as a path. Else, return the \"HUGO_SECTION\" path. @@ -1574,7 +1574,7 @@ The function always returns a string. INFO is a plist used as a communication channel." (let* ((hugo-section-prop (org-entry-get nil "EXPORT_HUGO_SECTION" :inherit)) (hugo-section-kwd (plist-get info :hugo-section)) - (hugo-section-frag-prop (org-entry-get nil "EXPORT_HUGO_SECTION*" :inherit)) + (hugo-section-frag-prop (org-entry-get nil "EXPORT_HUGO_SECTION_FRAG" :inherit)) (section-path-1 (or hugo-section-prop ;EXPORT_HUGO_SECTION gets higher precedence hugo-section-kwd)) ;This is mainly to support per-file flow section-path) @@ -1587,7 +1587,7 @@ INFO is a plist used as a communication channel." (when (org-string-nw-p hugo-section-frag-prop) (setq section-path-1 (concat (file-name-as-directory section-path-1) ;Add trailing slash if absent - (org-hugo--entry-get-concat nil "EXPORT_HUGO_SECTION*" "/")))) + (org-hugo--entry-get-concat nil "EXPORT_HUGO_SECTION_FRAG" "/")))) (setq section-path (file-name-as-directory section-path-1)) ;; (message "[ox-hugo section-path DBG] section path: %S" section-path) section-path)) @@ -2084,8 +2084,8 @@ Return nil if none of the above are true." ;; path fragments. (while (and pheading (not (org-export-get-node-property :EXPORT_HUGO_SECTION pheading nil))) - ;; Add the :EXPORT_HUGO_SECTION* value to the fragment list. - (when (setq fragment (org-export-get-node-property :EXPORT_HUGO_SECTION* pheading nil)) + ;; Add the :EXPORT_HUGO_SECTION_FRAG value to the fragment list. + (when (setq fragment (org-export-get-node-property :EXPORT_HUGO_SECTION_FRAG pheading nil)) (push fragment fragments)) (setq pheading (org-element-property :parent pheading))) @@ -4260,7 +4260,7 @@ are \"toml\" and \"yaml\"." "HUGO_ALLOW_SPACES_IN_TAGS" "HUGO_BLACKFRIDAY" "HUGO_SECTION" - "HUGO_SECTION*" + "HUGO_SECTION_FRAG" "HUGO_BUNDLE" "HUGO_BASE_DIR" "HUGO_GOLDMARK" diff --git a/test/ert/tslug.el b/test/ert/tslug.el index 219f88b5..f61b47f4 100644 --- a/test/ert/tslug.el +++ b/test/ert/tslug.el @@ -240,11 +240,11 @@ :END: ** Section 2 :PROPERTIES: -:EXPORT_HUGO_SECTION*: sec2 +:EXPORT_HUGO_SECTION_FRAG: sec2 :END: *** Section 3 :PROPERTIES: -:EXPORT_HUGO_SECTION*: sec3 +:EXPORT_HUGO_SECTION_FRAG: sec3 :END: **** Some page :PROPERTIES: @@ -263,11 +263,11 @@ :END: ** Section 2 :PROPERTIES: -:EXPORT_HUGO_SECTION*: sec2 +:EXPORT_HUGO_SECTION_FRAG: sec2 :END: *** Section 3 :PROPERTIES: -:EXPORT_HUGO_SECTION*: sec3 +:EXPORT_HUGO_SECTION_FRAG: sec3 :EXPORT_HUGO_BUNDLE: branch :END: **** Branch bundle diff --git a/test/site/content-org/all-posts.org b/test/site/content-org/all-posts.org index cf7b8eb5..987ab841 100644 --- a/test/site/content-org/all-posts.org +++ b/test/site/content-org/all-posts.org @@ -740,7 +740,7 @@ This post is created at the site root. ** Section fragment concatenation :fragment:concatenation:deep_nesting: *** sub1 section :PROPERTIES: -:EXPORT_HUGO_SECTION*: sub1 +:EXPORT_HUGO_SECTION_FRAG: sub1 :END: **** Post in sub1 :PROPERTIES: @@ -751,7 +751,7 @@ Test post created in ~posts/sub1~. #+end_description **** sub1/sub2 section :PROPERTIES: -:EXPORT_HUGO_SECTION*: sub2 +:EXPORT_HUGO_SECTION_FRAG: sub2 :END: ***** Post in sub1/sub2 :PROPERTIES: @@ -762,7 +762,7 @@ Test post created in ~posts/sub1/sub2~. #+end_description ***** sub1/sub2/sub3 section :PROPERTIES: -:EXPORT_HUGO_SECTION*: sub3 +:EXPORT_HUGO_SECTION_FRAG: sub3 :END: ****** Post in sub1/sub2/sub3 :PROPERTIES: @@ -771,10 +771,10 @@ Test post created in ~posts/sub1/sub2~. #+begin_description Test post created in ~posts/sub1/sub2/sub3~. #+end_description -*** Post with all HUGO_SECTION, HUGO_SECTION*, EXPORT_FILE_NAME in same subtree +*** Post with all HUGO_SECTION, HUGO_SECTION_FRAG, EXPORT_FILE_NAME in same subtree :PROPERTIES: :EXPORT_HUGO_SECTION: articles -:EXPORT_HUGO_SECTION*: emacs +:EXPORT_HUGO_SECTION_FRAG: emacs :EXPORT_FILE_NAME: hugo-section-frag-post-in-articles-emacs :END: #+begin_description @@ -786,7 +786,7 @@ Test post created in ~articles/emacs~. :END: *** Articles :PROPERTIES: -:EXPORT_HUGO_SECTION*: articles +:EXPORT_HUGO_SECTION_FRAG: articles :END: **** Articles Index page :PROPERTIES: diff --git a/test/site/content/articles/emacs/hugo-section-frag-post-in-articles-emacs.md b/test/site/content/articles/emacs/hugo-section-frag-post-in-articles-emacs.md index 0f6fa615..2bea87c8 100644 --- a/test/site/content/articles/emacs/hugo-section-frag-post-in-articles-emacs.md +++ b/test/site/content/articles/emacs/hugo-section-frag-post-in-articles-emacs.md @@ -1,5 +1,5 @@ +++ -title = "Post with all HUGO_SECTION, HUGO_SECTION*, EXPORT_FILE_NAME in same subtree" +title = "Post with all HUGO_SECTION, HUGO_SECTION_FRAG, EXPORT_FILE_NAME in same subtree" description = "Test post created in `articles/emacs`." tags = ["section", "fragment", "concatenation", "deep-nesting"] draft = false