Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use of markdown headings in roxygen with @md is not caught or handled #804

Closed
tbates opened this issue Oct 18, 2018 · 8 comments
Closed

Use of markdown headings in roxygen with @md is not caught or handled #804

tbates opened this issue Oct 18, 2018 · 8 comments

Comments

@tbates
Copy link
Contributor

@tbates tbates commented Oct 18, 2018

If one uses a markdown heading ( # ) in roxygen with @md tag, the heading is generated, but causes a warning (Unknown xml node: heading) on package load.

EXPECTED: Either the currently invalid heading code is caught, or rendered as something legal.

Here's an example chunk of roxygen and a tmp function which if included in a package will generate the illegal xml warning.

#' Headings in Rd are not flagged, but don't work
#'
#' @description test function for headings
#' ## Markdown heading will generate "1: Unknown xml node: heading" warning message on load.
#' 
#' Should either flag the heading code as an error, or render something supported by Rd.
#' 
#' *note*: Add fn to a package and load to see the warning
#'
#' @return - 
#' @export
#' @md
tmp <- function(x) {
    just a demo
}

version:

> packageVersion("roxygen2")
[1] ‘6.1.0’
@hadley hadley added this to the v6.2.0 milestone Aug 22, 2019
@hadley
Copy link
Member

@hadley hadley commented Aug 22, 2019

Minimal reprex:

library(roxygen2)
x <- roc_proc_text(rd_roclet(), "
  #' title
  #' @md
  #' @description
  #' ## Heading 2
  f <- function() {}
")[[1]]
#> Warning: Unknown xml node: heading

Created on 2019-08-22 by the reprex package (v0.3.0)

Even more minimal reprex:

roxygen2:::full_markdown("## Heading\n")
#> Warning: Unknown xml node: heading

@gaborcsardi
Copy link
Collaborator

@gaborcsardi gaborcsardi commented Aug 22, 2019

This was never supposed to work, use @section to create sections. The error message could be better though.

@tbates
Copy link
Contributor Author

@tbates tbates commented Aug 22, 2019

maybe

Markdown headings not supported. Replace with @section to create sections.

@hadley hadley closed this in 844e14a Aug 22, 2019
@tbates
Copy link
Contributor Author

@tbates tbates commented Aug 22, 2019

Nice!
Has gone from 4 unallocated notes about xml heading not supported, to a full line-linked check!!

Updating umx documentation
Warning: @param [umx/R/build_run_modify.R#4271]: Use of inline HTML is not currently supported
Warning: @details [umx/R/lavanify2ram.R#15]: Use of markdown headings is not currently supported
Warning: @details [umx/R/lavanify2ram.R#15]: Use of inline HTML is not currently supported
Warning: @details [umx/R/lavanify2ram.R#15]: Use of inline HTML is not currently supported
Warning: @description [umx/R/misc_and_utility.R#90]: Use of inline HTML is not currently supported
Warning: @description [umx/R/misc_and_utility.R#90]: Use of inline HTML is not currently supported
Warning: @param [umx/R/misc_and_utility.R#105]: Use of inline HTML is not currently supported
Warning: @description [umx/R/misc_and_utility.R#1]: Use of markdown headings is not currently supported
Warning: @param [umx/R/misc_and_utility.R#1310]: Use of markdown headings is not currently supported
Warning: @details [umx/R/misc_and_utility.R#1]: Use of inline HTML is not currently supported
Warning: @description [umx/R/misc_and_utility.R#1]: Use of inline HTML is not currently supported
Warning: @details [umx/R/umx_build_umxSexLim.R#1]: Use of markdown headings is not currently supported

@tbates
Copy link
Contributor Author

@tbates tbates commented Aug 27, 2019

FYI, lack of line numbers (nearly always #1) and non-printing of the offending string means it's hard to find.
e.g. these are each 10,000 line files... and the markdown heading is #....

Updating umx documentation
Warning: @description [R/misc_and_utility.R#1]: Use of markdown headings is not currently supported
Warning: @details [R/misc_and_utility.R#1]: Use of inline HTML is not currently supported
Warning: @description [R/misc_and_utility.R#1]: Use of inline HTML is not currently supported
Warning: @details [R/umx_build_umxSexLim.R#1]: Use of markdown headings is not currently supported

@hadley
Copy link
Member

@hadley hadley commented Aug 27, 2019

That's issue #664 (but it shouldn't be hard to grep for #' # ?)

@tbates
Copy link
Contributor Author

@tbates tbates commented Aug 27, 2019

except that 99% of hits are in examples:

#' # ============================================
#' # = 1. Here's a simple example with raw data =
#' # ============================================
#' # 2. Use parameters to see the parameter estimates and labels

@gaborcsardi
Copy link
Collaborator

@gaborcsardi gaborcsardi commented Sep 13, 2019

@tbates FYI, you'll be able to use markdown headings, once these are merged: #907, #908.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants