Skip to content

Commit

Permalink
Merge pull request #616 from kaushalmodi/hugo-section-frag
Browse files Browse the repository at this point in the history
feat!: `EXPORT_HUGO_SECTION_FRAG` replaces `EXPORT_HUGO_SECTION*`
  • Loading branch information
kaushalmodi committed Apr 8, 2022
2 parents b1f014a + 88ae5c8 commit ad412e0
Show file tree
Hide file tree
Showing 8 changed files with 65 additions and 42 deletions.
2 changes: 1 addition & 1 deletion CONTRIBUTING.org
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion README.org
Expand Up @@ -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:
Expand Down
1 change: 1 addition & 0 deletions doc/doc-setupfile.org
Expand Up @@ -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=]]
Expand Down
66 changes: 44 additions & 22 deletions doc/ox-hugo-manual.org
Expand Up @@ -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:
Expand Down Expand Up @@ -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~
Expand Down Expand Up @@ -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
<HUGO_BASE_DIR>/content/<HUGO_SECTION>/<concatenated values of EXPORT_HUGO_SECTION*>/
└───────────────────── section path ──────────────────────┘
#+end_example
#+begin_src goat
<HUGO_BASE_DIR>/content/<HUGO_SECTION>/<concatenated values of EXPORT_HUGO_SECTION_FRAG>/
└───────────────────── 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:
Expand All @@ -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
Expand Down Expand Up @@ -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.

Expand Down
14 changes: 7 additions & 7 deletions ox-hugo.el
Expand Up @@ -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.
Expand All @@ -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)
Expand All @@ -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))
Expand Down Expand Up @@ -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)))

Expand Down Expand Up @@ -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"
Expand Down
8 changes: 4 additions & 4 deletions test/ert/tslug.el
Expand Up @@ -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<point>
:PROPERTIES:
Expand All @@ -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
Expand Down
12 changes: 6 additions & 6 deletions test/site/content-org/all-posts.org
Expand Up @@ -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:
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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
Expand All @@ -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:
Expand Down
@@ -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
Expand Down

0 comments on commit ad412e0

Please sign in to comment.