Fix: Don't change default interpretation of #+TAGS #breaking

Fixes #89 - Restore the default Org behavior of `#+TAGS`. Now that keyword (and the `EXPORT_TAGS` property) is **not** used by `ox-hugo`. - File-based exports must now use `#+HUGO_TAGS` to set the post tags. - Subtree-based exports can use the `EXPORT_HUGO_TAGS` property to override Org-style tags on the same headline (and the ones inherited from Org-style tags from any of the parent subtrees and `#+FILETAGS`). - Note that for subtree-based exports, `#+FILETAGS` can be used to set tags globally in the file. Earlier `#+TAGS` was used for that purpose. - Subtree-based exports can use the `EXPORT_HUGO_CATEGORIES` property to override Org-style categories (tags with "@" prefix) on the same headline (and the ones inherited from Org-style categories from any of the parent subtrees and `#+FILETAGS`). - Note that for subtree-based exports, `#+FILETAGS` can be used to set categories (tags with "@") globally in the file. ** Why use #+FILETAGS and not #+TAGS?? - About `#+FILETAGS` -- [Tag Inheritance](http://orgmode.org/manual/Tag-inheritance.html) - About `#+TAGS` -- [Setting Tags](http://orgmode.org/manual/Setting-tags.html) ===== See https://ox-hugo.scripter.co/doc/tags-and-categories/ =====
kaushalmodi · Oct 29, 2017 · 30ac7c3 · 30ac7c3
1 parent 4a476d9
commit 30ac7c3
Show file tree

Hide file tree

Showing 15 changed files with 401 additions and 90 deletions.
diff --git a/README.org b/README.org
@@ -155,6 +155,28 @@ The common =ox-hugo= export bindings are:
 Do =M-x customize-group=, and select =org-export-hugo= to see the
 available customization options for this package.
 * Changelog
+** v0.4 <2017-10-28 Sat>
+*** Backward-incompatible changes
+- Restore the default Org behavior of =#+TAGS=. Now that keyword (and
+  the =EXPORT_TAGS= property) is *not* used by =ox-hugo=. Fixes
+  [[[https://github.com/kaushalmodi/ox-hugo/issues/89][89]]].
+- File-based exports must now use =#+HUGO_TAGS= to set the post tags.
+- Subtree-based exports can use the =EXPORT_HUGO_TAGS= property to
+  override Org-style tags on the same headline (and the ones inherited
+  from Org-style tags from any of the parent subtrees and
+  =#+FILETAGS=).
+  - Note that for subtree-based exports, =#+FILETAGS= can be used to
+    set tags globally in the file. Earlier =#+TAGS= was used for that
+    purpose.
+- Subtree-based exports can use the =EXPORT_HUGO_CATEGORIES= property
+  to override Org-style categories (tags with "@" prefix) on the same
+  headline (and the ones inherited from Org-style categories from any
+  of the parent subtrees and =#+FILETAGS=).
+  - Note that for subtree-based exports, =#+FILETAGS= can be used to
+    set categories (tags with "@") globally in the file.
+
+See the new section added to documentation:
+[[https://ox-hugo.scripter.co/doc/tags-and-categories][*Tags and Categories*]]
 ** v0.3.2 <2017-10-24 Tue>
 *** Fixes
 - Fix issue with headline metadata parsing (ALLTAGS, CLOSED, TODO)

diff --git a/doc/content/doc/changelog.md b/doc/content/doc/changelog.md
@@ -6,6 +6,33 @@ draft = false
   identifier = "changelog"
 +++
 
+## v0.4 <span class="timestamp-wrapper"><span class="timestamp">&lt;2017-10-28 Sat&gt;</span></span> {#v0-dot-4}
+
+
+### Backward-incompatible changes {#backward-incompatible-changes}
+
+-   Restore the default Org behavior of `#+TAGS`. Now that keyword (and
+    the `EXPORT_TAGS` property) is **not** used by `ox-hugo`. Fixes
+    [[89](https://github.com/kaushalmodi/ox-hugo/issues/89)].
+-   File-based exports must now use `#+HUGO_TAGS` to set the post tags.
+-   Subtree-based exports can use the `EXPORT_HUGO_TAGS` property to
+    override Org-style tags on the same headline (and the ones inherited
+    from Org-style tags from any of the parent subtrees and
+    `#+FILETAGS`).
+    -   Note that for subtree-based exports, `#+FILETAGS` can be used to
+        set tags globally in the file. Earlier `#+TAGS` was used for that
+        purpose.
+-   Subtree-based exports can use the `EXPORT_HUGO_CATEGORIES` property
+    to override Org-style categories (tags with "@" prefix) on the same
+    headline (and the ones inherited from Org-style categories from any
+    of the parent subtrees and `#+FILETAGS`).
+    -   Note that for subtree-based exports, `#+FILETAGS` can be used to
+        set categories (tags with "@") globally in the file.
+
+See the new section added to documentation:
+[**Tags and Categories**](/doc/tags-and-categories)
+
+
 ## v0.3.2 <span class="timestamp-wrapper"><span class="timestamp">&lt;2017-10-24 Tue&gt;</span></span> {#v0-dot-3-dot-2}
 
 

diff --git a/doc/content/doc/tags-and-categories.md b/doc/content/doc/tags-and-categories.md
@@ -0,0 +1,113 @@
++++
+title = "Tags and Categories"
+draft = false
+[menu."org_to_hugo"]
+  weight = 3005
+  identifier = "tags-and-categories"
++++
+
+## Subtree-based Export {#subtree-based-export}
+
+
+### Tags {#tags}
+
+For subtree-based exports, the Hugo front-matter `tags` values are
+derived from Org tags set for the post subtree headline.
+
+Example:
+
+```org
+* My post                                                         :tag1:tag2:
+```
+
+By default, Org tags from parent headlines, and the tags set in the
+`#+FILETAGS` keyword get inherited (as the default value of
+`org-use-tag-inheritance` is `t`). If the tag inheritance doesn't work
+as expected, check that the value of that variable is set as required.
+
+If the `EXPORT_HUGO_TAGS` property is set for a valid Hugo post
+subtree, the value of that property will **completely override** the Org
+tags set even on that subtree, the inherited values of Org-style tags
+from parent headlines and even `#+FILETAGS`.
+
+
+#### Why use `#+FILETAGS` and not `#+TAGS`? {#why-use-filetags-and-not-tags}
+
+-   About `#+FILETAGS` -- [Tag Inheritance](http://orgmode.org/manual/Tag-inheritance.html) or `C-h i g (org) Tag
+      inheritance`
+-   About `#+TAGS` -- [Setting Tags](http://orgmode.org/manual/Setting-tags.html) or `C-h i g (org) Setting tags`
+
+
+### Categories {#categories}
+
+For subtree-based exports, the Hugo front-matter `categories` values
+are derived from Org tags set for the post subtree headline, but only
+the ones prefixed with **@**.
+
+Example:
+
+```org
+* My post                                                       :@cat1:@cat2:
+```
+
+As with the tags, by default, the categories (Org tags with "@"
+prefix) from parent headlines, and the ones set in the `#+FILETAGS`
+keyword too get inherited (as the default value of
+`org-use-tag-inheritance` is `t`). If the tag inheritance doesn't work
+as expected, check that the value of that variable is set as required.
+
+If the `EXPORT_HUGO_CATEGORIES` property is set for a valid Hugo post
+subtree, the value of that property will **completely override** the
+categories set even on that subtree, the inherited values of
+categories from parent headlines and even `#+FILETAGS`.
+
+
+## File-based Export {#file-based-export}
+
+The tag (and category) inheritance does not apply to the file-based
+export flow. So `#+FILETAGS` will have no effect in this flow.
+
+-   To set tags, use `#+HUGO_TAGS`.
+-   To set categories, use `#+HUGO_CATEGORIES`.
+
+
+## Hyphens in tags (and categories) {#hyphens-in-tags--and-categories}
+
+Hyphens are not allowed in Org tags. So `ox-hugo` converts **single
+underscores** to hyphens if `org-hugo-prefer-hyphen-in-tags` is set to
+non-nil (default). So an Org tag **abc\_def** will be exported as _tag_
+**"abc-def"**. Similarly an Org tag **@abc\_def** will be exported as
+_category_ **"abc-def"**.
+
+To export a tag or category with an underscore, use 3 consecutive
+underscores. So an Org tag **abc\_\_\_def** will be exported as _tag_
+**"abc\_def"**. If you rather prefer to always export single underscores
+as underscores, set `org-hugo-prefer-hyphen-in-tags` to nil.
+
+This variable does not affect the tags set via `#+HUGO_TAGS` keyword
+or the `EXPORT_HUGO_TAGS` property, because Org keywords and
+properties allow using the hyphen character. So underscores and
+hyphens in tags (or categories in `#+HUGO_CATEGORIES` /
+`EXPORT_HUGO_CATEGORIES`) remain untransformed on export.
+
+
+## Spaces in tags (and categories) {#spaces-in-tags--and-categories}
+
+Spaces are not allowed in Org tags. So `ox-hugo` converts **double
+underscores** to spaces if `org-hugo-allow-spaces-in-tags` is set to
+non-nil (default). So an Org tag **abc\_\_def** will be exported as _tag_
+**"abc def"**. Similarly an Org tag **@abc\_\_def** will be exported as
+_category_ **"abc def"**.
+
+This variable **also affects** the tags set via `#+HUGO_TAGS` keyword or
+the `EXPORT_HUGO_TAGS` property, because it is not possible to
+distinguish in Org keywords and properties whether the space is part
+of the tag or used to separate two tags. The same applies to
+categories set via `#+HUGO_CATEGORIES` / `EXPORT_HUGO_CATEGORIES`.
+
+
+## Examples {#examples}
+
+-   [Org source](https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content-org/tags-and-categories.org)
+-   Exported Markdown -- [`inheriting-tags.md`](https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content/posts/inheriting-tags.md), [`overriding-tags.md`](https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content/posts/overriding-tags.md)
+-   Hugo-generated HTML -- [Inheriting tags](https://ox-hugo.scripter.co/test/posts/inheriting-tags/), [Overriding tags](https://ox-hugo.scripter.co/test/posts/overriding-tags/)
diff --git a/doc/ox-hugo-manual.org b/doc/ox-hugo-manual.org
@@ -13,6 +13,28 @@
 :PROPERTIES:
 :CUSTOM_ID: changelog
 :END:
+** v0.4 <2017-10-28 Sat>
+*** Backward-incompatible changes
+- Restore the default Org behavior of =#+TAGS=. Now that keyword (and
+  the =EXPORT_TAGS= property) is *not* used by =ox-hugo=. Fixes
+  {{{issue(89)}}}.
+- File-based exports must now use =#+HUGO_TAGS= to set the post tags.
+- Subtree-based exports can use the =EXPORT_HUGO_TAGS= property to
+  override Org-style tags on the same headline (and the ones inherited
+  from Org-style tags from any of the parent subtrees and
+  =#+FILETAGS=).
+  - Note that for subtree-based exports, =#+FILETAGS= can be used to
+    set tags globally in the file. Earlier =#+TAGS= was used for that
+    purpose.
+- Subtree-based exports can use the =EXPORT_HUGO_CATEGORIES= property
+  to override Org-style categories (tags with "@" prefix) on the same
+  headline (and the ones inherited from Org-style categories from any
+  of the parent subtrees and =#+FILETAGS=).
+  - Note that for subtree-based exports, =#+FILETAGS= can be used to
+    set categories (tags with "@") globally in the file.
+
+See the new section added to documentation:
+{{{doc(tags-and-categories,*Tags and Categories*)}}}
 ** v0.3.2 <2017-10-24 Tue>
 *** Fixes
 - Fix issue with headline metadata parsing (ALLTAGS, CLOSED, TODO)
@@ -930,6 +952,92 @@ The Org source for the below is similar to the above, except that the
 =-n= switch is also added to enable the line numbers.
 
 #+INCLUDE: "../test/site/content-org/all-posts.org::#source-blocks-with-highlighting-with-linenums-not-starting-from-1" :only-contents t
+*** Tags and Categories
+:PROPERTIES:
+:EXPORT_FILE_NAME: tags-and-categories
+:END:
+**** Subtree-based Export
+***** Tags
+For subtree-based exports, the Hugo front-matter =tags= values are
+derived from Org tags set for the post subtree headline.
+
+Example:
+#+BEGIN_SRC org
+,* My post                                                         :tag1:tag2:
+#+END_SRC
+
+By default, Org tags from parent headlines, and the tags set in the
+=#+FILETAGS= keyword get inherited (as the default value of
+=org-use-tag-inheritance= is =t=). If the tag inheritance doesn't work
+as expected, check that the value of that variable is set as required.
+
+If the =EXPORT_HUGO_TAGS= property is set for a valid Hugo post
+subtree, the value of that property will *completely override* the Org
+tags set even on that subtree, the inherited values of Org-style tags
+from parent headlines and even =#+FILETAGS=.
+****** Why use =#+FILETAGS= and not =#+TAGS=?
+- About =#+FILETAGS= -- [[http://orgmode.org/manual/Tag-inheritance.html][Tag Inheritance]] or =C-h i g (org) Tag
+  inheritance=
+- About =#+TAGS= -- [[http://orgmode.org/manual/Setting-tags.html][Setting Tags]] or =C-h i g (org) Setting tags=
+***** Categories
+For subtree-based exports, the Hugo front-matter =categories= values
+are derived from Org tags set for the post subtree headline, but only
+the ones prefixed with *@*.
+
+Example:
+#+BEGIN_SRC org
+,* My post                                                       :@cat1:@cat2:
+#+END_SRC
+
+As with the tags, by default, the categories (Org tags with "@"
+prefix) from parent headlines, and the ones set in the =#+FILETAGS=
+keyword too get inherited (as the default value of
+=org-use-tag-inheritance= is =t=). If the tag inheritance doesn't work
+as expected, check that the value of that variable is set as required.
+
+If the =EXPORT_HUGO_CATEGORIES= property is set for a valid Hugo post
+subtree, the value of that property will *completely override* the
+categories set even on that subtree, the inherited values of
+categories from parent headlines and even =#+FILETAGS=.
+**** File-based Export
+The tag (and category) inheritance does not apply to the file-based
+export flow. So =#+FILETAGS= will have no effect in this flow.
+
+- To set tags, use =#+HUGO_TAGS=.
+- To set categories, use =#+HUGO_CATEGORIES=.
+**** Hyphens in tags (and categories)
+Hyphens are not allowed in Org tags. So =ox-hugo= converts *single
+underscores* to hyphens if =org-hugo-prefer-hyphen-in-tags= is set to
+non-nil (default). So an Org tag *abc_def* will be exported as /tag/
+*"abc-def"*. Similarly an Org tag *@abc_def* will be exported as
+/category/ *"abc-def"*.
+
+To export a tag or category with an underscore, use 3 consecutive
+underscores. So an Org tag *abc___def* will be exported as /tag/
+*"abc_def"*. If you rather prefer to always export single underscores
+as underscores, set =org-hugo-prefer-hyphen-in-tags= to nil.
+
+This variable does not affect the tags set via =#+HUGO_TAGS= keyword
+or the =EXPORT_HUGO_TAGS= property, because Org keywords and
+properties allow using the hyphen character. So underscores and
+hyphens in tags (or categories in =#+HUGO_CATEGORIES= /
+=EXPORT_HUGO_CATEGORIES=) remain untransformed on export.
+**** Spaces in tags (and categories)
+Spaces are not allowed in Org tags. So =ox-hugo= converts *double
+underscores* to spaces if =org-hugo-allow-spaces-in-tags= is set to
+non-nil (default). So an Org tag *abc__def* will be exported as /tag/
+*"abc def"*. Similarly an Org tag *@abc__def* will be exported as
+/category/ *"abc def"*.
+
+This variable *also affects* the tags set via =#+HUGO_TAGS= keyword or
+the =EXPORT_HUGO_TAGS= property, because it is not possible to
+distinguish in Org keywords and properties whether the space is part
+of the tag or used to separate two tags. The same applies to
+categories set via =#+HUGO_CATEGORIES= / =EXPORT_HUGO_CATEGORIES=.
+**** Examples
+- [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content-org/tags-and-categories.org][Org source]]
+- Exported Markdown -- [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content/posts/inheriting-tags.md][=inheriting-tags.md=]], [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content/posts/overriding-tags.md][=overriding-tags.md=]]
+- Hugo-generated HTML -- [[https://ox-hugo.scripter.co/test/posts/inheriting-tags/][Inheriting tags]], [[https://ox-hugo.scripter.co/test/posts/overriding-tags/][Overriding tags]]
 * COMMENT Local Variables                                           :ARCHIVE:
 # Local Variables:
 # fill-column: 70