change the reference manual ot times/courier by default, and allow

lm and cm-super as options.


git-svn-id: https://svn.r-project.org/R/trunk@30913 00db46b3-68df-0310-9c12-caf00c1e9a41

INSTALL

@@ -38,6 +38,9 @@ and make the manuals by (as many options as preferred from)
 	make pdf	to create PDF versions
 	make info	to create info files
 
+However, please read the notes in `R-admin.html' about making the
+reference manual.
+
 
 INSTALLATION
 

NEWS

@@ -161,7 +161,8 @@ NEW FEATURES
 	represent the DLL within R.
 
     o	help() now returns information about available documentation for
-	a given topic, and notifies about multiple matches.
+	a given topic, and notifies about multiple matches.  It has a
+	separate print() method.
 
     o	heatmap() has a new argument 'reorderfun'.
 
@@ -470,6 +471,10 @@ INSTALLATION CHANGES
     o   f2c is not allowed on 64-bit platforms, as it uses longs for
 	Fortran integers.
 
+    o   There are new options on how to make the PDF version of the
+	reference manual -- see the 'R Administration and Installation
+	Manual' section 2.2.
+
 
 PACKAGE INSTALLATION CHANGES
 

doc/manual/Makefile.win

@@ -39,8 +39,11 @@ endif
 
 R_PAPERSIZE = a4
 R_RD4DVI = ae
-# set the next to `ae' to omit the hyperlinks
-R_RD4PDF = ae,hyper
+# omit 'hyper' to omit the hyperlinks
+R_RD4PDF = times,hyper
+#R_RD4PDF = lm,hyper
+#R_RD4PDF = cm-super,hyper
+#R_RD4PDF = ae,hyper
 
 R_PKGS_refman = base datasets grDevices graphics grid methods stats tools utils
 refman_TEXINPUTS = $(R_PKGS_refman:=-pkg.tex)

doc/manual/R-admin.texi

@@ -416,10 +416,53 @@ You will not be able to build the info files unless you have
 
 The DVI versions can be previewed and printed using standard programs
 such as @command{xdvi} and @command{dvips}.  The PDF versions can be
-viewed using Acrobat Reader or (fairly recent versions of) ghostscript:
-they have hyperlinks that can be followed in Acrobat Reader.  The info
-files are suitable for reading online with Emacs or the standalone GNU
-Info.
+viewed using Acrobat Reader or (fairly recent versions of)
+@command{ghostscript}: they have hyperlinks that can be followed in
+Acrobat Reader.  The info files are suitable for reading online with
+Emacs or the standalone GNU Info.
+
+There are some issues with making the reference manual, and in
+particular with the PDF version @file{refman.pdf}.  The help files
+contain both ISO Latin1 character (e.g. in @file{text.Rd}) and upright
+quotes, neither of which are contained in the standard LaTeX Computer
+Modern fonts.  We have provided four alternatives:
+@itemize @bullet
+@item @code{times}
+Using standard PostScript fonts.  This works well both for on-screen
+viewing and for printing, and is the default from @R{} 2.0.0.  The one
+disadvantage is that the Usage and Examples sections may come out rather
+wide.
+
+@item @code{lm}
+Using the @emph{Latin Modern} fonts.  These are not often installed as
+part of a TeX distribution, but can obtained from
+@uref{http://www.ctan.org/tex-archive/fonts/ps-type1/lm} and mirrors.
+This uses fonts rather similar to Computer Modern, but is not so good
+on-screen as @code{times}.
+
+@item @code{cm-super}
+Using type-1 versions of the Computer Modern fonts by Vladimir Volovich.
+This is a large installation, obtainable from
+@uref{http://www.ctan.org/tex-archive/fonts/ps-type1/cm-super} and
+mirrors.  These type-1 fonts have poor hinting and so are nowhere near
+so readable on-screen as the other three options.
+
+@item @code{ae}
+A package to use composites of Computer Modern fonts.  This works well
+most of the time, and its PDF is more readable on-screen than the
+previous two options.  There are three fonts for which it will need to
+use bitmapped fonts, @file{tctt0900.600pk}, @file{tctt1000.600pk} and 
+@file{tcrm1000.600pk}.  Unfortunately, if those files are not available,
+Acrobat Reader will substitute completely incorrect glyphs so you need
+to examine the logs carefully.  This was the default in @R{} version 1.x.y.
+@end itemize
+
+Both Unix and Windows installations default to @code{times}.  The choice
+can be overridden by setting the environment variable @code{R_RD4PDF}.
+(On Unix, this will be picked up at install time.)  The default value is
+@code{times,hyper}: omit @code{hyper} if you do not want hyperlinks,
+e.g. for printing.
+
 
 @node Installation,  , Making the manuals, Installing R under Unix
 @section Installation
@@ -1065,6 +1108,9 @@ is a good idea to remove that file (if it exists) before re-configuring.
 Note that caching is turned @emph{off} by default: use the command line
 option @option{--config-cache} (or @option{-C}) to enable caching.
 
+The default settings for making the manuals are controlled by
+@env{R_RD4PDF} and @env{R_RD4DVI}.
+
 @node Using make, Using FORTRAN, Configuration variables, Configuration on Unix
 @section Using make
 @findex make

doc/manual/README

@@ -8,23 +8,18 @@ It also uses the standard package bm, which is part of the standard
 tools bundle and should be part of any reasonably recent LaTeX
 installation.
 
-The reference manual is made using the ae virtual fonts package. If
+The reference manual is made using the times fonts package. If
 you do not have that available, you can get it from CTAN, or set the
 environment variable R_RD4DVI to "", but the latin1 characters in
-text.Rd (and a few other places) will be missing.  The ae font package
-provides a reasonable approximation.  You will get better rendition by
-setting R_RD4DVI to "" using a Rd.cfg containing
-
-\usepackage[T1]{fontenc}
-
-BUT you cannot use type-1 postscript fonts with that setting.
+text.Rd (and a few other places) will be missing.  Other alternatives
+are discussed in the R-admin manual.
 
 
 Support for making PDF versions of the manuals is currently
 experimental.  You will need pdf(la)tex and the hyperref package (and
 ae, see above).  Hyperref versions 6.56, 6.67 and 6.69 are known to
 work.  If you want to avoid making the hyperlinks, you can set the
-environment variable R_RD4PDF to "ae" (or even to "").
+environment variable R_RD4PDF to "times" (or even to "").
 
 You may well have to increase the poolsize of your pdflatex to process
 the reference manual with hyperlinks, particularly with later versions
@@ -34,5 +29,5 @@ pdftex-0.14d you will also need to increase max_strings, for example
 to 50000.  The UNIX Makefile does this for you via environment variables,
 which should cover most UNIX TeX systems.
 
-pdftex-0.14d and later will warn (correctly) about missing hyperlinks
-in forming refman.pdf and R-exts.pdf.
+pdftex will warn (correctly) about missing hyperlinks in forming
+refman.pdf.

m4/R.m4

@@ -173,7 +173,7 @@ else
 fi
 : ${R_RD4DVI="ae"}
 AC_SUBST(R_RD4DVI)
-: ${R_RD4PDF="ae,hyper"}
+: ${R_RD4PDF="times,hyper"}
 AC_SUBST(R_RD4PDF)
 ])# R_PROG_TEXMF
 

share/texmf/Rd.sty

@@ -4,6 +4,7 @@
 %%% Modified 1998/07/07 by Martin Maechler
 %%% Modified 1999/11/20 by Brian Ripley
 %%% Modified 1999/12/26 by Kurt Hornik
+%%% and so on.
 
 \NeedsTeXFormat{LaTeX2e}
 \ProvidesPackage{Rd}{}
@@ -12,8 +13,16 @@
 \newboolean{Rd@has@ae}
 \newboolean{Rd@use@ae}
 \newboolean{Rd@use@hyper}
+\newboolean{Rd@has@times}
+\newboolean{Rd@use@times}
+\newboolean{Rd@use@cm-super}
+\newboolean{Rd@has@lm}
+\newboolean{Rd@use@lm}
 \DeclareOption{ae}{\setboolean{Rd@use@ae}{true}}
 \DeclareOption{hyper}{\setboolean{Rd@use@hyper}{true}}
+\DeclareOption{times}{\setboolean{Rd@use@times}{true}}
+\DeclareOption{lm}{\setboolean{Rd@use@lm}{true}}
+\DeclareOption{cm-super}{\setboolean{Rd@use@cm-super}{true}}
 \ProcessOptions
 \RequirePackage{longtable}
 \setcounter{LTchunksize}{250}
@@ -216,6 +225,18 @@
   \input{t1aett.fd}
   \DeclareFontShape{T1}{aett}{bx}{n}{<->ssub*aett/m/n}{}}
   {\message{NOT loading ae}}
+\IfFileExists{times.sty}{\setboolean{Rd@has@times}{true}}{}
+\ifthenelse{\boolean{Rd@use@times}\and\boolean{Rd@has@times}}{%
+  \usepackage[T1]{fontenc}
+  \usepackage{times}}
+  {\message{NOT loading times}}
+\IfFileExists{lmodern.sty}{\setboolean{Rd@has@lm}{true}}{}
+\ifthenelse{\boolean{Rd@use@lm}\and\boolean{Rd@has@lm}}{%
+  \usepackage[T1]{fontenc}
+  \usepackage{lmodern}}
+  {\message{NOT loading lmodern}}
+\ifthenelse{\boolean{Rd@use@cm-super}}{%
+  \usepackage[T1]{fontenc}}{}
 
 \ifthenelse{\boolean{Rd@use@hyper}}{%
   \RequirePackage{color}    

src/gnuwin32/INSTALL

@@ -224,7 +224,7 @@ and configured to work with a large file: see doc/manual/README.  You
 also need texindex (included in our tool set).  Then the pdf manuals
 can be made by
 
-	make docs
+	make manuals
 
 If you want to make the info versions (not the Reference Manual), use
 
@@ -238,13 +238,10 @@ To make DVI versions of the manuals use
 
 (assuming you have tex and latex installed and in your path).
 
-To make HTML versions of the manuals (not the Reference Manual) use
-
-	cd ../../doc/manual
-	make -f Makefile.win html
-
 The fptex distribution of TeX (via www.fptex.org) includes a suitable
-port of pdftex.
+port of pdftex.  Please read the section in R-admin.html about how to
+make 'refman.pdf' and set the environment variables R_RD4DVI and
+R_RD4PDF suitably and ensure you have the required fonts installed.
 
 
 Building the installers