doit

Author: Siddd-hrr

src/library/grid/vignettes/frame.Rnw

@@ -1,23 +1,20 @@
 %\VignetteEncoding{UTF-8}
 % File src/library/grid/vignettes/interactive.Rnw
 % Part of the R package, https://www.R-project.org
-% Copyright 2001–2026 Paul Murrell and the R Core Team
+% Copyright 2001-13 Paul Murrell and the R Core Team
 % Distributed under GPL 2 or later
 
 \documentclass[a4paper]{article}
 %\VignetteIndexEntry{Editing grid Graphics}
 %\VignettePackage{grid}
-
 \newcommand{\code}[1]{\texttt{#1}}
 \newcommand{\pkg}[1]{{\normalfont\fontseries{b}\selectfont #1}}
 \newcommand{\grid}{\pkg{grid}}
 \newcommand{\R}{{\sffamily R}}
-
 \setlength{\parindent}{0in}
 \setlength{\parskip}{.1in}
 \setlength{\textwidth}{140mm}
 \setlength{\oddsidemargin}{10mm}
-
 \title{An Example of Interactive Graphics Editing in \grid}
 \author{Paul Murrell}
 
@@ -30,22 +27,22 @@ library(grid)
 ps.options(pointsize = 12)
 options(width = 60)
 @
-
-\section*{Creating and Naming Grobs}
-We begin by creating an x‑axis and drawing it on the device. It is
-important to assign a \code{name} to the grob so that it can be
-referenced later for editing.
+First of all, we create an x-axis and draw it on the device.
+It is very important that we specify a \code{name} for the object
+so that we can refer to it later.
 
 <<fig1, results=hide, fig=TRUE, width=6, height=2, include=FALSE>>=
 grid.xaxis(at = 1:4/5, vp = viewport(w = .5, h = 0.01), name = "gxa")
 @
 \begin{center}
+{
 \includegraphics[width=3in, height=1in]{interactive-fig1}
+}
 \end{center}
+@
 
-\section*{Editing Grobs}
-Next, we edit the axis by changing its colour to red. The grob is
-referenced by its assigned \code{name}.
+Now we edit the axis, changing the colour of the entire axis to red.
+Notice that we refer to the x-axis by its name.
 
 <<edit1, eval=FALSE>>=
 grid.edit("gxa", gp = gpar(col = "red"))
@@ -55,12 +52,17 @@ gxa <- editGrob(gxa, gp = gpar(col = "red"))
 grid.draw(gxa)
 @
 \begin{center}
+{
 \includegraphics[width=3in, height=1in]{interactive-fig2}
+}
 \end{center}
 
-We can also edit specific components of a grob. For example, changing
-only the labels to green. The \code{gPath()} function is recommended
-for reusable code because it avoids hard‑coding grob names.
+@
+
+Now we change just the labels of the x-axis to green.  We use the
+\code{gPath()} function to concatenate the grob names (we could have used
+\code{"gxa::labels"} here, but \code{gPath()} is recommended for
+writing code that will be reused).
 
 <<edit2, eval=FALSE>>=
 grid.edit(gPath("gxa", "labels"), gp = gpar(col = "green"))
@@ -71,12 +73,18 @@ gxa <- editGrob(gxa, gPath = "labels", gp = gpar(col = "green"))
 grid.draw(gxa)
 @
 \begin{center}
+{
 \includegraphics[width=3in, height=1in]{interactive-fig3}
+}
 \end{center}
+@
 
-Editing can also change structural aspects, such as the number of tick
-marks. When new labels are created, they inherit the default colour of
-the axis, replacing previous label edits.
+It is also possible to change the number of tick marks.
+Notice that the labels all change back to red;  this happens
+because new labels are created by the axis and these ``inherit''
+the colour of the axis by default.  In other words, the
+colour specification of the old labels was specific to the old labels
+and was discarded when the old labels were discarded.
 
 <<edit3, eval=FALSE>>=
 grid.edit("gxa", at = c(0.0, 0.5, 1.0))
@@ -88,10 +96,13 @@ gxa <- editGrob(gxa, at = c(0.0, 0.5, 1.0))
 grid.draw(gxa)
 @
 \begin{center}
+{
 \includegraphics[width=3in, height=1in]{interactive-fig4}
+}
 \end{center}
+@
 
-Finally, we change the labels back to black and rotate them by $30^\circ$.
+Finally, we change the labels back to black and rotate them all $30\deg$.
 
 <<edit4, eval=FALSE>>=
 grid.edit("gxa::labels", gp = gpar(col = "black"), rot = 30)
@@ -104,14 +115,16 @@ gxa <- editGrob(gxa, gPath = "labels", gp = gpar(col = "black"), rot = 30)
 grid.draw(gxa)
 @
 \begin{center}
+{
 \includegraphics[width=3in, height=1in]{interactive-fig5}
+}
 \end{center}
+@
 
-\section*{Off‑Screen Editing}
-All of the above examples describe editing grobs and updating them on
-screen. Equivalent operations can be performed entirely off‑screen by
-working with grob objects directly. This approach is useful for
-reproducibility and scripted graphics pipelines.
+The above examples describe how to perform editing on a grid object
+and have the changes updated on screen.  The equivalent can be done
+entirely ``off-screen'', by just working with the grid object.
+The off-screen equivalent in this case would look like:
 
 <<results=hide>>=
 gxa <- xaxisGrob(at = 1:4/5, vp = viewport(w = .5, h = .01))
@@ -121,5 +134,4 @@ gxa <- editGrob(gxa, at = c(0.0, 0.5, 1.0))
 gxa <- editGrob(gxa, gPath = "labels", gp = gpar(col = "black"), rot = 30)
 grid.draw(gxa)
 @
-
-\end{document}
+\end{document}

src/library/grid/vignettes/interactive.Rnw

@@ -1,13 +1,12 @@
 %\VignetteEncoding{UTF-8}
 % File src/library/grid/vignettes/locndimn.Rnw
 % Part of the R package, https://www.R-project.org
-% Copyright 2001–2026 Paul Murrell and the R Core Team
+% Copyright 2001-13 Paul Murrell and the R Core Team
 % Distributed under GPL 2 or later
 
 \documentclass[a4paper]{article}
 %\VignetteIndexEntry{Locations versus Dimensions}
 %\VignettePackage{grid}
-
 \setlength{\parindent}{0in}
 \setlength{\parskip}{.1in}
 \setlength{\textwidth}{140mm}
@@ -17,10 +16,11 @@
 \newcommand{\pkg}[1]{{\normalfont\fontseries{b}\selectfont #1}}
 \newcommand{\grid}{\pkg{grid}}
 
-\title{The Difference Between Locations and Dimensions in \grid{}}
+\title{The difference between Locations and Dimensions in \grid{}}
 \author{Paul Murrell}
 
 \begin{document}
+
 \maketitle
 
 <<echo=FALSE, results=hide>>=
@@ -29,31 +29,31 @@ library(grid)
 ps.options(pointsize = 12)
 options(width = 60)
 @
-
-\section*{Introduction}
-The \grid{} package makes use of unit objects to express both the
-locations and dimensions of graphical components. For example,
-\code{grid.rect()} interprets its \code{x} and \code{y} arguments as
-locations within the current viewport, while its \code{width} and
-\code{height} arguments are treated as dimensions.
-
-These interpretations are usually implicit: if the argument is an
-\code{x} or \code{y} value, it represents a location; if it is a
-\code{width} or \code{height} value, it represents a dimension.
-
-The distinction matters because, in some coordinate systems —
-notably \code{"native"} coordinates — a location value can have a
-different meaning from a dimension value. This occurs whenever the
-minimum value of the coordinate system is not zero.
-
-In simple unit specifications, the difference may not be noticeable.
-However, there are two areas where the distinction is critical.
-
-\section*{1. Arithmetic on Units}
-When adding or performing arithmetic operations on units, it is
-important to remember that locations behave like vectors, while
-dimensions behave like lengths. The following diagram demonstrates
-the difference:
+\grid{} makes use of unit objects to express both the locations and
+dimensions of graphical components.  For example, the \code{grid.rect()}
+function treats its x- and y-arguments as locations within the current
+viewport, and its width- and height-arguments as dimensions within the
+current viewport.
+
+These different interpretations of units are usually implicit like this;
+if its an x- or y-value then its a location, if its a width- or height-value
+then its a dimension.
+
+The distinction is made at all because, in some coordinate systems, notably
+\code{"native"} coordinates, the location $x$ can have a very different
+meaning
+from the dimension $x$ -- basically, whenever the minimum value of the
+coordinate system is not zero.
+
+In the specification of simple units, the difference between locations
+and dimensions is often not noticeable.  However, there are a couple
+of tricky areas:
+
+\begin{enumerate}
+\item When adding (or performing any arithmetic operation on) units,
+it is important to keep in mind that locations are added like vectors
+and dimensions are added like lengths.  The following
+diagram demonstrates the difference:
 
 <<fig=TRUE, echo=FALSE, results=hide>>=
 diagram.locn <- function(i, n, locn) {
@@ -96,28 +96,28 @@ diagram.dimn(8, n, unit(0.4, "native"))
 diagram.dimn(9, n, unit(1, "native") + unit(-0.4, "native"))
 diagram.dimn(10, n, unit(1, "native") - unit(0.4, "native"))
 @
-
-\section*{2. Converting Units}
-The functions \code{convertX}, \code{convertY}, \code{convertWidth},
-and \code{convertHeight} are used to convert between coordinate
-systems. It is essential to distinguish whether the conversion is for
-a location or for a dimension.
-
-The following code demonstrates the difference:
+\item The functions \code{convertX},
+\code{convertY}, \code{convertWidth}, \code{convertHeight}
+  are used to convert from one coordinate system to another.
+Again, it is important whether the conversion is for a location or
+for a dimension.
+The following code
+demonstrates some results from these functions based on a similar
+situation to that in the preceding diagram:
 
 <<fig=FALSE>>=
 pushViewport(viewport(yscale = c(-0.6, 1.3)))
-# Location conversions
+# Unexpected results?
 convertY(unit(1,'native'), "native")
 convertY(unit(-.4,'native'), "native")
 convertY(unit(1,'native')+unit(-.4,'native'), "native")
 convertY(unit(1,'native')-unit(.4,'native'), "native")
-# Dimension conversions
+# Expected results
 convertHeight(unit(1,'native'), "native")
 convertHeight(unit(-.4,'native'), "native")
 convertHeight(unit(1,'native')+unit(-.4,'native'), "native")
 convertHeight(unit(1,'native')-unit(.4,'native'), "native")
 popViewport()
 @
-
-\end{document}
+\end{enumerate}
+\end{document}

src/library/grid/vignettes/locndimn.Rnw

@@ -1,23 +1,20 @@
 %\VignetteEncoding{UTF-8}
 % File src/library/grid/vignettes/moveline.Rnw
 % Part of the R package, https://www.R-project.org
-% Copyright 2001–2026 Paul Murrell and the R Core Team
+% Copyright 2001-13 Paul Murrell and the R Core Team
 % Distributed under GPL 2 or later
 
 \documentclass[a4paper]{article}
 %\VignetteIndexEntry{Demonstrating move-to and line-to}
 %\VignettePackage{grid}
-
 \newcommand{\code}[1]{\texttt{#1}}
 \newcommand{\pkg}[1]{{\normalfont\fontseries{b}\selectfont #1}}
 \newcommand{\grid}{\pkg{grid}}
 \newcommand{\R}{{\sffamily R}}
-
 \setlength{\parindent}{0in}
 \setlength{\parskip}{.1in}
 \setlength{\textwidth}{140mm}
 \setlength{\oddsidemargin}{10mm}
-
 \title{Drawing Lines Between Viewports: \\
 \code{grid.move.to} and \code{grid.line.to}}
 \author{Paul Murrell}
@@ -32,17 +29,17 @@ ps.options(pointsize = 12)
 options(width = 60)
 @
 
-\section*{Introduction}
-Many graphics systems provide the concept of a current drawing
-location. This functionality has been added to \grid{}, with the
-additional benefit that the drawing location can be specified relative
-to an arbitrary viewport. This allows drawing operations to span
-multiple coordinate systems.
+Many graphics systems have the notion of a current drawing location.
+This has been added to Grid, with the additional benefit that the
+drawing location can be specified relative to an arbitrary viewport.
+This allows drawing across coordinate
+systems\footnote{There was a request on R-help for exactly this
+sort of thing - I will try to find the exact reference - and there has
+since been another (From: Ross Darnell; Subject: Problems with
+segments and multiple graphs). }.
 
-\section*{Example}
-The following code demonstrates a simple example of moving to a
-location in one viewport and drawing a line to a location in another
-viewport. The output is shown below.
+The following code demonstrates a simple example (the output is
+given after the code).
 
 <<fig, results=hide, fig=TRUE, width=5, height=4, include=FALSE>>=
 pushViewport(
@@ -61,9 +58,10 @@ grid.points(0.5, unit(2, "native"))
 grid.line.to(0.5, unit(2,"native"))
 @
 \begin{center}
+{
 \includegraphics[width=5in, height=4in]{moveline-fig}
+}
 \end{center}
 
+@
 \end{document}
-
-