Pagedown: [Suggestion] Optional List of Abbreviations/ Symbols

[brentthorne]

Hello!

As I am working on a thesis template I noticed there is no option to add a "list of symbols" or abbreviations. I am slowly learning how it works but I figured I would throw the suggestion out to you guys in hopes that maybe you can implement it sooner and better than I could.

Thanks again

[RLesur]

Great question, thanks!
AFAIK, the Pandoc document model does not support abbreviations (see also here).

One solution would be to give a try to the HTML5 abbr element.
Here is a quick and dirty example with pagedown::html_paged

---
output: pagedown::html_paged
---

```{js, echo=FALSE}
Paged.registerHandlers(class extends Paged.Handler {
  constructor(chunker, polisher, caller) {
    super(chunker, polisher, caller);
  }
  beforeParsed(content) {
    const abbreviations = content.querySelectorAll('abbr');
    if(!abbreviations) return;
    let listOfAbbreviations = document.createElement('div');
    let descriptionList = document.createElement('dl');
    content.appendChild(listOfAbbreviations);
    listOfAbbreviations.id = 'list-of-abbreviations';
    listOfAbbreviations.classList.add('section', 'level1');
    listOfAbbreviations.innerHTML = '<h1>List of Abbreviations</h1>';
    listOfAbbreviations.appendChild(descriptionList);
    for(let abbr of abbreviations) {
      if(!abbr.title) continue;
      let term = document.createElement('dt');
      let definition = document.createElement('dd');
      descriptionList.appendChild(term);
      descriptionList.appendChild(definition);
      term.innerHTML = abbr.innerHTML;
      definition.innerText = abbr.title;
    }
  }
});
```

# A section with abbreviations

Pagedown uses <abbr title="HyperText Markup Language">HTML</abbr>, <abbr title="Cascading Style Sheets">CSS</abbr> and <abbr title="JavaScript">JS</abbr> to paginate documents.

However, abbreviations support is quite a generic need and I think a solution closer to Pandoc would be a better choice.
For instance, the Pandoc Wiki references this Pandoc python filter: https://github.com/scokobro/pandoc-abbreviations
It could be written in lua to be natively used with Pandoc 2.

IMO, this recent proposal in the related issue in Pandoc is extremely interesting.

[brentthorne]

So I tried using the js you wrote and it is great! My only issue is that it places the list of abbr at the end of the document. Is there a way for it to be added the same way that the lof or or lot to the toc?

Thanks again for the help, the thesis template is getting close to be pull request ready!

Cheers

[RLesur]

Of course!
There is a dedicated div in html_paged here: https://github.com/rstudio/pagedown/blob/712540ad9f883d078cf19752b806a70cacd1f66c/inst/resources/html/paged.html#L175

You need to replace this line of the hook:

 content.appendChild(listOfAbbreviations);

with

content.querySelector('.front-matter-container').appendChild(listOfAbbreviations);

[brentthorne]

Works great!

[brentthorne]

So in implementing the js hook for abbreviations I have run into a problem, the 'list of abbreviations' page always appears even when there are no abbreviations in the document. The TOC also does not find/ include the loa page but does include lof and lot. Any suggestions? The latest progress has been pushed to my fork here.

[RLesur]

Sorry for the first point, this is a bug in my _quick and dirty_ proposal.
The following line is wrong:

if(!abbreviations) return;

and must be replaced with:

if(abbreviations.length === 0) return;

For the TOC, you are right: the TOC is generated by pandoc and the hook should also update the TOC. This is feasible: you have to create and insert a new li element in the ul element of the TOC.
Tip to find where to insert this li element: all the anchors referring to front matter entries are of class front-matter-ref.

[brentthorne]

So far I've had little luck getting this to work. I've tried adding the front-matter and front-mater-ref class to the <h1> tag on the abbreviations page but have not been successful. I also tried to ad the li to th ul using js but again I will need to take more time to figure it out.

From what I've gathered so far in the config.js file there is code to take the ref data of all <h1> tags inside of the <div> with class .front-matter-container but it does not do it for the abbreviations <h1> tag.

I think it has something to do with the lack of ref-data= generated for the abbreviations <h1> tag but I'm not exactly sure.

Thanks again!

[RLesur]

I understand well the point.
It is important to have in mind the different steps of html_paged:

1. The PagedConfig.before async function runs first. The input is the HTML document generated by Pandoc. In pagedown, this step ensures that MathJax runs before Paged.js. The document is also slightly modified (note that these tasks could be done in a beforeParsed hook, this would lead to the same result). After this step, the document does not contain the list of abbreviations.
2. Paged.js runs. Paged.js analyses the CSS declarations, splits the document into pages (this is the chunker), remove the DOM... Paged.js also executes the hooks. Here, the internal representation of the document (which will be attached as a shadow DOM) contains the list of abbreviations. The TOC entry for the list of abbreviations should be added here.
3. Paged.js attaches the shadow DOM: the new DOM is then built. The ref-data attributes are added to the elements: these attributes are internal to Paged.js and link the DOM elements with their corresponding elements in the shadow DOM.

In order to collaborate on the thesis output format and if you do not mind, you could open a pull request (or a draft pull request if you prefer). Therefore, it would be easier for me to help you on specific part of the code.

[RLesur]

@brentthorne Thanks for https://github.com/rstudio/pagedown/pull/107! I will work on the list of abbreviations feature by pushing on your fork (maybe this week).

[RLesur]

In order to ease the implementation of this feature, I've updated pagedown through https://github.com/rstudio/pagedown/commit/c44ddd6d8efba992dedabd8616e318356ecbd99b and https://github.com/rstudio/pagedown/commit/53f29bd3889637c2bc635e917d6a6c4e275fe955

I also pushed a modified version of the hook in #107, see https://github.com/rstudio/pagedown/pull/107/commits/ca86bf53b19de49268772a0efde313e10d4ab30c

[brentthorne]

Looks great, thanks @RLesur ! Is there anything else needed on my end for the pull request to go through?

I do plan to make the skeleton.Rmd a little more robust with examples of the features one may want in a thesis document.

[RLesur]

@brentthorne I will review #107 and let you know my suggestions if any.