Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@

## [Unreleased]

### Added

- Add the `quarto-definition-list` description list format (`DescribeFormat::QuartoDefinitionList`), which writes Quarto's `::: {.definition-list}` div. Quarto 1.11.7+ and q2 render it as a definition list.
- **Breaking:** `DescribeFormat` gains the `QuartoDefinitionList` variant, and `WriterOptions` gains a `definition_list_syntax` field (`DefinitionListSyntax::Pandoc` by default). Exhaustive matches and struct literals must handle them, for example with `..Default::default()`.

### Changed

- **Breaking:** Rename the default description list format to `pandoc-definition-list` (`DescribeFormat::PandocDefinitionList`), naming it after the syntax it uses.
Expand All @@ -12,6 +17,7 @@

### Fixed

- A list item whose first block is a nested list now writes the nested list on the marker line (`- - a`). q2 rejected the previous form, an empty marker line followed by the list.
- Bare brace groups in Rd text (for example `{ a, b } text`) no longer drop their content. The group is now rendered in place without the braces, as R does. Braces inside `\code{}`, `\verb{}` and `\preformatted{}` are unchanged.
- Arguments cells that start with a code block or display equation now render validly in the `list-table` and `list` formats. Previously the `list-table` form failed to parse in Quarto 2.
- Remove a spurious blank line before the closing fence of code blocks in `grid-table` Arguments cells.
Expand Down
7 changes: 6 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ rd2qmd convert man/ -o docs/ -j4
| `--no-frontmatter` | Disable YAML frontmatter; use this for a visible body `# Title` in Markdown consumers that do not render YAML titles |
| `--no-pagetitle` | Skip pkgdown-style `pagetitle` metadata (`"<title> — <name>"`) |
| `--quarto-code-blocks <BOOL>` | Use `{r}` code blocks (auto-set based on format) |
| `--describe-format <FORMAT>` | Description list format: `pandoc-definition-list` (default), `list`, or `headings` (CommonMark/GFM) |
| `--describe-format <FORMAT>` | Description list format: `pandoc-definition-list` (default), `quarto-definition-list` (Quarto 1.11.7+ / q2), `list`, or `headings` (CommonMark/GFM) |
| `--arguments-format <FORMAT>` | Arguments format: `list-table` (default), `grid-table`, `pipe-table`, or `list` |
| `--input-format <FORMAT>` | Input format: `rd` (default) or `ast` (see [AST JSON I/O](#ast-json-io)) |
| `-v, --verbose` | Verbose output |
Expand Down Expand Up @@ -411,6 +411,11 @@ representation, including nested descriptions:
`definition-list` still selects this format, with a deprecation warning.
It will select the Quarto `.definition-list` format in a future release, so
use `pandoc-definition-list` to keep the current output.
- `quarto-definition-list`: Quarto's `::: {.definition-list}` div holding a
bullet list, which Quarto 1.11.7+ and q2 render as a definition list. Each
item is the term followed by a one-item bullet list with its description;
an empty description becomes a zero-width space (`&#8203;`). Older Quarto
versions show it as a nested bullet list.
- `list`: ordinary Markdown bullet lists with bold terms. Preserves paragraphs,
inline formatting, links, code examples, and nested lists in CommonMark/GFM.
- `headings`: terms become headings one level below their enclosing section
Expand Down
5 changes: 5 additions & 0 deletions crates/rd2qmd-cli/schema/rd2qmd.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,11 @@
"type": "string",
"const": "pandoc-definition-list"
},
{
"description": "Quarto definition-list div - requires Quarto 1.11.7+ or q2",
"type": "string",
"const": "quarto-definition-list"
},
{
"description": "Markdown bullet list - supports CommonMark and GFM, including nested descriptions",
"type": "string",
Expand Down
2 changes: 1 addition & 1 deletion crates/rd2qmd-cli/src/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -206,7 +206,7 @@ pub(crate) struct ConvertArgs {
#[arg(long, value_enum)]
pub(crate) arguments_format: Option<CliArgumentsFormat>,

/// Output format for \describe lists, including nested descriptions: pandoc-definition-list (default), list, or headings (CommonMark/GFM). Independent of --arguments-format
/// Output format for \describe lists, including nested descriptions: pandoc-definition-list (default), quarto-definition-list (Quarto 1.11.7+ / q2), list, or headings (CommonMark/GFM). Independent of --arguments-format
#[arg(long, value_enum)]
pub(crate) describe_format: Option<CliDescribeFormat>,

Expand Down
3 changes: 3 additions & 0 deletions crates/rd2qmd-cli/src/config.rs
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@ pub enum DescribeFormat {
/// Pandoc definition list (default) - requires definition-list support
#[default]
PandocDefinitionList,
/// Quarto definition-list div - requires Quarto 1.11.7+ or q2
QuartoDefinitionList,
/// Markdown bullet list - supports CommonMark and GFM, including nested descriptions
List,
/// Terms become headings below their enclosing section; beyond H6, use bullet lists
Expand Down Expand Up @@ -479,6 +481,7 @@ mod describe_format_tests {
fn describe_only_config_survives_serialization() {
for format in [
DescribeFormat::PandocDefinitionList,
DescribeFormat::QuartoDefinitionList,
DescribeFormat::List,
DescribeFormat::Headings,
] {
Expand Down
1 change: 1 addition & 0 deletions crates/rd2qmd-cli/src/config_merge.rs
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,7 @@ pub(crate) fn merge_describe_format(args: &ConvertArgs, config: &Config) -> Desc
CliDescribeFormat::PandocDefinitionList | CliDescribeFormat::DefinitionList => {
DescribeFormat::PandocDefinitionList
}
CliDescribeFormat::QuartoDefinitionList => DescribeFormat::QuartoDefinitionList,
CliDescribeFormat::List => DescribeFormat::List,
CliDescribeFormat::Headings => DescribeFormat::Headings,
}
Expand Down
7 changes: 6 additions & 1 deletion crates/rd2qmd-cli/tests/describe_format.rs
Original file line number Diff line number Diff line change
Expand Up @@ -245,7 +245,12 @@ fn describe_format_snapshots() {
include_str!("fixtures/describe_code_blocks.Rd"),
)
.unwrap();
for format in ["pandoc-definition-list", "list", "headings"] {
for format in [
"pandoc-definition-list",
"quarto-definition-list",
"list",
"headings",
] {
for extension in ["md", "qmd"] {
let filename = format!("output.{extension}");
run_cli(
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
---
source: crates/rd2qmd-cli/tests/describe_format.rs
expression: output
---
# Describe Blocks With Roxygen Code Fences

## Description

Demonstrates the Pandoc definition-list writer's handling of multi-line block children -- roxygen2 fenced code blocks, a nested definition list, and a bulleted list item that itself contains a fenced code block -- inside definition-list item descriptions. Rd authors reach this layout by embedding raw markup in a free-text roxygen2 field, as ggplot2 does when documenting its extensible base classes.

## Methods

::: {.definition-list}

- `compute()`

- **Usage**

```r
compute(a, b)
compute(a, b, extra = TRUE)
combine(a, b)
```

**Arguments**

::: {.definition-list}

- `a`

- The first value.

- `b`

- The second value.

:::

**Examples**

- Basic usage:

```
compute(1, 2)
#> [1] 3
```

- Advanced usage returns invisibly.

**Ordered examples**

1. Basic usage:

```
compute(1, 2)
#> [1] 3
```

2. Advanced usage returns invisibly.

That covers the `compute()` method.

:::
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
---
source: crates/rd2qmd-cli/tests/describe_format.rs
expression: output
---
# Describe Blocks With Roxygen Code Fences

## Description

Demonstrates the Pandoc definition-list writer's handling of multi-line block children -- roxygen2 fenced code blocks, a nested definition list, and a bulleted list item that itself contains a fenced code block -- inside definition-list item descriptions. Rd authors reach this layout by embedding raw markup in a free-text roxygen2 field, as ggplot2 does when documenting its extensible base classes.

## Methods

::: {.definition-list}

- `compute()`

- **Usage**

```r
compute(a, b)
compute(a, b, extra = TRUE)
combine(a, b)
```

**Arguments**

::: {.definition-list}

- `a`

- The first value.

- `b`

- The second value.

:::

**Examples**

- Basic usage:

```
compute(1, 2)
#> [1] 3
```

- Advanced usage returns invisibly.

**Ordered examples**

1. Basic usage:

```
compute(1, 2)
#> [1] 3
```

2. Advanced usage returns invisibly.

That covers the `compute()` method.

:::
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,11 @@ expression: schema
"type": "string",
"const": "pandoc-definition-list"
},
{
"description": "Quarto definition-list div - requires Quarto 1.11.7+ or q2",
"type": "string",
"const": "quarto-definition-list"
},
{
"description": "Markdown bullet list - supports CommonMark and GFM, including nested descriptions",
"type": "string",
Expand Down
1 change: 1 addition & 0 deletions crates/rd2qmd-core/src/convert_ast/assembly.rs
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,7 @@ mod tests {
&WriterOptions {
frontmatter: None,
quarto_code_blocks: options.quarto_code_blocks,
..Default::default()
},
)
}
Expand Down
26 changes: 21 additions & 5 deletions crates/rd2qmd-core/src/convert_ast/blocks/cell.rs
Original file line number Diff line number Diff line change
Expand Up @@ -5,29 +5,45 @@
//! construct, so the nodes are prepared, rendered with
//! [`render_blocks_fragment`], and re-indented under the construct's marker.

use rd2qmd_mdast::{Node, WriterOptions, normalize_inline_boundaries, render_blocks_fragment};
use rd2qmd_mdast::{
DefinitionListSyntax, Node, WriterOptions, normalize_inline_boundaries, render_blocks_fragment,
};

/// Serialize one node through the real writer.
///
/// Used only for nodes flattened into pipe-table cells (code, math,
/// headings), which never contain a definition list.
pub(super) fn node_to_markdown_string(node: &Node) -> String {
render_blocks_fragment(std::slice::from_ref(node), &writer_options())
render_blocks_fragment(
std::slice::from_ref(node),
&writer_options(DefinitionListSyntax::default()),
)
}

fn writer_options() -> WriterOptions {
fn writer_options(definition_list_syntax: DefinitionListSyntax) -> WriterOptions {
WriterOptions {
frontmatter: None,
// The migration context has no writer-format option yet. Preserve the
// legacy call site's default until the document converter is wired.
quarto_code_blocks: true,
definition_list_syntax,
}
}

/// Render block nodes as a cell body whose continuation lines are indented by
/// `indent` spaces. The first line is not indented: the caller places it after
/// its own marker. Empty content yields an empty string.
pub(super) fn render_cell(nodes: &[Node], indent: usize) -> String {
///
/// Cells are rendered during conversion, before the document writer runs, so
/// the definition list syntax must match the one the document uses.
pub(super) fn render_cell(
nodes: &[Node],
indent: usize,
definition_list_syntax: DefinitionListSyntax,
) -> String {
let mut nodes = normalize_inline_boundaries(nodes);
prepare_blocks(&mut nodes, true);
let rendered = render_blocks_fragment(&nodes, &writer_options());
let rendered = render_blocks_fragment(&nodes, &writer_options(definition_list_syntax));
indent_continuation(&rendered, indent)
}

Expand Down
18 changes: 15 additions & 3 deletions crates/rd2qmd-core/src/convert_ast/blocks/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -187,7 +187,11 @@ fn convert_arguments_grid(
let term_text = argument_name(argument, context);
let arg_text = rd2qmd_mdast::format_inline_code(term_text.trim(), false);
let desc_nodes = convert_block_content_ref(argument.description_ref(), context);
let desc_text = render_cell(&desc_nodes, 0);
let desc_text = render_cell(
&desc_nodes,
0,
context.describe_format.definition_list_syntax(),
);
builder.push_record([arg_text, desc_text]);
}

Expand Down Expand Up @@ -220,7 +224,11 @@ fn convert_arguments_list_table(
let term_text = argument_name(argument, context);
let arg_text = rd2qmd_mdast::format_inline_code(term_text.trim(), false);
let desc_nodes = convert_block_content_ref(argument.description_ref(), context);
let desc_text = render_cell(&desc_nodes, 4);
let desc_text = render_cell(
&desc_nodes,
4,
context.describe_format.definition_list_syntax(),
);
(arg_text, desc_text)
})
.collect();
Expand Down Expand Up @@ -258,7 +266,11 @@ fn convert_arguments_list(
let term_text = argument_name(argument, context);
let arg_code = rd2qmd_mdast::format_inline_code(term_text.trim(), false);
let desc_nodes = convert_block_content_ref(argument.description_ref(), context);
let desc_text = render_cell(&desc_nodes, 2);
let desc_text = render_cell(
&desc_nodes,
2,
context.describe_format.definition_list_syntax(),
);
(arg_code, desc_text)
})
.collect();
Expand Down
6 changes: 4 additions & 2 deletions crates/rd2qmd-core/src/convert_ast/blocks/tag_conversion.rs
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,8 @@ pub(super) fn convert_block(
let label = inline::convert_inline_nodes_ref(item.label_ref(), &context.inline);
let body = super::convert_block_content_ref(item.body_ref(), &body_context);
match format {
crate::DescribeFormat::PandocDefinitionList => {
crate::DescribeFormat::PandocDefinitionList
| crate::DescribeFormat::QuartoDefinitionList => {
children.push(Node::definition_term(label));
children.push(Node::definition_description(body));
}
Expand All @@ -115,7 +116,8 @@ pub(super) fn convert_block(
}
match format {
crate::DescribeFormat::Headings => children,
crate::DescribeFormat::PandocDefinitionList => {
crate::DescribeFormat::PandocDefinitionList
| crate::DescribeFormat::QuartoDefinitionList => {
vec![Node::definition_list(children)]
}
crate::DescribeFormat::List => vec![Node::list(false, children)],
Expand Down
Loading
Loading