From d419f00f5aa05b2f6f7fb4d5f71bf05ca96b8bfa Mon Sep 17 00:00:00 2001 From: Nicolas Goaziou Date: Sun, 7 Apr 2013 01:49:12 +0200 Subject: [PATCH 1/3] org.texi: Update documentation wrt to captions --- doc/org.texi | 37 ++++++++++++++++++++----------------- 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index c028208de..86d8d5af8 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -547,7 +547,7 @@ Custom agenda views Markup for rich export * Structural markup elements:: The basic structure as seen by the exporter -* Images and tables:: Tables and Images will be included +* Images and tables:: Images, tables and caption mechanism * Literal examples:: Source code examples with special formatting * Include files:: Include additional files into a document * Index entries:: Making an index @@ -3381,9 +3381,9 @@ completions.}. During export, internal links will be used to mark objects and assign them a number. Marked objects will then be referenced by links pointing to them. In particular, links without a description will appear as the number assigned -to the marked object@footnote{When targetting a @code{#+NAME} keyword, -@code{#+CAPTION} keyword is mandatory in order to get proper numbering.}. In -the following excerpt from an Org buffer +to the marked object@footnote{When targeting a @code{#+NAME} keyword, +@code{#+CAPTION} keyword is mandatory in order to get proper numbering +(@pxref{Images and Tables}).}. In the following excerpt from an Org buffer @example - one item @@ -9549,45 +9549,48 @@ Toggle the COMMENT keyword at the beginning of an entry. @cindex tables, markup rules @cindex #+CAPTION -@cindex #+LABEL +@cindex #+NAME Both the native Org mode tables (@pxref{Tables}) and tables formatted with the @file{table.el} package will be exported properly. For Org mode tables, the lines before the first horizontal separator line will become table header lines. You can use the following lines somewhere before the table to assign a caption and a label for cross references, and in the text you can refer to -the object with @code{\ref@{tab:basic-data@}}: +the object with @code{[[tab:basic-data]]} (@pxref{Internal links}): @example #+CAPTION: This is the caption for the next table (or link) -#+LABEL: tab:basic-data +#+NAME: tab:basic-data | ... | ...| |-----|----| @end example Optionally, the caption can take the form: @example -#+CAPTION: [Caption for list of figures]@{Caption for table (or link).@} +#+CAPTION[Caption for list of tables]: Caption for table. @end example @cindex inlined images, markup rules -Some backends (HTML and @LaTeX{}) allow you to directly include images into -the exported document. Org does this, if a link to an image files does not -have a description part, for example @code{[[./img/a.jpg]]}. If you wish to +Some backends allow you to directly include images into the exported +document. Org does this, if a link to an image files does not have +a description part, for example @code{[[./img/a.jpg]]}. If you wish to define a caption for the image and maybe a label for internal cross references, make sure that the link is on a line by itself and precede it -with @code{#+CAPTION} and @code{#+LABEL} as follows: +with @code{#+CAPTION} and @code{#+NAME} as follows: @example #+CAPTION: This is the caption for the next figure link (or table) -#+LABEL: fig:SED-HR4049 +#+NAME: fig:SED-HR4049 [[./img/a.jpg]] @end example -You may also define additional attributes for the figure. As this is -backend-specific, see the sections about the individual backends for more -information. +@noindent +Such images can be displayed within the buffer. @xref{Handling links,the +discussion of image links}. -@xref{Handling links,the discussion of image links}. +Even though images and tables are prominent examples of captioned structures, +the same caption mechanism can apply to many others (e.g., @LaTeX{} +equations, source code blocks). Depending on the export back-end, those may +or may not be handled. @node Literal examples, Include files, Images and tables, Markup @section Literal examples From e1a9b5fb32e7ef8a5bff1599de7460ecd3cd3730 Mon Sep 17 00:00:00 2001 From: Nicolas Goaziou Date: Sun, 7 Apr 2013 10:00:16 +0200 Subject: [PATCH 2/3] org.texi: Fix typo in commit d419f00f5aa05b2f6f7fb4d5f71bf05ca96b8bfa --- doc/org.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/org.texi b/doc/org.texi index 86d8d5af8..b2b41660c 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -3383,7 +3383,7 @@ a number. Marked objects will then be referenced by links pointing to them. In particular, links without a description will appear as the number assigned to the marked object@footnote{When targeting a @code{#+NAME} keyword, @code{#+CAPTION} keyword is mandatory in order to get proper numbering -(@pxref{Images and Tables}).}. In the following excerpt from an Org buffer +(@pxref{Images and tables}).}. In the following excerpt from an Org buffer @example - one item From 86815fc4e531227368548018d325cc7f3f986293 Mon Sep 17 00:00:00 2001 From: Nicolas Goaziou Date: Sun, 7 Apr 2013 10:08:09 +0200 Subject: [PATCH 3/3] orgguide.texi: Update documentation wrt captions --- doc/orgguide.texi | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/doc/orgguide.texi b/doc/orgguide.texi index ab9664180..6306ab5e2 100644 --- a/doc/orgguide.texi +++ b/doc/orgguide.texi @@ -2090,7 +2090,7 @@ summarizes the markup rules used in an Org-mode buffer. @menu * Structural markup elements:: The basic structure as seen by the exporter -* Images and tables:: Tables and Images will be included +* Images and tables:: Images, tables and caption mechanism * Literal examples:: Source code examples with special formatting * Include files:: Include additional files into a document * Embedded @LaTeX{}:: @LaTeX{} can be freely used inside Org documents @@ -2211,32 +2211,30 @@ Toggle the COMMENT keyword at the beginning of an entry. For Org mode tables, the lines before the first horizontal separator line will become table header lines. You can use the following lines somewhere before the table to assign a caption and a label for cross references, and in -the text you can refer to the object with @code{\ref@{tab:basic-data@}}: +the text you can refer to the object with @code{[[tab:basic-data]]}: @smallexample #+CAPTION: This is the caption for the next table (or link) -#+LABEL: tbl:basic-data +#+NAME: tbl:basic-data | ... | ...| |-----|----| @end smallexample -Some backends (HTML, @LaTeX{}, and DocBook) allow you to directly include -images into the exported document. Org does this, if a link to an image -files does not have a description part, for example @code{[[./img/a.jpg]]}. -If you wish to define a caption for the image and maybe a label for internal -cross references, you sure that the link is on a line by itself precede it -with: +Some backends allow you to directly include images into the exported +document. Org does this, if a link to an image files does not have +a description part, for example @code{[[./img/a.jpg]]}. If you wish to +define a caption for the image and maybe a label for internal cross +references, you sure that the link is on a line by itself precede it with: @smallexample #+CAPTION: This is the caption for the next figure link (or table) -#+LABEL: fig:SED-HR4049 +#+NAME: fig:SED-HR4049 [[./img/a.jpg]] @end smallexample -You may also define additional attributes for the figure. As this is -backend-specific, see the sections about the individual backends for more -information. - +The same caption mechanism applies to other structures than images and tables +(e.g., @LaTeX{} equations, source code blocks), provided the chosen export +back-end supports them. @node Literal examples, Include files, Images and tables, Markup @section Literal examples