Overall aim: I'd like to change the style of crossreferences to an anchor in the glossary, to get something like this (glossary links are more discreet than other links). I'd prefer not to change the <<word>> syntax, so document authors don't need to learn another syntax and can still use other tools (without my extension) to preview the document.
Using a TreeProcessor seemed the best way to find the glossary links -- they should be descendants of the block with the id "glossary". document.blocks.each do |block| if block.id == "glossary" then buildGlossary block end end How, though, am I supposed to change the actual text content? Even retrieving the text seems complicated. I came up with removing the substitutions, reading .text (maybe replacing it) and restoring the substitutions: if defined? block.text then s = [] s.replace(block.subs) s.map{|ss| block.remove_sub(ss)} text = block.text block.text = changeGlossaryRefs(block.text) s.map{|ss| block.subs.append(ss)} end Is there a better approach? The rough work is here: https://github.com/gbif/gbif-asciidoctor-toolkit/blob/glossary-references/gbif-extensions/lib/glossary.rb#L24 |
I got interested in glossaries yesterday…
I’m struggling to understand what you are doing now and what you want to be different. Could you show the asciidoc for everything involved in the simplest possible example and indicate how you want the generated html to be different from how it is? Thanks! David Jencks
|
I now have it working on a test document, example here including the source: http://mb.gbif.org/tmp/2020/07/asciidoctor-glossary.html
There is a role "glossary" on the crossreferences which point to items in the glossary, and the links are styled with a dotted underline instead of in blue. My concern is this seemed more complicated than I expected -- traversing the document with a TreeProcessor is fine, but making changes to the text required disabling substitutions before calling the text method. I expected the tree to include inline elements like crossreferences or macros, but instead I'm just using a regular expression to find the <<crossreferences>> and change them to xref:crossreferences[role=glossary]. |
Thanks for the example.
Asciidoctor parsing is conducted in more or less two phases: the “parser” identifies block content and creates the nodes for them, and the converter (e.g. html5) parses the content and identifies inline “blocks” such as links. A tree processor runs after the parser and before the converter, so inline nodes have not yet been recognized. This causes numerous problems but requires rewriting (at least) most of the parser to fix. It looks to me as if blocks allow direct access to the source through lines (as you do) but that listItems insist on substitutions, thus requiring your workaround. This seems pretty unfortunate to me.
|
I don't have much experience with Ruby, but I discovered it supports open classes, which is a neater way to get the source from blocks that don't have a suitable method already.
The resulting extension is now merged in to my repository here: https://github.com/gbif/gbif-asciidoctor-toolkit/blob/master/gbif-extensions/lib/glossary.rb And the (currently in draft) largest document this is intended for is here: https://docs.gbif-uat.org/georeferencing-best-practices/1.0/en/#introduction |
Free forum by Nabble | Edit this page |