emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Rasmus <rasmus@gmx.us>
To: emacs-orgmode@gnu.org
Subject: [org.texi] New keywords tables (was: [ox, patch] #+SUBTITLE)
Date: Tue, 31 Mar 2015 17:50:30 +0200	[thread overview]
Message-ID: <87lhidi2t5.fsf_-_@gmx.us> (raw)
In-Reply-To: <87vbhhxx3c.fsf@nicolasgoaziou.fr> (Nicolas Goaziou's message of "Tue, 31 Mar 2015 12:47:19 +0200")

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

Hi,

Following this discussion:

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
> Rasmus <rasmus@gmx.us> writes:

>> OK.  So with the above the in mind the game plan [for documentation]
>> seems to be:
>>
>>      - Remove DESCRIPTION/KEYWORD from it's current position in org.texi
>>        to backend descriptions and retain them in relevant backends.
>
> Correct.
>
>>        This imply some repetition, but also allows greater details,
>>        e.g. with latex we can point to the hyperref template.
>
> Indeed.

An example of a structure change is attached.  It introduces a table
similar to @ref{Export settings} in the beginning of most backend
chapters.

I have not (re)read it yet, but I want to make sure that we roughly agree
on the structure before I put more time into it.  It does not touch
texinfo (yet) 'cause it's complicated.

WDYT?

Also I would kill all backend specific keywords from the table in "@node
In-buffer settings":

    @itemx #+LATEX_HEADER:, #+LATEX_HEADER_EXTRA:,
    @itemx #+HTML_HEAD:, #+HTML_HEAD_EXTRA:, #+HTML_LINK_UP:, #+HTML_LINK_HOME:,
    @itemx #+ODT_STYLES_FILE:,

It does not contain all HTML KW or any Beamer KW.  IOW it's a mess and the
true picture here would be ugly.

WDYT?

—Rasmus

-- 
However beautiful the theory, you should occasionally look at the evidence

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0002-org.texi-Introduce-tables-for-backend-keywords.patch --]
[-- Type: text/x-diff, Size: 9391 bytes --]

From 406fec4af53607a78d56d278389a8821d9d91f1c Mon Sep 17 00:00:00 2001
From: Rasmus <rasmus@gmx.us>
Date: Tue, 31 Mar 2015 17:37:48 +0200
Subject: [PATCH 2/2] org.texi: Introduce tables for backend keywords

---
 doc/org.texi | 176 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 163 insertions(+), 13 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index ffaa281..1780b33 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -9707,7 +9707,7 @@ The title of the exported document is taken from the special line
 
 @cindex #+TITLE
 @example
-#+TITLE: This is the title of the document
+#+: This is the title of the document
 @end example
 
 @cindex property, EXPORT_TITLE
@@ -11092,21 +11092,49 @@ Beamer back-end is an extension of @LaTeX{} back-end.  As such, all @LaTeX{}
 specific syntax (e.g., @samp{#+LATEX:} or @samp{#+ATTR_LATEX:}) is
 recognized.  See @ref{@LaTeX{} and PDF export} for more information.
 
+Beamer export introduces a number of keywords, similar to the general options
+settings described in @pxref{Export settings}.
+
+@table @samp
+@item BEAMER_THEME
 @cindex #+BEAMER_THEME
-@cindex #+BEAMER_COLOR_THEME
+@vindex org-beamer-theme
+The Beamer theme (@code{org-beamer-theme}).  See chapter 15 in the Beamer
+manual.
+
+@item BEAMER_FONT_THEME
 @cindex #+BEAMER_FONT_THEME
+The Beamer font theme.  See chapter 18 in the Beamer manual.
+
+@item BEAMER_INNER_THEME
 @cindex #+BEAMER_INNER_THEME
+The Beamer inner theme.  See chapter 16 in the Beamer manual.
+
+@item BEAMER_OUTER_THEME
 @cindex #+BEAMER_OUTER_THEME
-Beamer export introduces a number of keywords to insert code in the
-document's header.  Four control appearance of the presentation:
-@code{#+BEAMER_THEME}, @code{#+BEAMER_COLOR_THEME},
-@code{#+BEAMER_FONT_THEME}, @code{#+BEAMER_INNER_THEME} and
-@code{#+BEAMER_OUTER_THEME}.  All of them accept optional arguments within
-square brackets.  The last one, @code{#+BEAMER_HEADER}, is more generic and
-allows you to append any line of code in the header@footnote{Lines are
-appended at the end of the preamble, allowing for any final customization
-such as the inclusion of short titles.}.
+The Beamer outer theme.  See chapter 16 in the Beamer manual.
+
+@c This one is probably not needed
+@item BEAMER_HEADER
+@cindex #+BEAMER_HEADER
+Arbitrary lines appended to the end of the preamble of the document.
+
+@item DESCRIPTION
+@cindex #+DESCRIPTION (Beamer)
+The document description.  By default these are inserted as metadata using
+hyperref.  You can use several such keywords if the list is long.  See also
+@code{org-latex-hyperref-template} and @code{org-latex-title-command}.
 
+@item KEYWORDS
+@cindex #+KEYWORDS (Beamer)
+The keywords defining the contents of the document.  By default these are
+inserted as metadata using hyperref.  You can use several such keywords if
+the list is long.  See also @code{org-latex-hyperref-template} and
+@code{org-latex-title-command}.
+@end table
+
+This example illustrates how to change the theme.  Note that theme options
+can be specified in square brackets.
 @example
 #+BEAMER_THEME: Rochester [height=20pt]
 #+BEAMER_COLOR_THEME: spruce
@@ -11219,6 +11247,7 @@ HTML formatting, in ways similar to John Gruber's @emph{markdown}
 language, but with additional support for tables.
 
 @menu
+* HTML specific syntax::        Special keywords for HTML export.
 * HTML Export commands::        How to invoke HTML export
 * HTML doctypes::               Org can export to various (X)HTML flavors
 * HTML preamble and postamble::  How to insert a preamble and a postamble
@@ -11232,6 +11261,61 @@ language, but with additional support for tables.
 * JavaScript support::          Info and Folding in a web browser
 @end menu
 
+@node HTML specific syntax
+
+HTML export introduces a number of keywords, similar to the general options
+settings described in @pxref{Export settings}.
+
+@table @samp
+@item DESCRIPTION
+@cindex #+DESCRIPTION (HTML)
+The document description.  This description is inserted as a HTML meta tag.
+You can use several such keywords if the list is long.
+
+@item HTML_DOCTYPE
+@cindex #+HTML_DOCTYPE
+The document type (e.g. HTML5) (@code{org-html-doctype}).
+
+@item HTML_CONTAINER
+@cindex #+HTML_CONTAINER
+The contrainer used to wrap element (@code{org-html-container-element}).
+
+@item HTML_LINK_HOME
+@cindex #+HTML_LINK_HOME
+The URL of the home link (@code{org-html-link-home}).
+
+@item HTML_LINK_UP
+@cindex #+HTML_LINK_UP
+The URL of the up link (@code{org-html-link-up}).
+
+@item HTML_MATHJAX
+@cindex #+HTML_MATHJAX
+Options for MathJax (@code{org-html-mathjax-options}).  See also
+@code{org-html-mathjax-template}.
+
+@item HTML_HEAD
+@cindex #+HTML_HEAD
+Arbitrary lines appended to the end of the header of the document
+(@code{org-html-head}).
+
+@item HTML_HEAD_EXTRA
+@cindex #+HTML_HEAD_EXTRA
+Arbitrary lines appended to the end of the header of the document
+(@code{org-html-head-extra}).
+
+@item KEYWORDS
+@cindex #+KEYWORDS (HTML)
+The keywords defining the contents of the document.  This description is
+inserted as a HTML meta tag.  You can use several such keywords if the list
+is long.
+
+@item LATEX_HEADER
+@cindex #+LATEX_HEADER (HTML)
+used when transcoding e.g. math formulas to images.
+@end table
+
+These keywords are treated in details in the following sections.
+
 @node HTML Export commands
 @subsection HTML export commands
 
@@ -11755,12 +11839,54 @@ nested footnotes, footnotes in tables and footnotes in a list item's
 description.
 
 @menu
+* @LaTeX{} specific syntax::    Special keywords for @LaTeX{} export
 * @LaTeX{} export commands::    How to export to LaTeX and PDF
 * Header and sectioning::       Setting up the export file structure
 * Quoting @LaTeX{} code::       Incorporating literal @LaTeX{} code
 * @LaTeX{} specific attributes::  Controlling @LaTeX{} output
 @end menu
 
+@subsection @LaTeX{} specific syntax
+The @LaTeX{} exporter introduces a number of keywords, similar to the general
+options settings described in @pxref{Export settings}.
+
+@table @samp
+@item DESCRIPTION
+@cindex #+DESCRIPTION (@LaTeX)
+The document description.  By default these are inserted as metadata using
+hyperref.  You can use several such keywords if the list is long.  See also
+@code{org-latex-hyperref-template} and @code{org-latex-title-command}.
+
+@item LATEX_CLASS
+@cindex #+LATEX_CLASS
+The predefined preamble to use (@code{org-latex-default-class}).  The
+preamble must be an element in @code{org-latex-classes}.
+
+@item LATEX_CLASS_OPTIONS
+@cindex #+LATEX_CLASS_OPTIONS
+Options given to the @LaTeX{} document class.
+
+@item LATEX_HEADER
+@cindex #+LATEX_HEADER
+Arbitrary lines added to the preamble of the document, before the hyperref
+settings.  See also @code{org-latex-classes}.
+
+@item LATEX_HEADER_EXTRA
+@cindex #+LATEX_HEADER_EXTRA
+Arbitrary lines added to the preamble of the document, before the hyperref
+settings.  See also @code{org-latex-classes}.
+
+@item KEYWORDS
+@cindex #+KEYWORDS (@LaTeX)
+The keywords defining the contents of the document.  By default these are
+inserted as metadata using hyperref.  You can use several such keywords if
+the list is long.  See also @code{org-latex-hyperref-template} and
+@code{org-latex-title-command}.
+@end table
+
+These keywords are treated in details in the following sections.
+
+
 @node @LaTeX{} export commands
 @subsection @LaTeX{} export commands
 
@@ -12187,6 +12313,7 @@ are compatible with LibreOffice 3.4.
 
 @menu
 * Pre-requisites for ODT export::  What packages ODT exporter relies on
+* ODT specific syntax::         Specific keywords for ODT export
 * ODT export commands::         How to invoke ODT export
 * Extending ODT export::        How to produce @samp{doc}, @samp{pdf} files
 * Applying custom styles::      How to apply custom styles to the output
@@ -12199,6 +12326,29 @@ are compatible with LibreOffice 3.4.
 * Advanced topics in ODT export::  Read this if you are a power user
 @end menu
 
+@subsection ODT specific syntax
+The ODT exporter introduces a number of keywords, similar to the general
+options settings described in @pxref{Export settings}.  The keywords are
+treated in details in the following sections.
+
+@table @samp
+@item DESCRIPTION
+@cindex #+DESCRIPTION (ODT)
+The document description.  These are inserted as document metadata.  You can
+use several such keywords if the list is long.
+
+@item KEYWORDS
+@cindex #+KEYWORDS (ODT)
+The keywords defining the contents of the document.  These are inserted as
+document metadata.  You can use several such keywords if the list is long.
+
+@item ODT_STYLES_FILE
+@cindex ODT_STYLES_FILE
+The style file of the document (@code{org-odt-styles-file}).
+@end table
+
+These keywords are treated in details in the following sections.
+
 @node Pre-requisites for ODT export
 @subsection Pre-requisites for ODT export
 @cindex zip
@@ -12425,7 +12575,7 @@ desired image file with no link description.  For example, to embed
 [[file:img.png]]
 @end example
 
-@example
+@exampl
 [[./img.png]]
 @end example
 
@@ -13144,7 +13294,7 @@ including DocBook.}.
 @end table
 
 @node Document preamble
-@subsection Document preamble
+@subsection Texinfo specific syntax
 
 When processing a document, @samp{texinfo} back-end generates a minimal file
 header along with a title page, a copyright page, and a menu.  You control
-- 
2.3.4


  reply	other threads:[~2015-03-31 15:50 UTC|newest]

Thread overview: 26+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2015-03-27 14:19 [ox, patch] #+SUBTITLE Rasmus
2015-03-27 15:08 ` Andreas Leha
2015-03-27 15:12   ` Rasmus
2015-03-27 15:35     ` Andreas Leha
2015-03-28 15:40 ` Nicolas Goaziou
2015-03-28 15:55   ` Rasmus
2015-03-28 17:15     ` Thomas S. Dye
2015-03-29  9:44     ` Nicolas Goaziou
2015-03-29 11:50       ` Rasmus
2015-03-29 13:05         ` Nicolas Goaziou
2015-03-29 13:13           ` Rasmus
2015-03-30  7:39             ` Nicolas Goaziou
2015-03-30 10:35               ` Rasmus
2015-03-31 10:18                 ` Nicolas Goaziou
2015-03-31 10:35                   ` Rasmus
2015-03-31 10:47                     ` Nicolas Goaziou
2015-03-31 15:50                       ` Rasmus [this message]
2015-03-31 20:33                         ` [org.texi] New keywords tables Nicolas Goaziou
2015-03-31 21:57                           ` Rasmus
2015-04-01 11:53                           ` Rasmus
2015-04-01 19:37                             ` Nicolas Goaziou
2015-04-01 21:55                               ` Rasmus
2015-04-01 22:34                       ` [ox, patch] #+SUBTITLE Rasmus
2015-04-08 21:25                         ` Rasmus
2015-03-29 11:16   ` Rasmus
2015-03-31 10:21     ` Nicolas Goaziou

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87lhidi2t5.fsf_-_@gmx.us \
    --to=rasmus@gmx.us \
    --cc=emacs-orgmode@gnu.org \
    --subject='Re: [org.texi] New keywords tables (was: [ox, patch] #+SUBTITLE)' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this inbox:

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).