search

wshito / asciidoctor-chunker

The utility to create chunked HTML files from the single HTML generated by Asciidoctor.
MIT License
25 stars 7 forks source link

unresolved internal xrefs turn into 'undefined' xrefs, which is a behavior change #22

Closed oddhack closed 2 years ago

oddhack commented 3 years ago

When the input HTML generated by asciidoctor contains an xref to a (potentially) undefined anchor, notionally '\<\>', asciidoctor will still generate HTML containing an href to that anchor (although it will possibly surround the anchor text with square brackets, and will report it if run with -v).

When the chunker encounters this scenario, it replaces the 'href="#badanchor"' with 'href="undefined"'. This is a behavior change in the HTML. In the original, clicking on the anchor just won't do anything, in the chunked version it takes you to what is almost certainly a nonexistent page 'undefined'. We ran into this when running a link checker over our chunked docs and, while obviously we should fix the bad xrefs, the behavior change is undesirable from a user XP point of view (they might be annoyed by the link going nowhere before, now they at least have to hit the browser 'back' button to return to what they were looking at).

The best fix would be to just retain the bad anchor in the output, which leaves behavior unchanged in the chunked document compared to the original HTML.

This is trivial to reproduce in any chunked output, so I won't provide an example - just add '\<\>' somewhere in the asciidoc source.

wshito commented 2 years ago

@oddhack Sorry for the delay. I was so busy that I totally forgot to reply. Yes, I will fix this as you requested to conform the original behavior.

wshito commented 2 years ago

@oddhack Sorry for taking for so long. I have fixed the undefined link. Please pull the repository and test with the dist/asciidoctor-chunker.js script.

The chunker now adds target-missing class attribute to the anchor element when the target is missing. You can put an icon on the missing links to call the attention.

oddhack commented 2 years ago

@wshito sorry, I overlooked this and just got around to testing with dist/asciidoctor-chunker.js from master branch. Unfortunately, it's running into this error very early in the process:


node /home/tree/git/vulkan/scripts/asciidoctor-chunker/asciidoctor-chunker.js /home/tree/git/vulkan/gen/out/html/prechunked.html -o /home/tree/git/vulkan/gen/out/html
/home/tree/git/vulkan/scripts/asciidoctor-chunker/asciidoctor-chunker.js:7
<!DOCTYPE html>
^

SyntaxError: Unexpected token '<'
    at wrapSafe (internal/modules/cjs/loader.js:915:16)
    at Module._compile (internal/modules/cjs/loader.js:963:27)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1027:10)
    at Module.load (internal/modules/cjs/loader.js:863:32)
    at Function.Module._load (internal/modules/cjs/loader.js:708:14)
    at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:60:12)
    at internal/main/run_main_module.js:17:47
make: *** [Makefile:293: chunked] Error 1

If it is relevant, using node v12.22.10.

wshito commented 2 years ago

@oddhack Why does the output file has the suffix js? Or maybe I am missing your input since it looks truncated in the post above.

node /home/tree/git/vulkan/scripts/asciidoctor-chunker/asciidoctor-chunker.js /home/tree/git/vulkan/gen/out/html/prechunked.html -o /home/tree/git/vulkan/gen/out/html /home/tree/git/vulkan/scripts/asciidoctor-chunker/asciidoctor-chunker.js:7

If it is relevant, using node v12.22.10.

v12 is quite old now. The asciidoctor-chunker is tested only with higher than v14. It's a good idea to upgrade to the LTS version 16.

oddhack commented 2 years ago

@oddhack Why does the output file has the suffix js?

Actually what I did was to download the chunker JS from the wrong github page, and I had a ".js" file with Github HTML in it instead :-( With that corrected, this works perfectly and as desired when run with the actual .js - sorry for my mistake!