From 6e5598dc316146f50b2503a9f18dcf7d25e873db Mon Sep 17 00:00:00 2001 From: Nicolas Goaziou Date: Sat, 19 Aug 2017 15:32:54 +0200 Subject: [PATCH] Document new column display * doc/org.texi (Column width and alignment): Document new column display. --- doc/org.texi | 107 +++++++++++++++++++++++++++++++++------------------ etc/ORG-NEWS | 30 +++++++++++++++ 2 files changed, 99 insertions(+), 38 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 494987bee..ef54ea252 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -2296,60 +2296,91 @@ 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. -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{} 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. +@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: -@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 | -|---+------------------------------| |---+--------| -@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}. +@table @asis +@orgcmd{C-c C-c,org-table-align} +Align the current table. +@end table @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: +@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. 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 +|---+---------------------+--------| |---+-------@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 + +To set the width of a column, one field anywhere in the column may contain +just the string @samp{} where @samp{N} specifies the width as a number of +characters. You control displayed width of columns with the following tools: + +@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: shrink +@end example + If you would like to overrule the automatic alignment of number-rich columns to the right and of string-rich columns to the left, you can use @samp{}, @samp{}@footnote{Centering does not work inside Emacs, but it does have an effect when exporting to HTML.} or @samp{} in a similar fashion. You may also combine alignment and field width like this: @samp{}. -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 cce6f4e36..41cc3f9a3 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