From a001627a9609221f05631aaf0366795ce28f8437 Mon Sep 17 00:00:00 2001
From: James Lowe <pkx166h@gmail.com>
Date: Sun, 11 Mar 2012 20:08:21 +0000
Subject: [PATCH] Doc: NR add predefined paper sizes to appendix

Issue 2391

Copied predefined paper size entries from scm/paper.scm as a seperate
appendix entry in order to better document predefined paper sizes.

Also revamped section on Paper Sizes including better @cindex entries,
reworded explanation and examples including how to create a custom
paper size without the need to edit scm/paper.scm

Added note in scm/paper.scm to say that the appendix entry was not
autogenerated so that any new entries will not be forgotten to be added
in the appendix - until someone 'scripts' it.
---
 .../notation/notation-appendices.itely        | 254 ++++++++++++++++++
 Documentation/notation/spacing.itely          |  88 +++---
 scm/paper.scm                                 |   5 +
 3 files changed, 308 insertions(+), 39 deletions(-)

diff --git a/Documentation/notation/notation-appendices.itely b/Documentation/notation/notation-appendices.itely
index 1c00f6fb5b..30756c9d2f 100644
--- a/Documentation/notation/notation-appendices.itely
+++ b/Documentation/notation/notation-appendices.itely
@@ -18,6 +18,7 @@
 * Common chord modifiers::
 * Predefined string tunings::
 * Predefined fretboard diagrams::
+* Predefined paper sizes::
 * MIDI instruments::
 * List of colors::
 * The Feta font::
@@ -441,6 +442,259 @@ The chart below shows the predefined fretboard diagrams for mandolin.
 
 @lilypondfile{display-predefined-mandolin-fretboards.ly}
 
+
+@node Predefined paper sizes
+@appendixsec Predefined paper sizes
+
+Paper sizes are defined in @file{scm/paper.scm}
+
+@noindent
+@strong{The @qq{ISO 216} A Series}
+@table @code
+@item "a10"
+(26 x 37 mm)
+@item "a9"
+(37 x 52 mm)
+@item "a8"
+(52 x 74 mm)
+@item "a7"
+(74 x 105 mm)
+@item "a6"
+(105 x 148 mm)
+@item "a5"
+(148 x 210 mm)
+@item "a4"
+(210 x 297 mm)
+@item "a3"
+(297 x 420 mm)
+@item "a2"
+(420 x 594 mm)
+@item "a1"
+(594 x 841 mm)
+@item "a0"
+(841 x 1189 mm)
+@end table
+
+@noindent
+@strong{The @qq{ISO 216} B Series}
+@table @code
+@item "b10"
+(31 x 44 mm)
+@item "b9"
+(44 x 62 mm)
+@item "b8"
+(62 x 88 mm)
+@item "b7"
+(88 x 125 mm)
+@item "b6"
+(125 x 176 mm)
+@item "b5"
+(176 x 250 mm)
+@item "b4"
+(250 x 353 mm)
+@item "b3"
+(353 x 500 mm)
+@item "b2"
+(500 x 707 mm)
+@item "b1"
+(707 x 1000 mm)
+@item "b0"
+(1000 x 1414 mm)
+@end table
+
+@noindent
+@strong{Two extended sizes as defined in @qq{DIN 476}}
+@table @code
+@item "4a0"
+(1682 x 2378 mm)
+@item "2a0"
+(1189 x 1682 mm)
+@end table
+
+@noindent
+@strong{@qq{ISO 269} standard C series}
+@table @code
+@item "c10"
+(28 x 40 mm)
+@item "c9"
+(40 x 57 mm)
+@item "c8"
+(57 x 81 mm)
+@item "c7"
+(81 x 114 mm)
+@item "c6"
+(114 x 162 mm)
+@item "c5"
+(162 x 229 mm)
+@item "c4"
+(229 x 324 mm)
+@item "c3"
+(324 x 458 mm)
+@item "c2"
+(458 x 648 mm)
+@item "c1"
+(648 x 917 mm)
+@item "c0"
+(917 x 1297 mm)
+@end table
+
+@noindent
+@strong{North American paper sizes}
+@table @code
+@item "junior-legal"
+(8.0 x 5.0 in)
+@item "legal"
+(8.5 x 14.0 in)
+@item "ledger"
+(17.0 x 11.0 in)
+@item "letter"
+(8.5 x 11.0 in)
+@item "tabloid"
+(11.0 x 17.0 in)
+@item "11x17"
+(11.0 x 17.0 in)
+@item "17x11"
+(17.0 x 11.0 in)
+@end table
+
+@noindent
+@strong{Government-letter by IEEE Printer Working Group, for children's
+writing}
+@table @code
+@item "government-letter"
+(8 x 10.5 in)
+@item "government-legal"
+(8.5 x 13.0 in)
+@item "philippine-legal"
+(8.5 x 13.0 in)
+@end table
+
+@noindent
+@strong{ANSI sizes}
+@table @code
+@item "ansi a"
+(8.5 x 11.0 in)
+@item "ansi b"
+(17.0 x 11.0 in)
+@item "ansi c"
+(17.0 x 22.0 in)
+@item "ansi d"
+(22.0 x 34.0 in)
+@item "ansi e"
+(34.0 x 44.0 in)
+@item "engineering f"
+(28.0 x 40.0 in)
+@end table
+
+@noindent
+@strong{North American Architectural sizes}
+@table @code
+@item "arch a"
+(9.0 x 12.0 in)
+@item "arch b"
+(12.0 x 18.0 in)
+@item "arch c"
+(18.0 x 24.0 in)
+@item "arch d"
+(24.0 x 36.0 in)
+@item "arch e"
+(36.0 x 48.0 in)
+@item "arch e1"
+(30.0 x 42.0 in)
+@end table
+
+@noindent
+@strong{Antique sizes still used in the United Kingdom}
+@table @code
+@item "statement"
+(5.5 x 8.5 in)
+@item "half letter"
+(5.5 x 8.5 in)
+@item "quarto"
+(8.0 x 10.0 in)
+@item "octavo"
+(6.75 x 10.5 in)
+@item "executive"
+(7.25 x 10.5 in)
+@item "monarch"
+(7.25 x 10.5 in)
+@item "foolscap"
+(8.27 x 13.0 in)
+@item "folio"
+(8.27 x 13.0 in)
+@item "super-b"
+(13.0 x 19.0 in)
+@item "post"
+(15.5 x 19.5 in)
+@item "crown"
+(15.0 x 20.0 in)
+@item "large post"
+(16.5 x 21.0 in)
+@item "demy"
+(17.5 x 22.5 in)
+@item "medium"
+(18.0 x 23.0 in)
+@item "broadsheet"
+(18.0 x 24.0 in)
+@item "royal"
+(20.0 x 25.0 in)
+@item "elephant"
+(23.0 x 28.0 in)
+@item "double demy"
+(22.5 x 35.0 in)
+@item "quad demy"
+(35.0 x 45.0 in)
+@item "atlas"
+(26.0 x 34.0 in)
+@item "imperial"
+(22.0 x 30.0 in)
+@item "antiquarian"
+(31.0 x 53.0 in)
+@end table
+
+@noindent
+@strong{PA4 based sizes}
+@table @code
+@item "pa0"
+(840 x 1120 mm)
+@item "pa1"
+(560 x 840 mm)
+@item "pa2"
+(420 x 560 mm)
+@item "pa3"
+(280 x 420 mm)
+@item "pa4"
+(210 x 280 mm)
+@item "pa5"
+(140 x 210 mm)
+@item "pa6"
+(105 x 140 mm)
+@item "pa7"
+(70 x 105 mm)
+@item "pa8"
+(52 x 70 mm)
+@item "pa9"
+(35 x 52 mm)
+@item "pa10"
+(26 x 35 mm)
+@end table
+
+@noindent
+@strong{Used in Southeast Asia and Australia}
+@table @code
+@item "f4"
+(210 x 330 mm)
+@end table
+
+@noindent
+@strong{Used for very small @code{@@lilypond} examples in the
+documentation based on a8 landscape.}
+@table @code
+@item "a8landscape"
+(74 x 52 mm)
+@end table
+
+
 @node MIDI instruments
 @appendixsec MIDI instruments
 
diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely
index 64af60f58e..68208d2010 100644
--- a/Documentation/notation/spacing.itely
+++ b/Documentation/notation/spacing.itely
@@ -191,71 +191,81 @@ Installed Files:
 @funindex \paper
 
 @menu
-* Setting paper size::
+* Setting the paper size::
 * Automatic scaling to paper size::
 @end menu
 
 
-@node Setting paper size
-@unnumberedsubsubsec Setting paper size
+@node Setting the paper size
+@unnumberedsubsubsec Setting the paper size
 
-Two functions are available for changing the paper size:
-@code{set-default-paper-size} and @code{set-paper-size}.
-@code{set-default-paper-size} must be placed in the toplevel
-scope, and @code{set-paper-size} must be placed in a @code{\paper}
-block:
+@q{A4} is the default value when no explicit paper size is set. However,
+there are two functions that can be used to change it
+@code{set-default-paper-size},
 
 @example
-#(set-default-paper-size "a4")
+#(set-default-paper-size "quarto")
 @end example
 
+which must always be placed at the toplevel scope. and
+@code{set-paper-size},
+
 @example
 \paper @{
-  #(set-paper-size "a4")
+  #(set-paper-size "tabloid")
 @}
 @end example
 
-@noindent
-In the toplevel scope, the @code{set-default-paper-size} function
-can safely be called anywhere before the first @code{\paper}
-block.  Within a @code{\paper} block, the safest place to call
-@code{set-paper-size} is at the top, above the list of variable
-declarations.  The reasons for this are discussed in
-@ref{Automatic scaling to paper size}.
+which must always be placed in a @code{\paper} block.
 
-@code{set-default-paper-size} sets the size of all pages, whereas
-@code{set-paper-size} only sets the size of the pages that the
-@code{\paper} block applies to.  For example, if the @code{\paper}
-block is at the top of the file, then it will apply the paper size
-to all pages.  If the @code{\paper} block is inside a
+If the @code{set-default-paper-size} function is used in the toplevel
+scope, it must come before the any @code{\paper} block.
+@code{set-default-paper-size} sets the paper size for all pages,
+whereas @code{set-paper-size} only sets the paper size for the pages
+that the @code{\paper} block applies to.  For example, if the
+@code{\paper} block is at the top of the file, then it will apply the
+paper size to all pages.  If the @code{\paper} block is inside a
 @code{\book}, then the paper size will only apply to that book.
 
-Common paper sizes are available, including @code{a4},
-@code{letter}, @code{legal}, and @code{11x17} (also known as
-tabloid).  Many more paper sizes are supported by default.  For
-details, see @file{scm/paper.scm}, and search for the
-definition of @code{paper-alist}.
+When the @code{set-paper-size} function is used, it must be
+placed @emph{before} any other functions used within the same
+@code{\paper} block.  See @ref{Automatic scaling to paper size}.
 
-@c TODO add a new appendix for paper sizes (auto-generated) -pm
+Paper sizes are defined in @file{scm/paper.scm}, and while it is
+possible to add custom sizes, they will be overwritten on subsequent
+software updates.
 
-@warning{The default paper size is @code{a4}.}
+@c An appendix entry exists for paper sizes but is not auto-generated
 
-Extra sizes may be added by editing the definition of
-@code{paper-alist} in the initialization file
-@file{scm/paper.scm}, however they will be overridden on a
-subsequent install.
+The following command can be used in the file to add a custom paper size
+which can then be used with @code{set-default-paper-size} or
+@code{set-paper-size} as appropriate,
 
-@cindex orientation
-@cindex landscape
+@example
+#(set! paper-alist (cons '("my size" . (cons (* 15 in) (* 3 in))) paper-alist))
 
-If the symbol @code{'landscape} is supplied as an argument to
-@code{set-default-paper-size}, pages will be rotated by 90
-degrees, and wider line widths will be set accordingly.
+\paper @{
+  #(set-paper-size "my size")
+@}
+@end example
+
+The units @code{in} (inches), @code{cm} (centimeters) and @code{mm}
+(millimeters) can all be used.
+
+@cindex paper size, orientation
+@cindex page, orientation
+@cindex paper size, landscape
+
+If the symbol @code{'landscape} is added to the paper size function,
+pages will be rotated by 90 degrees, and wider line widths will be set
+accordingly.
 
 @example
 #(set-default-paper-size "a6" 'landscape)
 @end example
 
+The music output will @emph{not} be rotated, just the paper size.
+
 @seealso
 Notation Reference:
 @ref{Automatic scaling to paper size}.
@@ -277,7 +287,7 @@ that the automatic scaling is not triggered by setting the
 @code{paper-width} can influence other values (this is separate
 from scaling and is discussed below).  The
 @code{set-default-paper-size} and @code{set-paper-size} functions
-are described in @ref{Setting paper size}.
+are described in @ref{Setting the paper size}.
 
 The vertical dimensions affected by automatic scaling are
 @code{top-margin} and @code{bottom-margin} (see
diff --git a/scm/paper.scm b/scm/paper.scm
index bd88e11c79..e076d692a3 100644
--- a/scm/paper.scm
+++ b/scm/paper.scm
@@ -128,6 +128,11 @@
   ;; don't use decimals.
   ;; ISO 216 has a tolerance of +- 2mm
 
+  ;; TODO Autogenerate the following list so it appears under the
+  ;; 'Predefined paper sizes' node in notation-appendices.itely
+  ;; currently the list below has been copied and formatted manually.
+  ;; Therefore, please add any new entries to the *itely file as well.
+
   '(("a10" . (cons (* 26 mm) (* 37 mm)))
     ("a9" . (cons (* 37 mm) (* 52 mm)))
     ("a8" . (cons (* 52 mm) (* 74 mm)))
-- 
2.39.5