| % File src/library/base/man/sQuote.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2018 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{sQuote} |
| \alias{sQuote} |
| \alias{dQuote} |
| \title{Quote Text} |
| \description{ |
| Single or double quote text by combining with appropriate single or |
| double left and right quotation marks. |
| } |
| \usage{ |
| sQuote(x, q = getOption("useFancyQuotes")) |
| dQuote(x, q = getOption("useFancyQuotes")) |
| } |
| \arguments{ |
| \item{x}{an \R object, to be coerced to a character vector.} |
| \item{q}{the kind of quotes to be used, see \sQuote{Details}.} |
| } |
| \details{ |
| The purpose of the functions is to provide a simple means of markup |
| for quoting text to be used in the R output, e.g., in warnings or |
| error messages. |
| |
| The choice of the appropriate quotation marks depends on both the |
| locale and the available character sets. Older Unix/X11 fonts |
| displayed the grave accent (ASCII code 0x60) and the apostrophe (0x27) |
| in a way that they could also be used as matching open and close |
| single quotation marks. Using modern fonts, or non-Unix systems, |
| these characters no longer produce matching glyphs. Unicode provides |
| left and right single quotation mark characters (U+2018 and U+2019); |
| if Unicode markup cannot be assumed to be available, it seems good |
| practice to use the apostrophe as a non-directional single quotation |
| mark. |
| |
| Similarly, Unicode has left and right double quotation mark characters |
| (U+201C and U+201D); if only ASCII's typewriter characteristics can be |
| employed, than the ASCII quotation mark (0x22) should be used as both |
| the left and right double quotation mark. |
| |
| Some other locales also have the directional quotation marks, notably |
| on Windows. TeX uses grave and apostrophe for the directional single |
| quotation marks, and doubled grave and doubled apostrophe for the |
| directional double quotation marks. |
| |
| What rendering is used depends on \code{q} which by default depends on |
| the \code{\link{options}} setting for \code{useFancyQuotes}. If this |
| is \code{FALSE} then the undirectional |
| ASCII quotation style is used. If this is \code{TRUE} (the default), |
| Unicode directional quotes are used are used where available |
| (currently, UTF-8 locales on Unix-alikes and all Windows locales |
| except \code{C}): if set to \code{"UTF-8"} UTF-8 markup is used |
| (whatever the current locale). If set to \code{"TeX"}, TeX-style |
| markup is used. Finally, if this is set to a character vector of |
| length four, the first two entries are used for beginning and ending |
| single quotes and the second two for beginning and ending double |
| quotes: this can be used to implement non-English quoting conventions |
| such as the use of guillemets. |
| |
| Where fancy quotes are used, you should be aware that they may not be |
| rendered correctly as not all fonts include the requisite glyphs: for |
| example some have directional single quotes but not directional double |
| quotes. |
| #ifdef windows |
| This is particularly troublesome in Windows \sQuote{Command Prompt} |
| windows, which by default are set up to run in the so-called OEM |
| codepage, which in most locales uses a different encoding from |
| Windows. Further, if the codepage is changed (with \code{chcp.exe}, |
| e.g.\sspace{}to 1252 in a Western European language), the default raster fonts |
| do not support the directional quotes. |
| |
| To work around this, the default for \code{options("useFancyQuotes")} |
| is \code{FALSE} on Windows except for the \code{Rgui} console. There |
| fancy quotes work with the default Courier New font and more elegantly with |
| Lucida Console and default East Asian fonts, but directional double |
| quotes are missing in raster fonts such as Courier and FixedSys. |
| #endif |
| } |
| \value{ |
| A character vector of the same length as \code{x} (after any coercion) |
| in the current locale's encoding. |
| } |
| \seealso{ |
| \link{Quotes} for quoting \R code. |
| |
| \code{\link{shQuote}} for quoting OS commands. |
| } |
| \references{ |
| Markus Kuhn, \dQuote{ASCII and Unicode quotation marks}. |
| \url{https://www.cl.cam.ac.uk/~mgk25/ucs/quotes.html} |
| } |
| % these char strings have to be readable in any locale, |
| % so cannot use \uxxxx (fails in Japanese). |
| \examples{ |
| op <- options("useFancyQuotes") |
| paste("argument", sQuote("x"), "must be non-zero") |
| options(useFancyQuotes = FALSE) |
| cat("\ndistinguish plain", sQuote("single"), "and", |
| dQuote("double"), "quotes\n") |
| options(useFancyQuotes = TRUE) |
| cat("\ndistinguish fancy", sQuote("single"), "and", |
| dQuote("double"), "quotes\n") |
| options(useFancyQuotes = "TeX") |
| cat("\ndistinguish TeX", sQuote("single"), "and", |
| dQuote("double"), "quotes\n") |
| if(l10n_info()$`Latin-1`) { |
| options(useFancyQuotes = c("\xab", "\xbb", "\xbf", "?")) |
| cat("\n", sQuote("guillemet"), "and", |
| dQuote("Spanish question"), "styles\n") |
| } else if(l10n_info()$`UTF-8`) { |
| options(useFancyQuotes = c("\xc2\xab", "\xc2\xbb", "\xc2\xbf", "?")) |
| cat("\n", sQuote("guillemet"), "and", |
| dQuote("Spanish question"), "styles\n") |
| } |
| options(op) |
| } |
| \keyword{character} |