This patch introduces more hooks for preprocessing the export buffer,
at various strategic moments. See the Changes.org file for a
description of the hooks.
Org-mode allows multiple references to the same footnote. However,
the HTML exporter cannot use the same name for all these references,
because names have to be unique. This patch appends numbers to
footnote reference names, to make sure they remain unique.
The dark side of this patch means that from the footnote definition,
there is only a single link, to the first reference of the note.
However, in a browser you can always press BACK to go back after
jumping to a footnote definition.
This patch covers the three main backends, html, latex, and ascii. It
adds the code to make sure the coderef links identified by the
preprocessing will be implemented correctly when a backend does its work.
This patch covers the much of the new line numbering and code line
referencing.
We introduce a new function with the longish name
`org-export-replace-src-segments-and-examples'. It is an extension of
the earlier `org-export-replace-src-segments'. It now also covers
EXAMPLE blocks, not only source code blocks. This was necessary to
allow line numbering also in EXAMPLE blocks.
Both clock types now accept a string with options which will be given
in the BEGIN line. Options currently recognized are -n, +n, and -r.
A bit unsatisfactory about this patch may be that LaTeX-specific code
is now defined in org-exp.el, maybe eventually we want to think of a
way to move this code back to org-export-latex.el. Really, all it
does is adding line numbers and wrapping them into a verbatim
environment.
Besides adding line numbers in a backend specific way, this patch also
adds code to search or special cookies in source code, like "((1))" or
"((name))". These are labels that can be addressed by links as
references to specific line in source code.
This patch adds a new constant with javascript functions. Each
exported HTML file will contain these definitions. Also, we add to
the default export CSS style a new class, code-highlighted, which will
be used to highlight lines in code whenever the mouse overs over a
link to this line.
Unique identifiers for entries can now be used more efficiently.
Internally, a hash array has replaced the alist used so far to
keep track of the files in which an ID is defined. This makes it
quite fast to find an entry by ID.
There is now a new link type which looks like this:
id:GLOBALLY-UNIQUE-IDENTIFIER
This link points to a specific entry. When you move the entry to
a different file, for example if you move it to an archive
file, this link will continue to work.
The file /org-id.el/ contains an API that can be used to write
code using these identifiers, including creating IDs and finding
them wherever they are.
Org has its own method to create unique identifiers, but if the
system has /uuidgen/ command installed (Mac's and Linux systems
generally do), it will be used by default. You an also select
the method by hand, using the variable =org-id-method=.
If the ID system ever gets confused about where a certain ID is,
it initiates a global scan of all agenda files with associated
archives, all files previously known containing any IDs, and all
currently visited Org-mode files to rebuild the hash. You can
also initiate this by hand: =M-x org-id-update-id-locations=.
Running this command will also dump into the =*Messages*= buffer
information about any duplicate IDs. These should not exist, but
if you /copy/ an entry with its properties, duplicate IDs will
inevitably be produced. This is unavoidable in a plain text
system that allows you to edit the text in arbitrary ways, and a
portion of care on your side is needed to keep this system clean.
The hash is stored in the file =~/.emacs.d/.org-id-locations=.
This is also a change from previous versions where the file was
=~/.org=id-locations=. Therefore, you can remove this old file
if you have it. I am not sure what will happen if the =.emacs.d=
directory does not exists in your setup, but in modern Emacsen, I
believe it should exist. If you do not want to use IDs across
files, you can avoid the overhead with tracking IDs by
customizing the variable =org-id-track-globally=. IDs can then
still be used for links inside a single file.
IDs will also be used when you create a new link to an Org-mode
buffer. If you use =org-store-link= (normally at =C-c l=) inside
en entry in an Org-mode buffer, and ID property will be created
if it does not exist, and the stored link will be an =id:= link.
If you prefer the much less secure linking to headline text, you
can configure the variable =org-link-to-org-use-id=. The default
setting for this variable is =create-if-interactive=, meaning
that an ID will be created when you store a link interactively,
but not if you happen to be in an Org-mode file while you create
a remember note (which usually has a link to the place where you
were when starting remember).
Tables, and Hyperlinks that represent inlined images, can now be
equipped with additional information that will be used during
export. The information will be taken from the following special
lines in the buffer and apply to the first following table or
link.
- #+CAPTION: :: The caption of the image or table. This string
should be processed according to the export backend, but
this is not yet done.
- #+LABEL: :: A label to identify the figure/table for cross
references. For HTML export, this string will become the
ID for the `<div class="figure">' element that encapsulates
the image tag and the caption. For LaTeX export, this
string will be used as the argument of a `\label{...}'
macro. These lables will be available for internal links
like `[[label][Table] ]'.
- #+ATTR_HTML: :: Attributes for HTML export of image, to be
added as attributes into the `<img...>' tag. This string
will not be processed, so it should have immediately the
right format.
- #+ATTR_LaTeX: :: Attributes for LaTeX export of images, to
be inserted into the optional argument of the
`\includegraphics[...]{file}' command, to specify scaling,
clipping and other options. This string will not be
processed, so it should have immediately the right
format, like `width=5cm,angle=90'
For LaTeX export, if either a caption or a label is given, the
element will be exported as a float, i.e. wrapped into a figure
or table environment.
Xerxes Folupa writes:
> I spotted a little inconsistency in the way Org strips tags when
> processing #+begin_verse ... #+end_verse, and #+begin_quote
> ... #+end_quote blocks, compared with other literal blocks that strip
> superfluous <p> tags correctly (e.g. #+html)
[...]
> Additional question: is the space before the <br/> in verse blocks a
> design decision?
This patch fixes these issues.
It seems that CSS and Java-script stuff should be quoted in a very
strange way in order to make sure that the resulting file functions
correct in current browsers *and* validates against various XHTML and
XML standards. To be honest, the quoting technique seem really
strange, but Sebastian Rose argues, that this is the way to handle
this issue.
Harri Kiiskinen suggested that it might be useful to make the LOCATION
property an inherited property during iCalendar export. In this way
you can have set the LOCATION for a whole set of items by setting it
only in the parent.
While this will slow down iCalendar export for large files, I think it
can be quite useful. This patch does implement the basic code needed
for this functionality. However, you still need to tell Org that
LOCATION should be inherited, by setting org-use-property-inheritance.
If you set it to t, beware that this may trigger a significant
slowdown when creating the match view in the agenda. So it may be
better to set this variable to
(setq org-use-property-inheritance '("LOCATION"))
instead.
This patch improves the internal handling of the large number of
export options that Org-mode has. In particular, it now defines a
single constant, `org-export-plist-vars' that contains the full list
of options, and how these can be accessed through variables, and
through the #+OPTIONS line. Before the patch, there used to be a
separate list or the OPTIONS handling, which has gotten out of sync.
This now no longer can happen.
Also, this patch adds two new variables, `org-export-with-priority',
and `org-export-with-todo-keywords', which can be used to turn the
export of TODO keywords and priority cookies on and off, so that these
can simply disappear and not be shown in the exported file. In fact,
the default for the priority cookie is to remove it.
When the export skips the text before the first headline, we now
include the comment line before the first headline, if any.
This makes sure that we can specify an anchor for this headline.
"\\" at the end of a line marks forces line breaks for HTML and LaTeX
export. ASCII export does preserve lines anyway, but these line break
indicators might still be present and need to be removed.
Reported by Rustom Mody.
A link to an image can function as the description part of a link, to
create a clickable image. The corresponding image tag was
erroneously processed like normal text. This patch protects such
descriptions from processing.
Reported by Richard Riley.
Org allows to define invisible anchors in a document in comment lines
like
If such a line is directly before or after a headline, previously this
anchor was removed, and all references to it were replaced with
references to the anchor that the headline had anyway.
Matthew Lundin pointed out that this makes it impossible to have
permanent links to headlines that can also be used from outside the
current page.
This patch changes his situation by adding the additional targets as
empty anchors to the section heading. If works by creating, during
preprocessing, an alist with targets that do have aliases. During
publishing, these aliases are looked up and converted into anchors.
In LaTeX export, these additional targets become additional labels.
This is a bugfix. When the number of headline levels was set to zero,
or if there was no heading at all in the export, the final closing
</div> should not be present.
This patch implements the possibility to translate links.
It can be useful if use both planner and Org-mode, if you sometimes
copy text from one side to the other and you do not want to worry
about link syntax. This patch allows links created with planner to
function correctly in Org-mode. I would probably be simple to
implement the reverse conversion in planner as well.
This patch is a first shot at this functionality and very likely can
be improved.
iCalendar export has now improved compliance with RFC 2445.
Now all occurrences in data fields of the double quotes are replaced
by two single quotes, and any fields containing comma, colon, or
semicolon are quoted by surrounding them with double quotes.
Link descriptions where so far exported literally. However, really
they need to escape special characters and have TeX-like macros
interpreted and emphasis enabled just like any other text.
This patch makes sure link descriptions are passed through a new
filter, `org-export-html-format-desc' which does just that.
This fix is a follow-up to a report by Sebastian Rose.
So far, Org used either `fit-window-to-buffer' or
`shrink-window-if-larger-than-buffer' without any further checks when
displaying one of its many help and selection buffers. This can cause
problems if the user has set up Emacs to split windows horizontally
rather than vertically, because the window being shrunken then may be
side-by-side with another window, and shrinking the height of one will
also change the other.
With this patch, shrinking a window always goes through the new
function `org-fit-window-to-buffer' which only acts if the current
window spans the whole width of the frame.
Furthermore, this function also helps with compatibility, because it
falls back to `shrink-window-if-larger-than-buffer' if
`fit-window-to-buffer' does not exist, as is the case on older version
of Emacs and XEmacs.
field (or in any other attribute value) must be written as "&" in
order to be valid XHMTL. This patch implements a new filter function
through which every href value is passed, and which enforces this
standard.
This is was triggered by a report by Sebastian Rose.
Org-mode does sometimes included CSS definitions directly
into an exported XHTML file. To pass validation tests
for XHTML, these sections need to be wrapped in
order to pass as CDATA, not PCDATA. This patch
(written by Sebastian Rose) does implement this change.
It also fixes some typos.
The new default asks to open all those files in Emacs, for which
`auto-mode-alist' does contain an entry. The reasoning is that
Org-mode users are Emacs users and probably like to use exactly
this setup. The only exception configured as such by default is
that files with html or xhtml extensions will be opened using
the system default, most likely a browser.
See <E1KE2Mh-0005EC-CF@cvs.savannah.gnu.org> in emacs-commit@:
* org.el (org-agenda-skip-unavailable-files):
* org-clock.el (org-clock-out-when-done): Doc fixes.
The bug affected the exportation of commented subtree: case cannot be
ignored when checking for the COMMENT cookie ("Comment" is a frequent
word in french, and has a completely different meaning.)
This bug was reported by Manuel Hermenegildo. There
were really two issues: The parsing of the FILETAGS line
was broken, and the function `org-get-tags-at' did ignore
these tags. Both problems are fixed now.
The #+STARTUP etc lines that define settings on a per-file
basis can now be collected in a separate file and included
with a line:
#+SETUPFILE: "/path/to/setup.org"
This has been a frequent request in the past, now it is
finally possible.
Carsten Dominik
Bernt Hansen
Bastien Guerry
Carsten Dominik