summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNicolas Goaziou <mail@nicolasgoaziou.fr>2017-08-19 15:32:54 +0200
committerNicolas Goaziou <mail@nicolasgoaziou.fr>2017-09-06 15:21:20 +0200
commit6e5598dc316146f50b2503a9f18dcf7d25e873db (patch)
tree7806138334bcdbffdaa2f5d6bd6cb9eb3a2fb7bd
parent8374e6f438b8c2b85c0bb0671fa6df1547b49ec5 (diff)
downloadorg-mode-6e5598dc316146f50b2503a9f18dcf7d25e873db.tar.gz
Document new column display
* doc/org.texi (Column width and alignment): Document new column display.
-rw-r--r--doc/org.texi101
-rw-r--r--etc/ORG-NEWS30
2 files changed, 96 insertions, 35 deletions
diff --git a/doc/org.texi b/doc/org.texi
index 494987b..ef54ea2 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -2296,50 +2296,81 @@ it off with
@cindex narrow columns in tables
@cindex alignment in tables
-The width of columns is automatically determined by the table editor. And
-also the alignment of a column is determined automatically from the fraction
-of number-like versus non-number fields in the column.
+The width of columns is automatically determined by the table editor. The
+alignment of a column is determined automatically from the fraction of
+number-like versus non-number fields in the column.
+
+@vindex org-table-automatic-realign
+Editing a field may modify alignment of the table. Moving a contiguous row
+or column---i.e., using @kbd{TAB} or @kbd{RET}---automatically re-aligns it.
+If you want to disable this behavior, set @code{org-table-automatic-realign}
+to @code{nil}. In any case, you can always align manually a table:
+
+@table @asis
+@orgcmd{C-c C-c,org-table-align}
+Align the current table.
+@end table
+
+@vindex org-startup-align-all-tables
+@noindent
+Setting the option @code{org-startup-align-all-tables} re-aligns all tables
+in a file upon visiting it. You can also set this option on a per-file basis
+with:
+
+@example
+#+STARTUP: align
+#+STARTUP: noalign
+@end example
Sometimes a single field or a few fields need to carry more text, leading to
-inconveniently wide columns. Or maybe you want to make a table with several
-columns having a fixed width, regardless of content. To set the width of
-a column, one field anywhere in the column may contain just the string
-@samp{<N>} where @samp{N} is an integer specifying the width of the column in
-characters. The next re-align will then set the width of this column to this
-value.
+inconveniently wide columns. Maybe you want to hide away several columns or
+display them with a fixed width, regardless of content, as shown in the
+following example.
@example
@group
-|---+------------------------------| |---+--------|
-| | | | | <6> |
-| 1 | one | | 1 | one |
-| 2 | two | ----\ | 2 | two |
-| 3 | This is a long chunk of text | ----/ | 3 | This=> |
-| 4 | four | | 4 | four |
-|---+------------------------------| |---+--------|
+|---+---------------------+--------| |---+-------@dots{}|@dots{}|
+| | <6> | | | | <6> @dots{}|@dots{}|
+| 1 | one | some | ----\ | 1 | one @dots{}|@dots{}|
+| 2 | two | boring | ----/ | 2 | two @dots{}|@dots{}|
+| 3 | This is a long text | column | | 3 | This i@dots{}|@dots{}|
+|---+---------------------+--------| |---+-------@dots{}|@dots{}|
@end group
@end example
-@noindent
-Fields that are wider become clipped and end in the string @samp{=>}.
-Note that the full text is still in the buffer but is hidden.
-To see the full text, hold the mouse over the field---a tool-tip window
-will show the full content. To edit such a field, use the command
-@kbd{C-c `} (that is @kbd{C-c} followed by the grave accent). This will
-open a new window with the full field. Edit it and finish with @kbd{C-c
-C-c}.
+To set the width of a column, one field anywhere in the column may contain
+just the string @samp{<N>} where @samp{N} specifies the width as a number of
+characters. You control displayed width of columns with the following tools:
-@vindex org-startup-align-all-tables
-When visiting a file containing a table with narrowed columns, the
-necessary character hiding has not yet happened, and the table needs to
-be aligned before it looks nice. Setting the option
-@code{org-startup-align-all-tables} will realign all tables in a file
-upon visiting, but also slow down startup. You can also set this option
-on a per-file basis with:
+@table @asis
+@orgcmd{C-c @key{TAB},org-table-toggle-column-width}
+Shrink or expand current column.
+
+If a width cookie specifies a width W for the column, shrinking it displays
+the first W visible characters only. Otherwise, the column is shrunk to
+a single character.
+
+When called before the first column or after the last one, ask for a list of
+column ranges to operate on.
+
+@orgcmd{C-u C-c @key{TAB},org-table-shrink}
+Shrink all columns with a column width. Expand the others.
+
+@orgcmd{C-u C-u C-c @key{TAB},org-table-expand}
+Expand all columns.
+@end table
+
+To see the full text of a shrunk field, hold the mouse over it---a tool-tip
+window then shows the full content. For convenience, any change to a shrunk
+column expands it.
+
+@vindex org-startup-shrink-all-tables
+Setting the option @code{org-startup-shrink-all-tables} shrinks all columns
+containing a width cookie in a file the moment it is visited. You can also
+set this option on a per-file basis with:
@example
-#+STARTUP: align
-#+STARTUP: noalign
+#+STARTUP: shrink
@end example
If you would like to overrule the automatic alignment of number-rich columns
@@ -2348,8 +2379,8 @@ to the right and of string-rich columns to the left, you can use @samp{<r>},
effect when exporting to HTML.} or @samp{<l>} in a similar fashion. You may
also combine alignment and field width like this: @samp{<r10>}.
-Lines which only contain these formatting cookies will be removed
-automatically when exporting the document.
+Lines which only contain these formatting cookies are removed automatically
+upon exporting the document.
@node Column groups
@section Column groups
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index cce6f4e..41cc3f9 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -1,5 +1,7 @@
ORG NEWS -- history of user-visible changes. -*- mode: org; coding: utf-8 -*-
+#+STARTUP: overview
+
#+LINK: doc http://orgmode.org/worg/doc.html#%s
#+LINK: git http://orgmode.org/cgit.cgi/org-mode.git/commit/?id=%s
@@ -9,6 +11,20 @@ See the end of the file for license conditions.
Please send Org bug reports to mailto:emacs-orgmode@gnu.org.
* Version 9.2
+** Incompatible changes
+*** =align= STARTUP value no longer narrow table columns
+
+Columns narrowing (or shrinking) is now dynamic. See [[*Dynamically
+narrow table columns]] for details. In particular, it is decoupled from
+aligning.
+
+If you need to automatically shrink columns upon opening an Org
+document, use =shrink= value instead, or in addition to align:
+
+#+BEGIN_EXAMPLE
+,#+STARTUP: align shrink
+#+END_EXAMPLE
+
** New features
*** ~org-archive~ functions update status cookies
@@ -28,6 +44,20 @@ Will update the status cookie in the top level header.
The ~org-agenda-overriding-header~ inserted into agenda views can now
be disabled by setting it to an empty string.
+*** Dynamically narrow table columns
+
+With ~C-c TAB~, it is now possible to narrow a column to the width
+specified by a width cookie in the column, or to 1 character if there
+is no such cookie. The same keybinding expands a narrowed column to
+its previous state.
+
+Editing the column automatically expands the whole column to its full
+size.
+
+#+BEGIN_EXAMPLE
+ ,#+STARTUP: shrink
+#+END_EXAMPLE
+
* Version 9.1
** Incompatible changes