TeXCheckR

Description

Checks LaTeX documents and .bib files for typing errors, such as spelling errors, incorrect quotation marks. Also provides useful functions for parsing and linting bibliography files.

List of correctly spelled, case-sensitive words

Description

List of correctly spelled, case-sensitive words

Usage

CORRECTLY_SPELLED_WORDS_CASE_SENSITIVE

Format

A character vector of words as perl-regex case-sensitive patterns to skip during the spell check.

Are any bib entries duplicated?

Description

Are any bib entries duplicated?

Usage

any_bib_duplicates(bib.files, .report_error, rstudio = FALSE)

Arguments

Details

This function is very fastidious about the format of bib.files. Run lint_bib (noting that this will overwrite your bibliography) if it complains.

This function finds exact duplicates in the author title date/year and volume fields. Note that it is not possible in general to detect actual duplicates; you will still need to inspect the printed bibliography.

Value

Called for its side-effect. If duplicates are detected, the first six are printed as a data.table; otherwise, NULL, invisibly.

Replace nth arguments

Description

Replace nth arguments

Usage

replace_nth_LaTeX_argument(
  tex_lines,
  command_name,
  n = 1L,
  replacement = "correct",
  optional = FALSE,
  warn = TRUE,
  .dummy_replacement = "Qq"
)

nth_arg_positions(
  tex_lines,
  command_name,
  n = 1L,
  optional = FALSE,
  star = TRUE,
  data.tables = TRUE,
  allow_stringi = TRUE
)

Arguments

Details

nth_arg_positions reports the starts and stops of the command for every line. This includes the braces (in order to accommodate instances where the argument is empty).

If the line is empty or does not contain the command the values of starts and stops are NA_integer_.

Examples

nth_arg_positions("This is a \\textbf{strong} statement.", "textbf")
replace_nth_LaTeX_argument("This is a \\textbf{strong} statement.", "textbf")

Functions for parsing .bib files

Description

Functions for parsing .bib files

Usage

fread_bib(
  file.bib,
  check.dup.keys = TRUE,
  strip.braces = TRUE,
  check.unescaped.percent = TRUE,
  .bib_expected = TRUE,
  halt = TRUE,
  rstudio = FALSE,
  .report_error
)

bib2DT(file.bib, to_sort = FALSE)

reorder_bib(file.bib, outfile.bib = file.bib)

Arguments

Details

bib2DT returns a data.table of the entries in file.bib. The function reorder_bib rewrites file.bib, to put it in surname, year, title, line number order.

Brace closes at

Description

Where do braces close?

Usage

braces_closes_at(tex_line, position_of_opening_brace)

Arguments

Value

The positions of the closing brace matching the opening braces at position_of_opening_brace.

Check biber

Description

Check biber

Usage

check_biber(path = ".", rstudio = FALSE)

Arguments

Check consecutive typeset words

Description

Check consecutive typeset words

Usage

check_consecutive_words(
  path = ".",
  latex_file = NULL,
  md5sum.ok = NULL,
  outfile = NULL,
  outfile.append = FALSE
)

Arguments

Value

NULL if the LaTeX document does not create a PDF with lines repeated. An error if words are repeated on consecutive lines, together with cat() output of the offending lines. The output is presented in 'stanzas':

'<Repeated word>'
        <Context>

for example a document that results in the following lines, notably the repetition of household, the output would be:

'household'
        affordable. This `mortgage burden' is often defined as the proportion of
        household income spent on repaying a mortgage. Depending on the
        household income measure used, the mortgage burden on a newly
        purchased first home, assuming a person borrows 80 per cent of the
        value of the home, is currently lower than much of the period between

Lastly the error message contains the md5sum of the file is returned in the error message, so it can be supplied to md5sum.ok.

Check dashes entered as hyphens

Description

Check dashes entered as hyphens

Usage

check_dashes(
  filename,
  .report_error,
  dash.consistency = c("en-dash", "em-dash"),
  protases_ok = TRUE,
  rstudio = TRUE
)

Arguments

Value

File stops and cat()s on any line where a hyphen is surrounded by a space. Excludes dashes in knitr chunks and LaTeX math mode \(...\) but not in TeX math mode $...$.

Check escapes

Description

Checks file for unescaped dollar signs. With these present, there is a risk of constructions like We gave $10 to a million people at a cost of $10~million dollars., which is valid syntax, but incorrectly formatted. Accordingly, math-mode must be more assertively requested using \(..\).

Usage

check_escapes(filename, .report_error)

Arguments

Value

An error if unescaped dollar signs are present in filename. Otherwise, NULL invisibly.

Check footnote typography

Description

Check footnote typography

Usage

check_footnote_typography(
  filename,
  ignore.lines = NULL,
  .report_error,
  rstudio = FALSE
)

Arguments

Details

See https://github.com/grattan/grattex/blob/master/doc/grattexDocumentation.pdf for full set of error conditions.

Value

Called for its side-effect.

Examples

## Not run: 
  tex_file <- tempfile(fileext = ".tex")
  cat("Footnote not ending with full stop.\\footnote{No sentence}", file = tex_file)
  check_footnote_typography(tex_file)

## End(Not run)

Check labels

Description

Check labels

Usage

check_labels(filename, .report_error, check.chaprefs = TRUE)

Arguments

Details

Checks each label has a prefix and the prefix is one of the following: fig:, tbl:, box:, chap:, sec:, eq:, subsec:, subsubsec:, para: paragraph:. Checks also that chapter labels are marked with chap:. (N.B. although each label must have a prefix, it must not necessarily the right prefix; for example, a table caption may have prefix tbl:.)

Value

NULL, invisibly if labels check out. An error otherwise.

Check that citations are all using cites

Description

Check that citations are all using cites

Usage

check_literal_citations(filename, .report_error)

Arguments

Check for hard-coded cross-references

Description

Check for hard-coded cross-references

Usage

check_literal_xrefs(filename, .report_error)

Arguments

Value

An error, or if none found, NULL invisibly.

Check quote marks in TeX

Description

Checks whether a closing quote has been used at the start of a word.

Usage

check_quote_marks(filename, .report_error, rstudio = FALSE)

Arguments

Examples

## Not run: 
  tex_file <- tempfile(fileext = ".tex")
  cat("This is the wrong 'quote' mark.", file = tex_file)
  check_quote_marks(tex_file)
  file.remove(tex_file)

## End(Not run)

Spell checking

Description

Spell checking

Usage

check_spelling(
  filename,
  tex_root = dirname(filename),
  pre_release = TRUE,
  ignore.lines = NULL,
  known.correct = NULL,
  known.correct.fixed = NULL,
  known.wrong = NULL,
  ignore_spelling_in = NULL,
  ignore_spelling_in_nth = NULL,
  bib_files,
  check_etcs = TRUE,
  dict_lang = "en_GB",
  rstudio = FALSE,
  .report_error
)

Arguments

Details

Extends and enhances hunspell:

• You can add directives in the document itself. To add a word foobaz to the dictionary (so its presence does not throw an error), write % add_to_dictionary: foobaz on a single line. The advantage of this method is that you can collaborate on the document without having to keep track of which spelling errors are genuine.

• The directive % ignore_spelling_in: mycmd which will ignore the spelling of words within the first argument of \mycmd.

• ignore_spelling_in_file: <file.tex> will skip the check of <file.tex> if it is input or include in filename, as well as any files within it. Should appear as it is within input but with the file extension

• Only the root document need be supplied; any files that are fed via \input or \include are checked (recursively).

• A historical advantages was that the contents of certain commands were not checked, the spelling of which need not be checked as they are not printed, viz. citation and cross-reference commands, and certain optional arguments. Most of these are now parsed correctly by hunspell, though some still need to be supplied (including, naturally, user-supplied macros).

• Abbreviations and initialisms which are validly introduced will not throw errors. See extract_valid_abbrevations.

• Words preceded by '[sic]' will not throw errors.

The package comes with a suite of correctly_spelled_words that were not present in hunspell's dictionary.

This function should be quite fast, but slower than hunspell::hunspell (which it invokes). I aim for less than 500 ms on a real-world report of around 100 pages. The function is slower when it needs to consult bib_files, though I recommend adding authors, titles, etc. to the dictionary explicitly, or using citeauthor and friends.

This function is forked from https://github.com/hughparsonage/grattanReporter to parse reports of the Grattan Institute, Melbourne for errors. See https://github.com/grattan/grattex/blob/master/doc/grattexDocumentation.pdf for the full spec. Some checks that package performs have been omitted in this package.

Value

Called primarily for its side-effect. If the spell check fails, the line at which the first error was detected, with an error message. If the check succeeds, NULL invisibly.

Examples

## Not run: 
url_bib <- 
paste0("https://raw.githubusercontent.com/HughParsonage/",
       "grattex/e6cab97145d38890e44e83d122e995e3b8936fc6/",
       "Report.tex")
check_spelling(url_bib)

## End(Not run)

Check cross-references

Description

Check cross-references that are repetitive or (in the case of ⁠cleveref⁠ and ⁠varioref⁠) incorrect case.

Usage

check_xrefs(filename, permitted.case = c(NA, "upper", "lower"), .report_error)

Arguments

List all unique commands in a document

Description

List all unique commands in a document

Usage

commands_used(tex_lines)

Arguments

Value

A character vector of unique commands used in tex_lines.

Examples

commands_used(c("A \\abc{d}", "\\def{x}"))

List of correctly spelled words

Description

List of correctly spelled words

Usage

correctly_spelled_words

Format

A character vector of words as perl-regex patterns to skip during the spell check.

Extract LaTeX command argument

Description

This is a simple wrapper around extract_mandatory_LaTeX_argument and extract_optional_LaTeX_argument.

Usage

extract_LaTeX_argument(tex_lines, command_name, n = 1L, optional = FALSE)

Arguments

Extract mandatory argument II

Description

Extract mandatory argument II

Usage

extract_mandatory_LaTeX_argument(
  tex_lines,
  command_name,
  n = 1L,
  by.line = FALSE,
  parsed_doc = NULL
)

Arguments

Extract optional argument

Description

Extract optional argument

Usage

extract_optional_LaTeX_argument(
  tex_lines,
  command_name,
  n = 1L,
  by.line = FALSE
)

Arguments

Extract valid abbreviations and initialisms

Description

Extracts abbreviations which are preceded by the full text (e.g. 'The Quebec Xylophone Enterprise Foundation (QXEF)').

Usage

extract_validate_abbreviations(lines)

Arguments

Details

Only 'valid' abbreviations are extracted, viz. those abbreviations of the form (ABC) where the first letters of the preceding words (excluding some common words like of, and, etc.) are 'a', 'b', 'c'.

Value

Character vector of abbreviations of the form (ABC)

Return unreferenced figures or tables in document

Description

Useful for checking whether all the figures and tables in a document have been referenced in the main text. You may exclude figures and tables from the check by using the directive % may_be_left_unreferenced: in the preamble before the label that is to be excluded.

Usage

figs_tbls_unrefd(filename, .report_error, check.labels = TRUE)

Arguments

Value

The labels of any figure or table left unreferenced in filename (including inputs).

Inputs to files nested within LaTeX document

Description

Inputs to files nested within LaTeX document

Usage

inputs_of(filename, exclude.preamble = TRUE, append.tex = TRUE)

Arguments

Value

A character vector of file paths relative to filename that are used as \inputs or \includes within filename. If no such files are present within filename, NULL is returned.

Is a line in knitr R or not?

Description

Is a line in knitr R or not?

Usage

isR_line_in_knitr(lines)

Arguments

Value

TRUE if in knitr chunk (including boundaries). FALSE otherwise.

Tidy bibliography so equals signs align

Description

Tidy bibliography so equals signs align

Usage

lint_bib(bib_file, outfile = bib_file, leading_spaces = 2L)

Arguments

Details

Aligns the equals signs in bib_file and ensures all fields have a trailing comma.

Locate contents of LaTeX commands

Description

Provides the locations of LaTeX commands with mandatory arguments.

Usage

locate_mandatory_LaTeX_argument(
  tex_lines,
  command_name,
  n = 1L,
  parsed_doc = NULL
)

Arguments

Generate a minimal bibliography file

Description

Generate a minimal bibliography file

Usage

minimal_bib(path = ".", bbl.file = NULL, bib.files = NULL, out.bib = bib.files)

Arguments

Parse LaTeX lines

Description

Parse LaTeX lines

Usage

parse_tex(tex_lines)

Arguments

Value

A data.table where each row identifies a unique character in tex_lines.

line_no

Matches the index of tex_lines.

char_no

The character within line_no.

char

The character. A single character.

tex_group

The TeX group by default. Any delimiters can be used.

optional_tex_group

(If any present), the optional TeX group.

tgi

The number of braces opened at the i-th current TeX group level.

GROUP_IDi

An integer identifying the unique contiguous block at the TeX group at or above the current group level.

GROUP_IDi

The analog for optional groups.

If tex_lines is zero-length, a null data.table.

Examples

parse_tex(c("A{}", "B[a]{b{c}{d}}z"))
# The version transposed:
#
#>          char : A{}B[a]{b{c}{d}}z
#>           tg1 : 011111122......22
#>           tg2 : 00000000011122222
#>           og1 : 00001111111111111
#>     GROUP_ID1 : .11....222222222.
#>     GROUP_ID2 : .........111222..
#> OPT_GROUP_ID1 : ....111..........

Position of strings

Description

Position of strings

Usage

position_of_string(tex_line_split, command_split, end = TRUE)

positions_of_all_strings(tex_line, command_name, end = TRUE)

Arguments

Value

The end (or start if end = FALSE) of the location of command

Read a LaTeX document

Description

Read a LaTeX document

Usage

read_tex_document(file_root)

Arguments

Report errors to console

Description

Report errors to console

Usage

report2console(
  file = NULL,
  line_no = NULL,
  column = NULL,
  context = NULL,
  error_message = NULL,
  advice = NULL,
  build_status = NULL,
  extra_cat_ante = NULL,
  extra_cat_post = NULL,
  caret = FALSE,
  rstudio = FALSE,
  log_file = NULL,
  log_file_sep = "|",
  silent = FALSE,
  halt = getOption("TeXCheckR.halt_on_error", FALSE),
  as_tbl = getOption("TeXCheckR.error_as_tbl", FALSE)
)

Arguments

Remove editorial square brackets

Description

Change text such as phas[e] out to phase out, without removing square brackets denoting optional arguments.

Usage

rm_editorial_square_brackets(tex_lines)

Arguments

Examples

x <- "the BCA's call to `urgently phas[e] out all side deals'"
rm_editorial_square_brackets(x)

Put sentences on their own line

Description

Put sentences on their own line

Usage

separate_sentences(filename, hanging_footnotes = FALSE)

Arguments

Value

NULL. The function is called for its side-effect: rewriting filename with separated sentences.

Split report into include-able files

Description

Split report into include-able files

Usage

split_report(
  Report.tex,
  include = TRUE,
  subdir = "tex",
  use.chapter.title = TRUE,
  out.tex = Report.tex
)

Arguments

Strip comments from LaTeX lines

Description

Strip comments from LaTeX lines

Usage

strip_comments(lines, retain.percent.symbol = TRUE)

Arguments

Value

lines but with all text to the right of every unescaped ⁠%⁠ removed

Examples

some_lines <- c("Text. % A comment", "20\\% of comments are % useful")
strip_comments(some_lines)
strip_comments(some_lines, retain.percent.symbol = FALSE)

TeX group by character position

Description

Opening a brace increases the 'group' in TeX. For example, in a{bc}{d{e}} a is in group 0, bc in group 1 as is d and e is in group 2.

Usage

tex_group_by_char(tex_lines, optional = FALSE)

Arguments

Value

A list the same length as lines. Each element an integer vector indicating the TeX group at that position.

For positions at braces the upcoming group is returned. So a{b} should return 0 1 1 0 (in its first element).

Examples

tex_group_by_char("a{bc}{d{e}}")

Valid English contractions

Description

List of words which should never raise a spelling error.

Usage

valid_English_contractions

Format

An object of class character of length 110.

Source

https://gist.githubusercontent.com/J3RN/ed7b420a6ea1d5bd6d06/raw/acda66b325a2b4d7282fb602a7551912cdc81e74/contractions.txt

Validate bibliography according to Grattan style

Description

Validate bibliography according to Grattan style

Usage

validate_bibliography(path = ".", file = NULL, .report_error, rstudio = FALSE)

Arguments

Details

This is a highly fastidious test of the bibliography. Useful for collaboration to ensure consistent style.

Value

NULL if bibliography validated.

Examples

## Not run: 
bib_temp <- tempfile(fileext = ".bib")
url_bib <- 
  paste0("https://raw.githubusercontent.com/HughParsonage/",
         "grattex/e6cab97145d38890e44e83d122e995e3b8936fc6",
         "/bib/Grattan-Master-Bibliography.bib")

download.file(url_bib, destfile = bib_temp)
validate_bibliography(file = bib_temp)

bib_temp <- tempfile(fileext = ".bib")
url_bib <- 
  paste0("https://raw.githubusercontent.com/HughParsonage/",
         "grattex/8f7f52a28789d12a363ceb30cea3b41f590ae58a",
         "/bib/Grattan-Master-Bibliography.bib")
download.file(url_bib, destfile = bib_temp)
validate_bibliography(file = bib_temp)

## End(Not run)

Veto sic

Description

Vetoes words in a LaTeX document that are marked '[sic]' for the purpose of spell checking by replacing them (and '[sic]' itself) with white space of equal length.

Usage

veto_sic(tex_lines, quote = TRUE, sentence = !quote, words_ante = 1L)

Arguments

Unbreaking spaces between billion and million

Description

Unbreaking spaces between billion and million

Usage

weld_bmillion(filename, outfile = filename)

Arguments

Value

NULL. This function is called for its side-effect: rewriting filename with 30 million changed to 30~million.

List of wrongly spelled words

Description

List of wrongly spelled words

Usage

wrongly_spelled_words

Format

A regex of patterns to raise as spelling errors.