Perfecting the resdoc_word2 output

[seananderson]

It sounds like the writing is on the wall that we'll have to work with .docx output across all regions soon. The new resdoc_word2() by @PaulRegular with officedown and officer looks like a big improvement. I wanted to wrap my head around the remaining known issues. Maybe some of these are already working, but we need to fix the example template. Others may be easily fixable. Others may be too hard to fix and we can just push back that this is something CSAS is going to have to deal with.

Here are some things I see in the default template:

1. References cited appears before appendices but the reference list appears at the end.

2. Appendices get sequential numbers that continue and the letter isn't in the appendix header:

3. References don't get the necessary hanging indent:

4. Section and subsection numbers are supposed to have a . after them but don't. And strangely the gap seems a bit large between the number and the text:

5. 'Appendix' gets printed before the appendices once:

[PaulRegular]

I can confirm that the References Cited is easily fixed:

# REFERENCES CITED {-}

<div id="refs" custom-style = "citation"></div>

This should solve issue 1. and 3. I contemplated adding this to the template, but I wasn't sure whether this will break the pdf side.

I've opted to build documents without section numbers, so I've yet to explore heading customizations. I suspect item 4. will be easier to fix than item 2. For item 2., creating a new section should reset the numbering, but the prefix may need to be manually added after the doc is rendered.

[seananderson]

For item 4 (section number formatting), it looks like the issue is that the reference .docx has both "Heading 1" etc. and "Heading 1 with number" etc. Apparently we could replace the styles like this:

library(officer)

# Path to your rendered docx from officedown
input_file  <- "my_report.docx"
output_file <- "my_report_with_numbered_heading1.docx"

# Read the docx
doc <- read_docx(input_file)

# Extract all paragraphs with their styles
content <- docx_summary(doc)

# Find paragraphs that have style exactly "Heading 1"
heading1_ids <- content$doc_index[content$style_name == "Heading 1"]

# Loop through each matching paragraph index
for (id in heading1_ids) {
  doc <- body_replace(doc,
                      old_value = fixed(content$text[id]),
                      new_value = fpar(ftext(content$text[id],
                                             prop = fp_text()),
                                       style = "Heading 1 with number"),
                      only_at_cursor = FALSE)
}

# Save the modified document
print(doc, target = output_file)

ChatGPT also suggested an approach working directly with the xml with xml2.

I think a similar (but slightly more complicated) approach would work with the appendices and may fix the number/letter issues there. More complicated because we'd have to replace the headers after the first appendix with a different style ("Appendix H1" etc.).

Also, in the reference block, all "Normal" needs to be changed to "citation" style and that will fix the indenting.

I'm also wondering if we're reaching a point at which a csasdown2 might be warranted that (1) has no illusions of maintaining backwards compatibility with the LaTeX templates while not breaking existing workflows,(2) is much leaner because it would drop all the TeX processing functions and package dependencies, and (3) has a more well thought out set of YAML arguments given everything we've learned over the years.

[seananderson]

Adding to this:

• All lists get left as "Compact" but should be either "List Bullet" or "List Number" (how we figure out which is another good question)

Edit: Slightly inelegant, but this should work and may be safer than us trying to grep these out somehow:

::: {custom-style="List Bullet"}
- Item one
- Item two
- Item three
:::

::: {custom-style="List Number"}
1. First
2. Second
3. Third
:::

• Table Caption -> Caption Table

Edit: this is easily fixable with in the existing officedown call. Oh, see the comment about davidgohel/officedown#112

[seananderson]

• Applying "Appendix H1" style to "TEST" automatically makes the formatting correct as "APPENDIX A. TEST".

Whether cross references will update and work is another matter.

This might be easiest as:

::: {custom-style="Appendix H1"}
MY FIRST APPENDIX
:::

To avoid us having to guess at these.

Overall, the problem is that pandoc strips out all unused styles. One solution is to use hidden text to use all styles we need at least once. This also looks like a solution using officer to bring over all styles:

library(officer)

# Your full template with all styles
ref_docx <- "full_styles_reference.docx"

# The report content you just generated
content_docx <- "content.docx"

# Read both
doc <- read_docx(ref_docx)         # Start from the full-style template
content <- read_docx(content_docx) # The generated report

# Append content into the template
doc <- body_add_docx(doc, content)

# Save the final report
print(doc, target = "final_report.docx")

[PaulRegular]

I like the idea of replacing the styles to impose the numbering and using the right style. This functionality could be triggered through the number_sections yaml argument...however, I'm not sure how to deal with uses of {-} to suppress the numbering of specific sections.

For item 4 (section number formatting), it looks like the issue is that the reference .docx has both "Heading 1" etc. and "Heading 1 with number" etc. Apparently we could replace the styles like this:
...

[PaulRegular]

This is a viable way forward too, but my understanding is that custom styles cannot be used in a CSAS doc :/

• Applying "Appendix H1" style to "TEST" automatically makes the formatting correct as "APPENDIX A. TEST".

...

[seananderson]

This is a viable way forward too, but my understanding is that custom styles cannot be used in a CSAS doc :/
Applying "Appendix H1" style to "TEST" automatically makes the formatting correct as "APPENDIX A. TEST".

My point was that "Appendix H1" is the official CSAS .docx style that we need to apply.

I assume regarding numbering, we'll want to always suppress the RMarkdown numbering functionality and then toggle which set of styles get applied. What I don't know is how any cross referencing would work. If we have to, we could probably live without that. Sections are probably rarely cross referenced. Appendices are referenced more, but hopefully they are more static in their lettering.

[PaulRegular]

My point was that "Appendix H1" is the official CSAS .docx style that we need to apply.

I assume regarding numbering, we'll want to always suppress the RMarkdown numbering functionality and then toggle which set of styles get applied. What I don't know is how any cross referencing would work. If we have to, we could probably live without that. Sections are probably rarely cross referenced. Appendices are referenced more, but hopefully they are more static in their lettering.

Doh! Of course. I overlooked that style.

And I agree, we could live without the cross-referencing of numbered sections if we have to.

[seananderson]

I'm happy to report that I think I've fixed everything listed here over in csasdown2. Appendices are even working:

    # APPENDIX B. ADDITIONAL ANALYSES

    ```{r setup-appendix-b}
    # Reset numbering for Appendix B (B.1, B.2, etc.)
    set_appendix("B")
    appendix_fig_opts()
    appendix_tab_opts()
    ```

[seananderson]

Even simpler now:

# APPENDIX `r new_appendix()`. BIOLOGICAL DATA

This appendix demonstrates appendix-specific figure and table numbering (A.1, A.2, etc.).

[seananderson]

@PaulRegular one thing that's driving me nuts is the alignment of tables. From your notes, it sounds like there are specific configurations of flextable that are CSAS compatible. In the current configuration over in csasdown2, the tables are always left aligned. I think this may be due to the funny tab alignment/margin setup for the table in the template .docx:

They end up like this.

1. Should they be centred for res docs? That's how I've always seen them (with left-aligned captions).
2. Is theme_fun = "theme_booktabs" going to cause grief with CSAS?
3. If we want them centred, how on earth do we do this? By default flextables are centred, but there's something here in our template making them left aligned no matter what I do with the settings.

For all of this, see the csasdown2 repo, not this main repo.

[seananderson]

@PaulRegular Equations are currently referenced as follows:

I can fix this (I think), but it will be much more complicated than the figures and tables were (I think). In your experience, were the parentheses OK or did you have some solution? My first proposed solution involves officer::body_replace_all_text(). https://xkcd.com/208/

[PaulRegular]

Re. table alignment, I've been supplying left aligned tables and have yet to be told they should be centered...but just looked and learned that CSAS centered all the tables before publication. It should be an easy fix of changing ft.align to "center" in opts_chunk$set().

On the equations, I see that CSAS has been doing some post-processing there too. When inline - e.g., "...bla bla Equation (1) bla bla bla..." - they keep the brackets; but, when in parentheses they change this "(see Equation (1))" to this "(see Equation 1)". This spurred me to do a little (belated) reading on conventions, and it looks like most math journals require equations to be referenced in parentheses. I didn't find any guidance on how to reference figures in parentheses (this exchange was the closest), but impression is that I should have been using brackets "[see Equation (1)]" or a comma "..., see Equation (1)" to retain the parentheses around the equation number. In short, I'm not sure this is something that needs to be programmatically fixed since it may be a matter of applying the right writing convention.

[seananderson]

Ha. I tried everything under the sun yesterday. Then, after your comment, I realized the ft.align was being overwritten in that opts_chunk$set() in skeleton.Rmd with ft.align = "left", so no matter what I did to the global options in base$knitr$opts_chunk or to the template .docx, nothing was happening. I've now moved more of the options that should always be the same into the base$knitr$opts_chunk settings.