[ox, patch] Keywords & what should go in ox?

[ox, patch] Keywords & what should go in ox?

[Rasmus]

[-- Attachment #1: Type: text/plain, Size: 1311 bytes --]

Hi,

First, as discussed a while back we want to move DESCRIPTION and KEYWORDS
out of ox.el as they are specific to certain backends.  The first patch
does this.

Second, I want to add support for printing keywords.  This patch is still
rough (i.e. no need commenting), but before proceeding I want to discuss
some things.  The goal is to allow cool stuff like:

   #+begin_abstract
     Read my paper, please...
     #+keywords: org, markup
   #+end_abstract

And eventually:

   #+tile: my fancy blog
   #+keywords: org, markup

Where 'org' and 'markup' would magically become links to indexes (like on
them fancy blogs on the interwebs).  I'm still not sure how to do the
latter (see TODO comment in patch).

So, I'm in a dilemma now.  On the one hand, ox should probably not include
too much cruft that is specific to certain backends.  OTOH, stuff like the
repetition of org-BACKEND-with-keywords and org-BACKEND-keywords-prefix is
a bit annoying (cf. patch).

Another idea I want to discuss.  I use "prefix" to designate what is
printed before the :.  By default the translated value of "Keywords".
Would it make sense to make this configurable in the file, e.g. as

      #+KEYWORDS: [my prefix: ] key0, key1, ....

—Rasmus

-- 
To err is human. To screw up 10⁶ times per second, you need a computer

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ox-Move-KEYWORD-and-DESCRIPTION-out-of-ox.patch --]
[-- Type: text/x-diff, Size: 6041 bytes --]

From 033f7b89f9f7d8a6776bc0758b0bd2db69eb24d1 Mon Sep 17 00:00:00 2001
From: Rasmus <rasmus@gmx.us>
Date: Fri, 13 Mar 2015 21:38:26 +0100
Subject: [PATCH 1/2] ox: Move KEYWORD and DESCRIPTION out of ox

* ox.el: Remove KEYWORD and DESCRIPTION.
* ox-deck.el, ox-rss.el, ox-html, ox-latex, ox-odt, ox-org: Add
  keyword and description.
* org.texi (Export settings): Explicit state which backends
  support DESCRIPTION and KEYWORDS.
---
 contrib/lisp/ox-deck.el | 4 +++-
 contrib/lisp/ox-rss.el  | 4 +++-
 doc/org.texi            | 9 ++++++---
 lisp/ox-html.el         | 2 ++
 lisp/ox-latex.el        | 2 ++
 lisp/ox-odt.el          | 2 ++
 lisp/ox-org.el          | 2 ++
 lisp/ox.el              | 2 --
 8 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/contrib/lisp/ox-deck.el b/contrib/lisp/ox-deck.el
index 0ebde41..7155863 100644
--- a/contrib/lisp/ox-deck.el
+++ b/contrib/lisp/ox-deck.el
@@ -51,7 +51,9 @@
 	      (if a (org-deck-export-to-html t s v b)
 		(org-open-file (org-deck-export-to-html nil s v b)))))))
   :options-alist
-  '((:html-link-home "HTML_LINK_HOME" nil nil)
+  '((:description "DESCRIPTION" nil nil newline)
+    (:keywords "KEYWORDS" nil nil space)
+    (:html-link-home "HTML_LINK_HOME" nil nil)
     (:html-link-up "HTML_LINK_UP" nil nil)
     (:deck-postamble "DECK_POSTAMBLE" nil org-deck-postamble newline)
     (:deck-preamble "DECK_PREAMBLE" nil org-deck-preamble newline)
diff --git a/contrib/lisp/ox-rss.el b/contrib/lisp/ox-rss.el
index 67b925f..8d3cc27 100644
--- a/contrib/lisp/ox-rss.el
+++ b/contrib/lisp/ox-rss.el
@@ -122,7 +122,9 @@ When nil, Org will create ids using `org-icalendar-create-uid'."
 	      (if a (org-rss-export-to-rss t s v)
 		(org-open-file (org-rss-export-to-rss nil s v)))))))
   :options-alist
-  '((:with-toc nil nil nil) ;; Never include HTML's toc
+  '((:description "DESCRIPTION" nil nil newline)
+    (:keywords "KEYWORDS" nil nil space)
+    (:with-toc nil nil nil) ;; Never include HTML's toc
     (:rss-extension "RSS_EXTENSION" nil org-rss-extension)
     (:rss-image-url "RSS_IMAGE_URL" nil org-rss-image-url)
     (:rss-categories nil nil org-rss-categories))
diff --git a/doc/org.texi b/doc/org.texi
index 632eb19..8fd958c 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -10612,7 +10612,9 @@ exported.}.
 @item DESCRIPTION
 @cindex #+DESCRIPTION
 The document description.  Back-ends handle it as they see fit (e.g., for the
-XHTML meta tag), if at all.  You can use several such keywords for long
+XHTML meta tag), if at all.  The description-keyword is used in
+@LaTeX{}-backends (see @var{org-latex-hyperref-template}), the HTML backend,
+and the ODT backend.  You can use several such keywords for long
 descriptions.
 
 @item EMAIL
@@ -10623,8 +10625,9 @@ The email address (@code{user-mail-address}).
 @item KEYWORDS
 @cindex #+KEYWORDS
 The keywords defining the contents of the document.  Back-ends handle it as
-they see fit (e.g., for the XHTML meta tag), if at all.  You can use several
-such keywords if the list is long.
+they see fit (e.g., for the XHTML meta tag), if at all.  Keywords are used in
+@LaTeX{} backends, (see @var{org-latex-hyperref-template}), the HTML backend,
+and the ODT backend.  You can use several such keywords if the list is long.
 
 @item LANGUAGE
 @cindex #+LANGUAGE
diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index 92fe3d9..21e6122 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -110,6 +110,8 @@
   :options-alist
   '((:html-doctype "HTML_DOCTYPE" nil org-html-doctype)
     (:html-container "HTML_CONTAINER" nil org-html-container-element)
+    (:description "DESCRIPTION" nil nil newline)
+    (:keywords "KEYWORDS" nil nil space)
     (:html-html5-fancy nil "html5-fancy" org-html-html5-fancy)
     (:html-link-use-abs-url nil "html-link-use-abs-url" org-html-link-use-abs-url)
     (:html-link-home "HTML_LINK_HOME" nil org-html-link-home)
diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index 6cec8a1..f3c47dc 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -110,6 +110,8 @@
     (:latex-class-options "LATEX_CLASS_OPTIONS" nil nil t)
     (:latex-header "LATEX_HEADER" nil nil newline)
     (:latex-header-extra "LATEX_HEADER_EXTRA" nil nil newline)
+    (:description "DESCRIPTION" nil nil newline)
+    (:keywords "KEYWORDS" nil nil space)
     ;; Other variables.
     (:latex-active-timestamp-format nil nil org-latex-active-timestamp-format)
     (:latex-caption-above nil nil org-latex-caption-above)
diff --git a/lisp/ox-odt.el b/lisp/ox-odt.el
index 386e894..dd3020e 100644
--- a/lisp/ox-odt.el
+++ b/lisp/ox-odt.el
@@ -97,6 +97,8 @@
 		(org-open-file (org-odt-export-to-odt nil s v) 'system))))))
   :options-alist
   '((:odt-styles-file "ODT_STYLES_FILE" nil nil t)
+    (:description "DESCRIPTION" nil nil newline)
+    (:keywords "KEYWORDS" nil nil space)
     ;; Other variables.
     (:odt-content-template-file nil nil org-odt-content-template-file)
     (:odt-display-outline-level nil nil org-odt-display-outline-level)
diff --git a/lisp/ox-org.el b/lisp/ox-org.el
index 734b8d2..3d65465 100644
--- a/lisp/ox-org.el
+++ b/lisp/ox-org.el
@@ -102,6 +102,8 @@ setting of `org-html-htmlize-output-type' is 'css."
     (underline . org-org-identity)
     (verbatim . org-org-identity)
     (verse-block . org-org-identity))
+  :options-alist '((:description "DESCRIPTION" nil nil newline)
+		   (:keywords "KEYWORDS" nil nil space))
   :menu-entry
   '(?O "Export to Org"
        ((?O "As Org buffer" org-org-export-as-org)
diff --git a/lisp/ox.el b/lisp/ox.el
index 0c7728f..213e56d 100644
--- a/lisp/ox.el
+++ b/lisp/ox.el
@@ -102,8 +102,6 @@
     (:date "DATE" nil nil t)
     (:author "AUTHOR" nil user-full-name t)
     (:email "EMAIL" nil user-mail-address t)
-    (:description "DESCRIPTION" nil nil newline)
-    (:keywords "KEYWORDS" nil nil space)
     (:language "LANGUAGE" nil org-export-default-language t)
     (:select-tags "SELECT_TAGS" nil org-export-select-tags split)
     (:exclude-tags "EXCLUDE_TAGS" nil org-export-exclude-tags split)
-- 
2.3.2


[-- Attachment #3: 0002-ox-Add-inclusion-of-KEYWORDS.patch --]
[-- Type: text/x-diff, Size: 13556 bytes --]

From 501fd9b90b1565e9e9a346c26706ae414f0417d7 Mon Sep 17 00:00:00 2001
From: Rasmus <rasmus@gmx.us>
Date: Fri, 13 Mar 2015 21:51:07 +0100
Subject: [PATCH 2/2] ox: Add inclusion of KEYWORDS

* ox-html.el (org-html-style-default): Add .keywords-value and
  .keywords-prefix style.
  (org-html-with-keywords,org-html-keywords-prefix): New variable.
  (org-html-keyword): Allow preliminary keywords inclusion.
* ox-ascii.el (org-ascii-with-keywords)
  (org-ascii-keyword-prefix): New variable.
  (org-ascii-keyword): Allow keywords includsion.
* ox-latex.el (org-latex-with-keywords)
  (org-latex-keywords-prefix, org-latex-keywords-template): New variable.
  (org-latex-keyword): Allow keywords inclusion.
* ox-odt.el (org-odt-with-keywords),
  (org-odt-keywords-prefix): New variable.
  (org-odt-keyword): Allow keywords inclusion.
* OrgOdtStyles.xml (OrgKeywordsPrefix, OrgKeywords): New style.
* ox.el (org-export-dictionary): Add "Keywords".

This allow constructs like this:

    #+begin_abstract
    my abstract
    #+keywords: markup, keywords, org-mode
    #+end_abstract
---
 etc/styles/OrgOdtStyles.xml |  4 ++++
 lisp/ox-ascii.el            | 34 ++++++++++++++++++++++++++++++--
 lisp/ox-html.el             | 45 +++++++++++++++++++++++++++++++++++++++++--
 lisp/ox-latex.el            | 47 ++++++++++++++++++++++++++++++++++++++++-----
 lisp/ox-odt.el              | 34 +++++++++++++++++++++++++++++++-
 lisp/ox.el                  |  5 +++++
 6 files changed, 159 insertions(+), 10 deletions(-)

diff --git a/etc/styles/OrgOdtStyles.xml b/etc/styles/OrgOdtStyles.xml
index 1a8edee..c9710b9 100644
--- a/etc/styles/OrgOdtStyles.xml
+++ b/etc/styles/OrgOdtStyles.xml
@@ -416,6 +416,10 @@
   <style:style style:name="OrgTimestampKeyword" style:family="text">
    <style:text-properties style:use-window-font-color="true" fo:font-weight="bold"/>
   </style:style>
+  <style:style style:name="OrgKeywordsPrefix" style:family="text">
+    <style:text-properties fo:font-style="italic"/>
+  </style:style>
+  <style:style style:name="OrgKeywords" style:family="text"/>
   <style:style style:name="OrgScheduledKeyword" style:family="text" style:parent-style-name="OrgTimestampKeyword"/>
   <style:style style:name="OrgDeadlineKeyword" style:family="text" style:parent-style-name="OrgTimestampKeyword"/>
   <style:style style:name="OrgClockKeyword" style:family="text" style:parent-style-name="OrgTimestampKeyword"/>
diff --git a/lisp/ox-ascii.el b/lisp/ox-ascii.el
index d5517bc..13e6ff7 100644
--- a/lisp/ox-ascii.el
+++ b/lisp/ox-ascii.el
@@ -121,7 +121,8 @@
 				       org-ascii-filter-comment-spacing)
 		   (:filter-section . org-ascii-filter-headline-blank-lines))
   :options-alist
-  '((:ascii-bullets nil nil org-ascii-bullets)
+  '((:keywords "KEYWORDS" nil nil space)
+    (:ascii-bullets nil nil org-ascii-bullets)
     (:ascii-caption-above nil nil org-ascii-caption-above)
     (:ascii-charset nil nil org-ascii-charset)
     (:ascii-global-margin nil nil org-ascii-global-margin)
@@ -142,7 +143,9 @@
     (:ascii-table-widen-columns nil nil org-ascii-table-widen-columns)
     (:ascii-text-width nil nil org-ascii-text-width)
     (:ascii-underline nil nil org-ascii-underline)
-    (:ascii-verbatim-format nil nil org-ascii-verbatim-format)))
+    (:ascii-verbatim-format nil nil org-ascii-verbatim-format)
+    (:keywords-prefix nil nil org-ascii-keywords-prefix)
+    (:with-keywords nil "keywords" org-ascii-with-keywords)))
 
 
 \f
@@ -410,6 +413,22 @@ nil to ignore the inline task."
   :package-version '(Org . "8.3")
   :type 'function)
 
+(defcustom org-ascii-keywords-prefix t
+  "Nonnil means prefix keywords.
+If the value is a string the string is used.  Otherwise the
+translation of \"Keywords\" from `org-export-dictionary' is used."
+  :group 'org-export-ascii
+  :version "25.1"
+  :package-version '(Org . "8.3")
+  :type '(choice boolean string))
+
+(defcustom org-ascii-with-keywords nil
+  "Nonnil means print keywords."
+  :group 'org-export-ascii
+  :version "25.1"
+  :package-version '(Org . "8.3")
+  :type 'boolean)
+
 
 \f
 ;;; Internal Functions
@@ -1470,6 +1489,17 @@ information."
 	(value (org-element-property :value keyword)))
     (cond
      ((string= key "ASCII") (org-ascii--justify-element value keyword info))
+     ((and (string= key "KEYWORDS")
+	   (plist-get info :with-keywords))
+      (format "%s%s"
+	      (let ((prefix (plist-get :keywords-prefix info))) 
+		(cond ((stringp prefix) prefix)
+		      (prefix
+		       (concat (org-export-translate "Keywords"
+						     (plist-get info :ascii-charset)  info)
+			       ": "))
+		      (t "")))
+	      (org-export-data value info)))
      ((string= key "TOC")
       (org-ascii--justify-element
        (let ((case-fold-search t))
diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index 21e6122..11aed01 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -173,7 +173,9 @@
     (:creator "CREATOR" nil org-html-creator-string)
     (:with-latex nil "tex" org-html-with-latex)
     ;; Retrieve LaTeX header for fragments.
-    (:latex-header "LATEX_HEADER" nil nil newline)))
+    (:latex-header "LATEX_HEADER" nil nil newline)
+    (:keywords-prefix nil nil org-html-keywords-prefix)
+    (:with-keywords nil "keywords" nil org-html-with-keywords)))
 
 \f
 ;;; Internal Variables
@@ -285,7 +287,7 @@ for the JavaScript code in this tag.
   .left   { margin-left: 0px;  margin-right: auto; text-align: left; }
   .center { margin-left: auto; margin-right: auto; text-align: center; }
   .underline { text-decoration: underline; }
-  #postamble p, #preamble p { font-size: 90%; margin: .2em; }
+  #keywords p, #postamble p, #preamble p { font-size: 90%; margin: .2em; }
   p.verse { margin-left: 3%; }
   pre {
     border: 1px solid #ccc;
@@ -340,6 +342,8 @@ for the JavaScript code in this tag.
     margin: 10px;
     background: #ffffcc;
   }
+  .keywords-value { font-style:normal; }
+  .keywords-prefix { font-style:italic; }
   #org-div-home-and-up
    { text-align: right; font-size: 70%; white-space: nowrap; }
   textarea { overflow-x: auto; }
@@ -720,6 +724,24 @@ The function should return the string to be exported."
   :package-version '(Org . "8.3")
   :type 'function)
 
+;;;; Keywords
+
+(defcustom org-html-keywords-prefix t
+  "Nonnil means prefix keywords.
+If the value is a string the string is used.  Otherwise the
+translation of \"Keywords\" from `org-export-dictionary' is used."
+  :group 'org-export-html
+  :type '(choice boolean string)
+  :version "25.1"
+  :package-version '(Org . "8.3"))
+
+(defcustom org-html-with-keywords t
+  "Nonnil means include keywords."
+  :group 'org-export-html
+  :version "25.1"
+  :package-version '(Org . "8.3")
+  :type 'boolean)
+
 ;;;; LaTeX
 
 (defcustom org-html-with-latex org-export-with-latex
@@ -2571,6 +2593,25 @@ CONTENTS is nil.  INFO is a plist holding contextual information."
 	(value (org-element-property :value keyword)))
     (cond
      ((string= key "HTML") value)
+     ((and (string= key "KEYWORDS")
+	   (plist-get info :with-keywords))
+      (format "<p div=\"keywords\">%s%s\n</p>"
+	      (let ((prefix (plist-get :keywords-prefix info)))
+		(if prefix 
+		    (format
+		     "<span class=\"keywords-prefix\">%s</span> "
+		     (if (stringp prefix) prefix
+		       (concat (org-export-translate "Keywords" :html info) ":")))
+		  ""))
+	      ;; TODO: there should be a possibility to automatically
+	      ;; add hrefs so each keyword.  Like a blog...  Perhaps
+	      ;; this should just call a function on each keyword.
+	      ;; Further, I guess the correct "semantic" way would be
+	      ;; to print it as a oneline list.  However, then we
+	      ;; would need to make assumptions on how to split
+	      ;; values.  Both comma and space makes sense for this.
+	      (format "<span class=\"keywords-value\">%s</span>"
+		      (org-export-data value info))))
      ((string= key "TOC")
       (let ((case-fold-search t))
 	(cond
diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index f3c47dc..1d9475c 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -132,6 +132,7 @@
     (:latex-inactive-timestamp-format nil nil org-latex-inactive-timestamp-format)
     (:latex-inline-image-rules nil nil org-latex-inline-image-rules)
     (:latex-link-with-unknown-path-format nil nil org-latex-link-with-unknown-path-format)
+    (:latex-keywords-template nil nil org-latex-keywords-template)
     (:latex-listings nil nil org-latex-listings)
     (:latex-listings-langs nil nil org-latex-listings-langs)
     (:latex-listings-options nil nil org-latex-listings-options)
@@ -143,6 +144,8 @@
     (:latex-text-markup-alist nil nil org-latex-text-markup-alist)
     (:latex-title-command nil nil org-latex-title-command)
     (:latex-toc-command nil nil org-latex-toc-command)
+    (:keywords-prefix nil nil org-latex-keywords-prefix)
+    (:with-keywords nil "keywords" org-latex-with-keywords)
     ;; Redefine regular options.
     (:date "DATE" nil "\\today" t)))
 
@@ -538,15 +541,40 @@ and resolve links into section references."
   :type 'string)
 
 
-;;;; Links
+;;;; Keywords
 
-(defcustom org-latex-image-default-option ""
-  "Default option for images."
+(defcustom org-latex-with-keywords nil
+  "Nonnil means that keywords are included in the output.
+When nil, keywords are not exported.  This option can also be set
+with the OPTIONS keyword, e.g.  \"keywords:nil\"."
   :group 'org-export-latex
-  :version "24.4"
-  :package-version '(Org . "8.0")
+  :type 'boolean
+  :version "25.1"
+  :package-version '(Org . "8.3"))
+
+(defcustom org-latex-keywords-prefix t
+  "Nonnil means prefix keywords.
+If the value is a string the string is used.  Otherwise the
+translation of \"Keywords\" from `org-export-dictionary' is used.
+See also `org-latex-keywords-template'."
+  :group 'org-export-latex
+  :type '(choice boolean string)
+  :version "25.1"
+  :package-version '(Org . "8.3"))
+
+(defcustom org-latex-keywords-template "\\par\\smallskip\n\\noindent{{\\itshape %s} %s}\n"
+  "Template used for printed keywords.
+Should contain two \"%s\"-expressions.  The first is set
+according to org-latex-keywords-prefix and the second with the
+value of the keywords."
+  :group 'org-export-latex
+  :version "25.1"
+  :package-version '(Org . "8.3")
   :type 'string)
 
+
+;;;; Links
+
 (defcustom org-latex-image-default-width ".9\\linewidth"
   "Default width for images.
 This value will not be used if a height is provided."
@@ -1821,6 +1849,15 @@ CONTENTS is nil.  INFO is a plist holding contextual information."
     (cond
      ((string= key "LATEX") value)
      ((string= key "INDEX") (format "\\index{%s}" value))
+     ((and (string= key "KEYWORDS")
+	   (plist-get info :with-keywords))
+      (format (plist-get info :latex-keywords-template)
+	      (let ((prefix (plist-get info :keywords-prefix)))
+		(cond ((stringp prefix) prefix)
+		      (prefix
+		       (concat (org-export-translate "Keywords" nil info) ":"))
+		      (t "")))
+	      (org-export-data value info)))
      ((string= key "TOC")
       (let ((case-fold-search t))
 	(cond
diff --git a/lisp/ox-odt.el b/lisp/ox-odt.el
index dd3020e..fee83ec 100644
--- a/lisp/ox-odt.el
+++ b/lisp/ox-odt.el
@@ -113,7 +113,9 @@
     (:odt-table-styles nil nil org-odt-table-styles)
     (:odt-use-date-fields nil nil org-odt-use-date-fields)
     ;; Redefine regular option.
-    (:with-latex nil "tex" org-odt-with-latex)))
+    (:with-latex nil "tex" org-odt-with-latex)
+    (:keywords-prefix nil nil org-odt-keywords-prefix)
+    (:with-keywords nil "keywords" org-odt-with-keywords)))
 
 
 ;;; Dependencies
@@ -747,6 +749,23 @@ t              Synonym for `mathjax'."
 	  (const :tag "Use MathJax to display math" mathjax)
 	  (const :tag "Leave math verbatim" verbatim)))
 
+;;;; Keywords
+
+(defcustom org-odt-keywords-prefix t
+  "Nonnil means prefix keywords.
+If the value is a string the string is used.  Otherwise the
+translation of \"Keywords\" from `org-export-dictionary' is used."
+  :group 'org-odt-latex
+  :type '(choice boolean string)
+  :version "25.1"
+  :package-version '(Org . "8.3"))
+
+(defcustom org-odt-with-keywords nil
+  "Nonnil means include keywords."
+  :group 'org-export-odt
+  :version "25.1"
+  :package-version '(Org . "8.3")
+  :type 'boolean)
 
 ;;;; Links
 
@@ -2030,6 +2049,19 @@ information."
      ((string= key "INDEX")
       ;; FIXME
       (ignore))
+     ((and (string= key "KEYWORDS")
+	   (plist-get info :with-keywords))
+      (format "<text:p>%s%s\n</text:p>\n"
+	      (let ((prefix (plist-get info ::keywords-prefix)))
+		(if prefix
+		    (format "<text:span text:style-name=\"%s\">%s</text:span>: "
+			    "OrgKeywordsPrefix"
+			    (if (stringp prefix) prefix
+			      (org-export-translate "Keywords" nil info)))
+		  ""))
+	      (format "<text:span text:style-name=\"%s\">%s</text:span>"
+		      "OrgKeywords"
+		      (org-export-data value info))))
      ((string= key "TOC")
       (let ((case-fold-search t))
 	(cond
diff --git a/lisp/ox.el b/lisp/ox.el
index 213e56d..af12216 100644
--- a/lisp/ox.el
+++ b/lisp/ox.el
@@ -5433,6 +5433,11 @@ them."
       :utf-8 "Примітки")
      ("zh-CN" :html "&#33050;&#27880;" :utf-8 "脚注")
      ("zh-TW" :html "&#33139;&#35387;" :utf-8 "腳註"))
+    ("Keywords"
+     ("da" :default "Nøgleord")
+     ("de" :default "Schlüsselworter")
+     ("se" :default "Nyckelord")
+     ("no" :default "Nøkkelord"))
     ("List of Listings"
      ("da" :default "Programmer")
      ("de" :default "Programmauflistungsverzeichnis")
-- 
2.3.2

Re: [ox, patch] Keywords & what should go in ox?

[Nicolas Goaziou]

Hello,

Rasmus <rasmus@gmx.us> writes:

> First, as discussed a while back we want to move DESCRIPTION and KEYWORDS
> out of ox.el as they are specific to certain backends.  The first patch
> does this.

Thanks.

You can remove the keywords from "ox-org.el" and "ox-ascii.el", as they
do not use them. You need to update (info "(org)Publishing options")
accordingly, too.

> Second, I want to add support for printing keywords.  This patch is still
> rough (i.e. no need commenting), but before proceeding I want to discuss
> some things.  The goal is to allow cool stuff like:
>
>    #+begin_abstract
>      Read my paper, please...
>      #+keywords: org, markup
>    #+end_abstract
>
> And eventually:
>
>    #+tile: my fancy blog
>    #+keywords: org, markup
>
> Where 'org' and 'markup' would magically become links to indexes (like on
> them fancy blogs on the interwebs).  I'm still not sure how to do the
> latter (see TODO comment in patch).

I fail to see how it is "cool". KEYWORDS are meant to add contents to
meta-data, i.e., an area you cannot reach easily with regular Org
syntax. As a consequence, KEYWORDS doesn't mean much for back-ends not
supporting such meta-data.

If KEYWORDS are meant to be inserted in the buffer, then write them
using regular syntax, e.g.,

  #+begin_abstract
  Read my paper, please...

  Keywords-in-my-language: [[http://link-to-tag-cloud][org]]
  #+end_abstract

We don't need a convoluted markup for that, let's keep it simple.


Regards,

-- 
Nicolas Goaziou

Re: [ox, patch] Keywords & what should go in ox?

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> We don't need a convoluted markup for that, let's keep it simple.

But then you'd have to repeat data.  E.g.

#+KEYWORDS: my keywords for meta-data that should also be printed.
my keywords for meta-data that should also be printed.

This seems error prone and undesirable IMO.

—Rasmus

-- 
El Rey ha muerto. ¡Larga vida al Rey!

Re: [ox, patch] Keywords & what should go in ox?

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>> We don't need a convoluted markup for that, let's keep it simple.
>
> But then you'd have to repeat data.  E.g.
>
> #+KEYWORDS: my keywords for meta-data that should also be printed.
> my keywords for meta-data that should also be printed.
>
> This seems error prone and undesirable IMO.

Except that this is not a real repetition. As you mentioned, in the
latter case, you want to throw in links and probably other markup, which
make no sense in plain meta-data.

IMO, this is over-engineering.


Regards,

Re: [ox, patch] Keywords & what should go in ox?

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Rasmus <rasmus@gmx.us> writes:
>
>> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>>
>>> We don't need a convoluted markup for that, let's keep it simple.
>>
>> But then you'd have to repeat data.  E.g.
>>
>> #+KEYWORDS: my keywords for meta-data that should also be printed.
>> my keywords for meta-data that should also be printed.
>>
>> This seems error prone and undesirable IMO.
>
> Except that this is not a real repetition. As you mentioned, in the
> latter case, you want to throw in links and probably other markup, which
> make no sense in plain meta-data.

Keywords are akin to small headings to identify the contents of a
document.  I see no reason to restrict this to the reader of the
electronic version of a document.

> IMO, this is over-engineering.

I disagree, but extrapolating this will go nowhere.

—Rasmus

-- 
Got mashed potatoes. Ain't got no T-Bone. No T-Bone

Re: [ox, patch] Keywords & what should go in ox?

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> Keywords are akin to small headings to identify the contents of a
> document.  I see no reason to restrict this to the reader of the
> electronic version of a document.

What are you talking about? I don't want to restrict anything: AFAIU,
the feature you propose already exists in another form.

Again, your proposal is to have KEYWORDS mix two different things, i.e.,
set meta-data in document's header and set contents in the document. My
opinion is that for a given topic, you probably don't always want the
same contents, e.g., in "\\hyperref{pdfkeywords={...}}" and at the
beginning of the document, if only for the limitations on the syntax
allowed in the former.

Therefore, we may consider keeping the two features separated.

Do you think that you /always/ want "pdfkeywords" to hold exactly the
same contents as what you could put in your document? Do you think that
a user who wants to fill pdfkeywords will always want to also add these
contents in the body of the document?


Regards,

Re: [ox, patch] Keywords & what should go in ox?

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Do you think that you /always/ want "pdfkeywords" to hold exactly the
> same contents as what you could put in your document?

You as in me: yes most certainly.

> Do you think that a user who wants to fill pdfkeywords will always want
> to also add these contents in the body of the document?

Which is why the patch provided a switch in #+OPTIONS.

—Rasmus

-- 
It was you, Jezebel, it was you

Re: [ox, patch] Keywords & what should go in ox?

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>> Do you think that you /always/ want "pdfkeywords" to hold exactly the
>> same contents as what you could put in your document?
>
> You as in me: yes most certainly.

IIUC, it contradicts your initial post where you wanted, at some later
time, to add bells and whistles to keywords displayed in the output
(e.g., turning them into links).

I'm not very keen on the idea of KEYWORD doing two different things. If
that's not the case, I'm fine with it.

>> Do you think that a user who wants to fill pdfkeywords will always want
>> to also add these contents in the body of the document?
>
> Which is why the patch provided a switch in #+OPTIONS.

The switch is all or nothing. Again, you're talking about two different
features : keywords in meta-data and keywords in data.


Regards,

Re: [ox, patch] Keywords & what should go in ox?

[Rasmus]

Hi,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

>> First, as discussed a while back we want to move DESCRIPTION and KEYWORDS
>> out of ox.el as they are specific to certain backends.  The first patch
>> does this.
>
> [...] You need to update (info "(org)Publishing options") accordingly,
> too.

I have now reviewed this section twice, and I have no clue what you want
me to change there.  There's no :with-keywords or :with-description.  At
least SUBTITLE for ox-texinfo in not documented here.

—Rasmus

-- 
Enough with the bla bla!

Re: [ox, patch] Keywords & what should go in ox?

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> I have now reviewed this section twice, and I have no clue what you want
> me to change there. There's no :with-keywords or :with-description.

I don't know either. I was sure that :keywords and :description were
here, but, oddly, it isn't the case. That's a documentation bug as long
as these keywords are in "ox.el".

> At least SUBTITLE for ox-texinfo in not documented here.

That's also a documentation bug. Note that it should probably
be :texinfo-subtitle (and :texinfo-subauthor).


Regards,

Re: [ox, patch] Keywords & what should go in ox?

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

>> I have now reviewed this section twice, and I have no clue what you want
>> me to change there. There's no :with-keywords or :with-description.
>
> I don't know either. I was sure that :keywords and :description were
> here, but, oddly, it isn't the case. That's a documentation bug as long
> as these keywords are in "ox.el".

By this logic we'd have to add *every* "global" keyword, no?  Does it make
sense?

>> At least SUBTITLE for ox-texinfo in not documented here.
>
> That's also a documentation bug. Note that it should probably
> be :texinfo-subtitle (and :texinfo-subauthor).

Unless we add a #+SUBTITLE...

So should I go ahead a kill KEYWORD and DESCRIPTION in ox?

—Rasmus

-- 
Lasciate ogni speranza o voi che entrate: siete nella mani di'machellaio

Re: [ox, patch] Keywords & what should go in ox?

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> By this logic we'd have to add *every* "global" keyword, no?  Does it make
> sense?

Every global (as in "ox.el") keyword should be documented there, indeed.

>>> At least SUBTITLE for ox-texinfo in not documented here.
>>
>> That's also a documentation bug. Note that it should probably
>> be :texinfo-subtitle (and :texinfo-subauthor).
>
> Unless we add a #+SUBTITLE...

It depends. Adding a prefix allows to specify a subtitle per back-end
when publishing through multiple back-ends. Not a big deal, tho.

> So should I go ahead a kill KEYWORD and DESCRIPTION in ox?

IIUC, this is what we agreed on in the related thread.

Regards,

Re: [ox, patch] Keywords & what should go in ox?

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Rasmus <rasmus@gmx.us> writes:
>
>> By this logic we'd have to add *every* "global" keyword, no?  Does it make
>> sense?
>
> Every global (as in "ox.el") keyword should be documented there, indeed.

OK.

Marc: you expressed a desire to fix some bugs.  I don't know if you like
documentation bugs, or whether you are more into code bugs.  If you like
documentation, would that be something you'd want to do?

>>>> At least SUBTITLE for ox-texinfo in not documented here.
>>>
>>> That's also a documentation bug. Note that it should probably
>>> be :texinfo-subtitle (and :texinfo-subauthor).
>>
>> Unless we add a #+SUBTITLE...
>
> It depends. Adding a prefix allows to specify a subtitle per back-end
> when publishing through multiple back-ends. Not a big deal, tho.

It would make it hard to set *a* subtitle through publishing.  As a user I
don't care about the implementation detail and I would prefer :subtitle
(should I ever need to specify a subtitle via publishing).

—Rasmus

-- 
Slowly unravels in a ball of yarn and the devil collects it

Re: [ox, patch] Keywords & what should go in ox?

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Rasmus <rasmus@gmx.us> writes:
>
>> By this logic we'd have to add *every* "global" keyword, no?  Does it make
>> sense?
>
> Every global (as in "ox.el") keyword should be documented there, indeed.

For now I have not moved the documentation as I'm not sure we know where
to put it yet.

>> So should I go ahead a kill KEYWORD and DESCRIPTION in ox?
>
> IIUC, this is what we agreed on in the related thread.

This is pushed now in 79c0aa21ca2657f2ea7272040bce3ff4754bab1b.

—Rasmus

-- 
Evidence suggests Snowden used a powerful tool called monospaced fonts