From 2583260566074fd263a84d515ef637267563d371 Mon Sep 17 00:00:00 2001
From: Trevor Daniels <t.daniels@treda.co.uk>
Date: Fri, 24 Oct 2014 14:50:48 +0100
Subject: [PATCH] Doc: Issue 4168: Add 'Dimensions' to Useful concepts

---
 .../notation/changing-defaults.itely          | 30 +++++++++++++++++++
 Documentation/notation/text.itely             |  5 ++--
 2 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely
index 6d6b724cff..da68bf2a2b 100644
--- a/Documentation/notation/changing-defaults.itely
+++ b/Documentation/notation/changing-defaults.itely
@@ -2585,6 +2585,7 @@ modified by completely re-defining them as alists.}
 * Input modes::
 * Direction and placement::
 * Distances and measurements::
+* Dimensions::
 * Staff symbol properties::
 * Spanners::
 * Visibility of objects::
@@ -2844,6 +2845,35 @@ Notation Reference:
 @ref{Setting the staff size}.
 
 
+@node Dimensions
+@subsection Dimensions
+
+@cindex dimensions
+@cindex bounding box
+
+The dimensions of a graphical object specify the positions of the left
+and right edges and the bottom and top edges of the objects' bounding
+box as distances from the objects' reference point in units of
+staff-spaces.  These positions are usually coded as two Scheme pairs.
+For example, the text markup command @code{\with-dimensions} takes
+three arguments, the first two of which are a Scheme pair giving the
+left and right edge positions and a Scheme pair giving the bottom and
+top edge positions:
+
+@example
+\with-dimensions #'(-5 . 10) #'(-3 . 15) @var{arg}
+@end example
+
+This specifies a bounding box for @var{arg} with its left edge at -5,
+its right edge at 10, its bottom edge at -3 and its top edge at 15,
+all measured from the objects' reference point in units of
+staff-spaces.
+
+@seealso
+Notation Reference:
+@ref{Distances and measurements}.
+
+
 @node Staff symbol properties
 @subsection Staff symbol properties
 
diff --git a/Documentation/notation/text.itely b/Documentation/notation/text.itely
index 739abbdf49..ac5436b94b 100644
--- a/Documentation/notation/text.itely
+++ b/Documentation/notation/text.itely
@@ -1122,9 +1122,10 @@ An exhaustive list of graphics-specific commands can be found in
 
 @seealso
 Notation Reference:
-@ref{Graphic},
+@ref{Align},
+@ref{Dimensions},
 @ref{Editorial annotations},
-@ref{Align}.
+@ref{Graphic}.
 
 Installed Files:
 @file{scm/define-markup-commands.scm},
-- 
2.39.2