\HeaderA{readNEWS}{Read R's NEWS file or a similar one}{readNEWS}
\aliasA{checkNEWS}{readNEWS}{checkNEWS}
\keyword{file}{readNEWS}
\keyword{documentation}{readNEWS}
\begin{Description}\relax
Read \R's NEWS file or a similarly formatted one.
This is an experimental feature, new in R 2.4.0
and may change in several ways.
\end{Description}
\begin{Usage}
\begin{verbatim}
readNEWS(file = file.path(R.home(), "NEWS"), trace = FALSE,
         chop = c("first", "1", "par1", "keepAll"))
checkNEWS(file = file.path(R.home(), "NEWS"))
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{file}] the name of the file which the data are to be read from.
Alternatively, \code{file} can be a \code{\LinkA{connection}{connection}}, which
will be opened if necessary, and can also be a complete URL.  For
more details, see the \code{file} argument of \code{\LinkA{read.table}{read.table}}.
\item[\code{trace}] logical indicating if the recursive reading should be
traced, i.e., print what it is doing.
\item[\code{chop}] a character string specifying how the news entries should
be \emph{chopped}; \code{chop = "keepAll"} saves the full entries.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{readNEWS()} reads a NEWS file; \code{checkNEWS()} checks for common
errors in formatting.  Currently it detects an incorrect number of spaces before
the \code{"o"} item marker.
\end{Details}
\begin{Value}
\code{readNEWS()} returns an (S3) object of class \code{"newsTree"}; effectively
a \code{\LinkA{list}{list}} of lists which is a tree of NEWS entries.

\code{checkNEWS()} returns \code{TRUE} if no suspected errors are found,
or prints a message for each suspected error and returns \code{FALSE}.

Note that this is still experimental and may change in the future.
\end{Value}
\begin{Examples}
\begin{ExampleCode}
NEWStr  <- readNEWS(trace = TRUE)# chop = "first" ( = "first non-empty")
## keep the full NEWS entry text i.e. "no chopping":
NEWStrA <- readNEWS(chop = "keepAll")
object.size(NEWStr)
object.size(NEWStrA) ## (no chopping) ==> about double the size

str(NEWStr, max.level = 3)

str(NEWStr[[c("2.3", "2.3.1")]], max.level=2, vec.len=1)

NEWStr [[c("2.3", "2.3.1", "NEW FEATURES")]]
NEWStrA[[c("2.4", "2.4.0", "NEW FEATURES")]]

# Check the current NEWS file

stopifnot(checkNEWS())

\end{ExampleCode}
\end{Examples}

