From 44f10fc9a1304c67ac56dbbc697ef47e65bab9de Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Wed, 17 May 2023 15:07:28 +0530 Subject: [PATCH 1/3] add intro to Rd files --- 07-documenting_R.Rmd | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/07-documenting_R.Rmd b/07-documenting_R.Rmd index fbf3b4a..bd25e5a 100644 --- a/07-documenting_R.Rmd +++ b/07-documenting_R.Rmd @@ -12,12 +12,16 @@ The involvement of the community takes many forms, from authoring to making bug This chapter is aimed at authors and potential authors of R documentation provided by the help files. More specifically, it is for people contributing to the standard documentation and for those developing additional documents using the same tools as the standard documents. Any time you feel that you can clarify and improve existing documentation or provide documentation that is missing, your contribution is welcome and appreciated. If you find it difficult to deal with the markup language, you can ask for help for that part too. Please do not let the material in this chapter stand between the documentation and your desire to help out. However, not every good faith effort to change or extend the documentation will be accepted - sometimes the patch contribution might be incorrect, other times, while a change in wording may make some things clearer and easier to understand, other finer details of some corner case may become less clear, leading to the patch being declined or modified by the member of R Core reviewing it before applying it (if they agree the issue is important enough to fix). -## Guidelines for writing R help files +## Introduction to .Rd files -This section summarises the [recommended style for writing the R help files](https://developer.r-project.org/Rds.html). The R help files are written in “R documentation” (Rd) format, a markup language which resembles LaTeX. An example of the .Rd format is available for [mean.Rd](https://svn.r-project.org/R/trunk/src/library/base/man/mean.Rd). These are intended for writing the core documentations but may also be useful for package writers. Extensive details of writing R documentation files can be found in the [Writing R Extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Writing-R-documentation-files) manual. +The R help files are written in “R documentation” (Rd) format, a markup language which resembles LaTeX. The .Rd file format can be further processed into a variety of formats, including LaTeX, HTML, and plain text. An example of the .Rd format is available for [mean.Rd](https://svn.r-project.org/R/trunk/src/library/base/man/mean.Rd). These are intended for writing the core documentations but may also be useful for package writers. Note: Many R package authors use the R package [roxygen2](https://cran.r-project.org/web/packages/roxygen2/index.html) to write documentation (which eventually creates the .Rd files), however, in this guide we focus on .Rd files only because the manual pages for the base distribution are written directly as .Rd files. +## Guidelines for writing R help files + +This section summarises the [recommended style for writing the R help files](https://developer.r-project.org/Rds.html). Extensive details of writing R documentation files can be found in the [Writing R Extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Writing-R-documentation-files) manual. + There are three main parts of an .Rd file: 1. **Header**: This part is for the basic information of the document/file. For instance, the name of the file, the topics documented, a title, a short textual description, and R usage information for the objects documented. From b19d1c8017e1372f9fa2f038da40c59610e86fb0 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Wed, 17 May 2023 15:09:34 +0530 Subject: [PATCH 2/3] remove extra whitespace --- 07-documenting_R.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/07-documenting_R.Rmd b/07-documenting_R.Rmd index bd25e5a..82a719e 100644 --- a/07-documenting_R.Rmd +++ b/07-documenting_R.Rmd @@ -20,7 +20,7 @@ Note: Many R package authors use the R package [roxygen2](https://cran.r-project ## Guidelines for writing R help files -This section summarises the [recommended style for writing the R help files](https://developer.r-project.org/Rds.html). Extensive details of writing R documentation files can be found in the [Writing R Extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Writing-R-documentation-files) manual. +This section summarises the [recommended style for writing the R help files](https://developer.r-project.org/Rds.html). Extensive details of writing R documentation files can be found in the [Writing R Extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Writing-R-documentation-files) manual. There are three main parts of an .Rd file: From 1171fba89a0fc8e274f12d5bb670b23ee879a95f Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Sat, 1 Jul 2023 14:35:16 +0530 Subject: [PATCH 3/3] Replace .Rd with `.Rd` --- 07-documenting_R.Rmd | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/07-documenting_R.Rmd b/07-documenting_R.Rmd index 82a719e..2d524df 100644 --- a/07-documenting_R.Rmd +++ b/07-documenting_R.Rmd @@ -1,6 +1,6 @@ # Documenting R {#Doc} -The R language has a substantial body of documentation, much of which is contributed by various authors. The help files for R functions are written in 'R documentation' (.Rd) file format. It is a simple markup language with close resemblance to LaTeX. The .Rd file format can be further processed into a variety of formats, including LaTeX, HTML, and plain text. +The R language has a substantial body of documentation, much of which is contributed by various authors. The help files for R functions are written in 'R documentation' (`.Rd`) file format. It is a simple markup language with close resemblance to LaTeX. The `.Rd` file format can be further processed into a variety of formats, including LaTeX, HTML, and plain text. This chapter describes the styleguide for R's documentation, how to document for R, report and review bugs (and/or suggest corrections for them) in the existing documentation. If you are interested in contributing to R's documentation, your contributions are more than welcome. @@ -12,17 +12,17 @@ The involvement of the community takes many forms, from authoring to making bug This chapter is aimed at authors and potential authors of R documentation provided by the help files. More specifically, it is for people contributing to the standard documentation and for those developing additional documents using the same tools as the standard documents. Any time you feel that you can clarify and improve existing documentation or provide documentation that is missing, your contribution is welcome and appreciated. If you find it difficult to deal with the markup language, you can ask for help for that part too. Please do not let the material in this chapter stand between the documentation and your desire to help out. However, not every good faith effort to change or extend the documentation will be accepted - sometimes the patch contribution might be incorrect, other times, while a change in wording may make some things clearer and easier to understand, other finer details of some corner case may become less clear, leading to the patch being declined or modified by the member of R Core reviewing it before applying it (if they agree the issue is important enough to fix). -## Introduction to .Rd files +## Introduction to `.Rd` files -The R help files are written in “R documentation” (Rd) format, a markup language which resembles LaTeX. The .Rd file format can be further processed into a variety of formats, including LaTeX, HTML, and plain text. An example of the .Rd format is available for [mean.Rd](https://svn.r-project.org/R/trunk/src/library/base/man/mean.Rd). These are intended for writing the core documentations but may also be useful for package writers. +The R help files are written in “R documentation” (Rd) format, a markup language which resembles LaTeX. The `.Rd` file format can be further processed into a variety of formats, including LaTeX, HTML, and plain text. An example of the `.Rd` format is available for [mean`.Rd`](https://svn.r-project.org/R/trunk/src/library/base/man/mean`.Rd`). These are intended for writing the core documentations but may also be useful for package writers. -Note: Many R package authors use the R package [roxygen2](https://cran.r-project.org/web/packages/roxygen2/index.html) to write documentation (which eventually creates the .Rd files), however, in this guide we focus on .Rd files only because the manual pages for the base distribution are written directly as .Rd files. +Note: Many R package authors use the R package [roxygen2](https://cran.r-project.org/web/packages/roxygen2/index.html) to write documentation (which eventually creates the `.Rd` files), however, in this guide we focus on `.Rd` files only because the manual pages for the base distribution are written directly as `.Rd` files. ## Guidelines for writing R help files This section summarises the [recommended style for writing the R help files](https://developer.r-project.org/Rds.html). Extensive details of writing R documentation files can be found in the [Writing R Extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Writing-R-documentation-files) manual. -There are three main parts of an .Rd file: +There are three main parts of an `.Rd` file: 1. **Header**: This part is for the basic information of the document/file. For instance, the name of the file, the topics documented, a title, a short textual description, and R usage information for the objects documented. @@ -30,7 +30,7 @@ There are three main parts of an .Rd file: 3. **Footer**: This part is optional. Usually the keyword information is included here. -All the above information is included in a .Rd file within a series of sections with standard names (user-defined sections are also allowed). These sections are discussed below: +All the above information is included in a `.Rd` file within a series of sections with standard names (user-defined sections are also allowed). These sections are discussed below: 1. `\title` section: * Capitalize each word.