Skip to content

Commit d88073c

Browse files
committed
Small docs tidying
1 parent 6c1ba8e commit d88073c

File tree

1 file changed

+25
-23
lines changed

1 file changed

+25
-23
lines changed

Documentation/PackingStyles.md

Lines changed: 25 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@
3434
☆ [`PostsAndLintel`, `Arch`](#PostsAndLintel_Arch) 
3535
☆ [Columns and rows](#Sides_Rows) 
3636
★ [`Array`](#Array) 
37+
★ [Other flags, constraints, and sub‑parameters](#other_flags_etc) 
3738
★ [Related parameters](#Related_parameters) 
3839
★ [Code extracts](#Code_extracts)
3940

@@ -51,7 +52,7 @@ Unless there is a compelling need to change things, users are encouraged to take
5152

5253
The user specifies an array, `PackingStyles`, which is a list of generic packing styles.
5354
In turn each style from the list is taken, and each allowed variation is tested.
54-
Broadly, if a later-tested style allows a larger radius than the current best, then the old best is replaced by this better style.
55+
Broadly, if a later‑tested style allows a larger radius than the current best, then the old best is replaced by this better style.
5556

5657
If the element of `PackingStyles` is just the style, it doesn’t need to be in an array.
5758
But the elements of `PackingStyles` can have constraints and variations.
@@ -71,19 +72,19 @@ E.g. (which is unrealistically verbose to show some of the possibilities, and wh
7172
]
7273
```
7374

74-
The general mathematical problem, largest possible radius for *n* non-overlapping circles in a particular rectangle, is difficult (see [PackoMania](http://www.packomania.com/) for solutions to many special cases).
75+
The general mathematical problem, largest possible radius for *n* non‑overlapping circles in a particular rectangle, is difficult (see [PackoMania](http://www.packomania.com/) for solutions to many special cases).
7576
This code has enough generality that it often finds the best, and when it can’t, its radius is not much smaller than the mathematical optimum.
7677
E.g., for 14 glasses on `/A3` see discussion in [issue 151](http://github.com/jdaw1/placemat/issues/151).
7778

7879
For many possible tastings, `PackingStyles` can be left at its default value.
7980
For example, if there are 24 different Madeiras over four `/A4` pages, the defaults work (though, of course, very important, don’t forget to invite [me](http://www.jdawiseman.com/author.html)).
80-
In such a case the default value of `GlassesOnSheetsMaxPerSheet` would cause [`GlassesOnSheets`](page_level.md#glassesonsheets-and-glassesontastingnotepages) to be four page-defining arrays each of length six glasses, which would cause the chosen element of `PackingStyles` to be `/RectangularDislocation`.
81+
In such a case the default value of `GlassesOnSheetsMaxPerSheet` would cause [`GlassesOnSheets`](page_level.md#glassesonsheets-and-glassesontastingnotepages) to be four page‑defining arrays each of length six glasses, which would cause the chosen element of `PackingStyles` to be `/RectangularDislocation`.
8182

8283
But if table space were tight, it could be better to have fifteen on an `/A3`, six on an `/A4`, and three on the right side of an `/A4`, so lessening usage of table space from 4 × 210mm = 840mm per person to ≈ 3½ × 210mm = 735mm.
8384
That would require changing [`GlassesOnSheets`](page_level.md#glassesonsheets-and-glassesontastingnotepages), and also changing the subject of this page, `PackingStyles`.
8485

8586
There follow descriptions and pictures of the various styles allowable in `PackingStyles`.
86-
(The two PDFs ([non-`/Array`](images/PackingStyles.pdf), [`/Array`](images/PackingStyles_Array.pdf)), from which the bitmaps were made, show the element of `PackingStyles` in the header.)
87+
(The two PDFs ([non‑`/Array`](images/PackingStyles.pdf), [`/Array`](images/PackingStyles_Array.pdf)), from which the bitmaps were made, show the element of `PackingStyles` in the header.)
8788

8889
<a name="Efficient"></a>
8990
## Efficient packings
@@ -115,7 +116,7 @@ The `/Mirror` flag chooses the alternate chirality, if that has a sensible meani
115116
<a name="RectangularDislocation"></a>
116117
### RectangularDislocation
117118

118-
`/RectangularDislocation`: The next four examples are rectangular, optionally with a horizontal &lsquo;dislocation&rsquo; in the middle, that having, `/Diamonds`-style, circles lying between the circles in the adjacent row.
119+
`/RectangularDislocation`: The next four examples are rectangular, optionally with a horizontal &lsquo;dislocation&rsquo; in the middle, that having, `/Diamonds`&#8209;style, circles lying between the circles in the adjacent row.
119120

120121
<div align="center">
121122

@@ -132,9 +133,9 @@ The `/Mirror` flag chooses the alternate chirality, if that has a sensible meani
132133
### SquareGrid
133134

134135
`/SquareGrid` can be similar to `/RectangularDislocation`.
135-
In the latter the glasses fill the page: observe the six-glass example above, in which the circles touch their vertical neighbours, but have a slight gap from the horizontal neighbour.
136+
In the latter the glasses fill the page: observe the six&#8209;glass example above, in which the circles touch their vertical neighbours, but have a slight gap from the horizontal neighbour.
136137
In `/SquareGrid` there is no dislocation, and by default the vertical and horizontal distances are the same and equal to the diameter.
137-
`/SquareGrid` has two optional one-parameter flags: `/HorizontalAlignment` (which must have a value of one of `/Left`, `/Right`, `/Centre`, or `/Justify`); and `/VerticalAlignment` (one of `/Top`, `/Bottom`, `/Middle`, or `/Justify`).
138+
`/SquareGrid` has two optional one&#8209;parameter flags: `/HorizontalAlignment` (which must have a value of one of `/Left`, `/Right`, `/Centre`, or `/Justify`); and `/VerticalAlignment` (one of `/Top`, `/Bottom`, `/Middle`, or `/Justify`).
138139
Obviously either `/Justify` can allow distances to differ.
139140

140141
<div align="center">
@@ -166,7 +167,7 @@ The diamonds can be offset from the diamonds either vertically or horizontally.
166167
<a name="DiamondsPlus"></a>
167168
### DiamondsPlus
168169

169-
`/DiamondsPlus` is mostly three-row diamonds (or, if `/Portrait`, three-column), with two extras set between the three rows (columns).
170+
`/DiamondsPlus` is mostly three&#8209;row diamonds (or, if `/Portrait`, three&#8209;column), with two extras set between the three rows (columns).
170171
It is the best packing of seven or ten glasses on several paper sizes.
171172

172173
There is a generalisation of `/DiamondsPlus` over any number of rows (columns), [not yet coded](http://github.com/jdaw1/placemat/issues/38).
@@ -185,7 +186,7 @@ There is a generalisation of `/DiamondsPlus` over any number of rows (columns),
185186
`/RectangularAlternateNudge`: in this rectangular variant, alternate rows (or columns) are slightly nudged, better to fill the space.
186187

187188
Thus `/RectangularAlternateNudge` is a small deviation away from greater symmetry, about which the the author is unenthusiastic.
188-
Because of this non-enthusiasm, by default, `/RectangularAlternateNudge` comes with a sub-parameter: `[ /RectangularAlternateNudge /ImprovementPointsMin 2 ]`.
189+
Because of this non&#8209;enthusiasm, by default, `/RectangularAlternateNudge` comes with a sub&#8209;parameter: `[ /RectangularAlternateNudge /ImprovementPointsMin 2 ]`.
189190
This imposes an additional requirement: this packing style is chosen only if it is an improvement on the previous best radius of &ge;&nbsp;2pt &asymp;&nbsp;0.7mm &asymp;&nbsp;0.028&Prime;.
190191

191192
The next table of examples shows six glasses on `/USL` = 8&frac12;&Prime;&times;11&Prime; and on `/A4` = 210mm&times;297mm, in all cases with margins of 24pt = &#8531;&Prime; &asymp; 8.5mm, and space of 6pt &asymp; 2.1mm for the header.
@@ -210,7 +211,7 @@ But on `/A4` the improvement in the radius is much less: only &asymp; 0.28pt &as
210211
<a name="RectangularAlternateSplitNudge"></a>
211212
### RectangularAlternateSplitNudge
212213

213-
`RectangularAlternateSplitNudge`, by making the nudged rows go in both directions, lessens the aesthetic damage of the non-`Split` nudge, but makes an even smaller gain in the radius.
214+
`RectangularAlternateSplitNudge`, by making the nudged rows go in both directions, lessens the aesthetic damage of the non&#8209;`Split` nudge, but makes an even smaller gain in the radius.
214215

215216
<div align="center">
216217

@@ -246,7 +247,7 @@ Obviously using both would be strange.
246247
### Temple
247248

248249
`/Temple` is an intricate pattern, that has the largest radius for 10 glasses on `/USL`, and for 13 glasses on either `/USLegal` or `/Tabloid`.
249-
The sub-parameter `/TempleExtraColsToLeftOrRowsBelow` is followed by one integer, and is to `/Temple` as `/RectColsToLeftOrRowsBelow` is to `/DiamondsAndRectangular`.
250+
The sub&#8209;parameter `/TempleExtraColsToLeftOrRowsBelow` is followed by one integer, and is to `/Temple` as `/RectColsToLeftOrRowsBelow` is to `/DiamondsAndRectangular`.
250251

251252
<div align="center">
252253

@@ -283,7 +284,7 @@ This design might be particularly appropriate if the central circles held the ca
283284
<a name="Sides_Rows"></a>
284285
### Sides, LeftSide, RightSide, TopRow, MiddleRow, BottomRow
285286

286-
`/Sides`, `/LeftSide`, `/RightSide`, `/TopRow`, `/MiddleRow`, and `/BottomRow` are mostly self-explanatory.
287+
`/Sides`, `/LeftSide`, `/RightSide`, `/TopRow`, `/MiddleRow`, and `/BottomRow` are mostly self&#8209;explanatory.
287288

288289
`/RightSide` (and, *mutatis mutandis*, `/LeftSide`) have a particular use.
289290
Consider a tasting with 17 glasses.
@@ -324,7 +325,7 @@ After the `/Positions` marker is a list of points, typically of the form `[x y]`
324325
The code then chooses the radius and separately scales the *x* and *y* directions such that things fit as snugly as possible, obviously subject to the other upper bounds on the radius.
325326
The glass ordering is that given in the array: there is no subsequent sorting or ordering.
326327

327-
There is a more complicated variant, in which some of the sub-arrays are of the form `[x y x' y']`.
328+
There is a more complicated variant, in which some of the sub&#8209;arrays are of the form `[x y x' y']`.
328329
The first two elements are used, as before, and fix the radius and the canvas.
329330
The circle at (*x*,*y*) is then moved in a straight line towards (*x'*,*y'*).
330331
A circle stops moving if it collides with another circle (a tangential touch not being a collision); if it collides with the edge of the page; or it arrives at (*x'*,*y'*).
@@ -343,43 +344,44 @@ The example image shows, on `/A3`, an alternation of the previous code extract t
343344
The difference is the movement of the circles at (2,2) and (4,2), both towards (3,2).
344345
For the author&rsquo;s taste, the closer relationship of the two B0 circles (same wine in single and magnum) means they should be touching, rather than equally spaced between A0 and C0.
345346

346-
## Other flags, constraints, and sub-parameters
347+
<a name="other_flags_etc"></a>
348+
## Other flags, constraints, and sub&#8209;parameters
347349

348-
There are other flags and constraints and sub-parameters, as follows.
350+
There are other flags and constraints and sub&#8209;parameters, as follows.
349351

350352
* `/Mirror`: the alternate chirality.
351353
If there isn&rsquo;t a sensible meaning to this, ignored.
352354

353355
* `/ShoveLeft` and `/ShoveRight`: if there is spare space between the circles, probably because the radius has been shrunk to that on another sheet, the circles are shoved leftwards (or rightwards) against that margin.
354356
But not heeded in every base style.
355357

356-
* `/PackingDirectionTopToBottom bool` and `/PackingDirectionLeftToRight bool` and `/PackingNestingColumnMajor bool`: by default most layouts start at the top-left, work across to the top-right, then start the second row slightly further down on the left.
357-
This can be changed: glasses can run right-to-left, bottom-to-top, and the nesting order of columns and rows can be exchanged.
358-
For large pre-poured tastings on `/A3` or `/Tabloid`, generally one pre-pours the youngest first.
358+
* `/PackingDirectionTopToBottom bool` and `/PackingDirectionLeftToRight bool` and `/PackingNestingColumnMajor bool`: by default most layouts start at the top&#8209;left, work across to the top&#8209;right, then start the second row slightly further down on the left.
359+
This can be changed: glasses can run right&#8209;to&#8209;left, bottom&#8209;to&#8209;top, and the nesting order of columns and rows can be exchanged.
360+
For large pre&#8209;poured tastings on `/A3` or `/Tabloid`, generally one pre&#8209;pours the youngest first.
359361
If these are in the front row, it is more fiddly to lower subsequent older vintages into place.
360362
Adding `/PackingNestingColumnMajor true` fixes this.
361-
(The global value of `PackingNestingColumnMajor` is the default value within PackingStyles, and also affects the ordering in Cork-Display pages.)
363+
(The global value of `PackingNestingColumnMajor` is the default value within PackingStyles, and also affects the ordering in [Cork&#8209;Display pages](not_glasses.md#CorkDisplay).)
362364

363365
* `/ProhibitVerticalNudging` or `/ProhibitHorizontalNudging`: have the obvious effect in base styles `/RectangularAlternateNudge` and `/RectangularAlternateSplitNudge`.
364366

365-
* `/RectColsToLeftOrRowsBelow int` chooses the position of the diamonds-style block in `/DiamondsAndRectangular`.
367+
* `/RectColsToLeftOrRowsBelow int` chooses the position of the diamonds&#8209;style block in `/DiamondsAndRectangular`.
366368

367369
* `/TempleExtraColsToLeftOrRowsBelow int` chooses the position of the &lsquo;hole&rsquo; in `/Temple`.
368370

369-
* `/CentralGlasses int`: both `/PostsAndLintel` and `/Arch` packings can have 0, 1, 2, or 3 glasses in the centre, the remainder running round the edge or semi-ellipse.
371+
* `/CentralGlasses int`: both `/PostsAndLintel` and `/Arch` packings can have 0, 1, 2, or 3 glasses in the centre, the remainder running round the edge or semi&#8209;ellipse.
370372

371373
* `/RowsNumMin int`, `/RowsNumMax int`: minimum or maximum number of rows permitted.
372374
Relevant in the `/Diamonds`, `/RectangularDislocation`, `/SquareGrid`, `/RectangularAlternateNudge`, and `/PostsAndLintel` packing styles.
373375

374376
* `/GlassesDeemedAtLeast int`: the number of glasses is deemed to be the greater of this and <code>GlassesOnSheets&nbsp;<i>SheetNum</i>&nbsp;get&nbsp;length</code>. Say there are 17 glasses, to be spread over three `/A4` sheets 6:6:5.
375-
One might want all three to have the same design, achievable with sub-parameter <code>/GlassesDeemedAtLeast&nbsp;6</code>.
377+
One might want all three to have the same design, achievable with sub&#8209;parameter <code>/GlassesDeemedAtLeast&nbsp;6</code>.
376378

377379
* `/OnlyIfGlassesNumMin int`, `/OnlyIfGlassesNumMax int`: permitted number of glasses.
378380
If breaching constraint, this packing specification not used.
379381

380382
* `/OnlyIfSheetNumMin int`, `/OnlyIfSheetNumMax int`: specifying permitted values for the internal variable `SheetNum`, which is `0` on the first sheet, `1` on the second, etc.
381383

382-
* `/OnlyIfOrientation name`, the sub-parameter being one of `/Landscape`, `/Portrait`, or `/Either`, the last being the default if this sub-parameter absent.
384+
* `/OnlyIfOrientation name`, the sub&#8209;parameter being one of `/Landscape`, `/Portrait`, or `/Either`, the last being the default if this sub&#8209;parameter absent.
383385
If `Orientation` not agreeing, this packing specification not used.
384386

385387
* `/ImprovementPointsMin num`, `/ImprovementProportionMin num`: this specification used only if beating previous best radius by the required amount, either absolute (e.g., `2`&nbsp;points) or as a proportion (e.g., `0.01`&nbsp;=&nbsp;1%).

0 commit comments

Comments
 (0)