Create static ToC for Html output

[opoudjis]

No description provided.

[opoudjis]

A static ToC means we give up on the smoothScrooling functionality, of synchronising the scrolling of the ToC and the content window. If you can run the Javascript to do smoothScrooling, you can also run the Javascript the generate the table of contents dynamically.

Because I will not code Javascript, if that's a problem, I'm not going to be the one to solve it.

[ronaldtse]

I think it's fine to first create the static ToC , and have someone else code up the smooth scrolling. @strogonoff could you help here?

[opoudjis]

That's not the only Javascript you may need to deal with, if you want to use crippled obsolete junk versions of browsers like Internet Explorer 11. There's also the scroll to the top HTML button, and the rendering of footnotes inline. See https://github.com/riboseinc/metanorma-iso/blob/master/lib/isodoc/iso/html/scripts.html

[ronaldtse]

Point remains that our HTML output needs to degrade gracefully. I believe @strogonoff could handle this.

[opoudjis]

I've generated the static ToC, but this needs the Javascript from the existing ToC script to be cannibalised, in order for it to deliver the same functionality. I will release the gems without the static ToC, and I am attaching a version with the static ToC content here, for Anton or Pierre to work on. I am also attaching a version with the dynamic ToC script, for comparison.

rice.html.dynamic.zip
rice.static.html.zip

The table of contents script is at https://cdn.rawgit.com/jgallen23/toc/0.3.2/dist/toc.min.js

The table of contents script is invoked as:

      $('#toc').toc({
          'selectors': 'h1,h2:not(.TermNum)', //elements to use as headings
          'container': 'main', //element to find all selectors in
          'smoothScrolling': true, //enable or disable smooth scrolling on click
          'prefix': 'toc', //prefix for anchor tags and class names
          'onHighlight': function(el) {}, //called when a new section is highlighted 
          'highlightOnScroll': true, //add class to heading that is currently in focus
          'highlightOffset': 100, //offset to trigger the next headline
          'anchorName': function(i, heading, prefix) { //custom function for anchor name
              return prefix+i;
          },
          'headerText': function(i, heading, $heading) { //custom function building the header-item text
              return $heading.text();
          },
      'itemClass': function(i, heading, $heading, prefix) { // custom function for item class
        return $heading[0].tagName.toLowerCase();
      }
      });

The functionality of "selectors", "container", "prefix", "headerText", "itemClass" has already been reproduced in the static code, and does not need to be replicated.

There are two pieces of functionality missing from the static version, and the ToC script needs to be cannibalised to replicate that functionality:

1. mouseover does highlight items, but it is not sticky: on click, the class "toc-active" ("activeClass" within the script) needs to be added to the clicked list item.
2. the functionality of smoothScrolling, which automatically scrolls the sidebar when the main window is scrolled, needs to be replicated.

[opoudjis]

I'm asking that any Javascript be included in the HTML file; I will add it back into the gem when done.

[strogonoff]

@opoudjis are you asking me to send you patched HTML, and you’ll diff & commit the changes later?

[opoudjis]

Yes.

[opoudjis]

@strogonoff Any progress on this? I am way overcommitted on other projects, but this does still need to be done.

[opoudjis]

@strogonoff Re-ping.

[opoudjis]

@strogonoff Please action. The task is to extract from the existing JS we use a smaller subset, which will just do mouseover highlighting and smooth scrolling; the remaining ToC functionality will be moving into statically generated code.

[strogonoff]

@strogonoff Please action. The task is to extract from the existing JS we use a smaller subset, which will just do mouseover highlighting and smooth scrolling; the remaining ToC functionality will be moving into statically generated code.

Sure, this slipped through the cracks, let me put some resources on it

[strogonoff]

As I’m looking into it, I don’t believe it’s worth mucking around with the jQuery plugin, since generating ToC from headers is its core feature. May be more straightforward to just generate ToC HTML and have a simple script to handle some UX niceties.

@opoudjis, you wrote

I've generated the static ToC

Is this in a branch? How can I generate the sample document with the static ToC? So that I can play around with the JS side of things on it

[opoudjis]

@opoudjis, you wrote

I've generated the static ToC
Is this in a branch? How can I generate the sample document with the static ToC? So that I can play around with the JS side of things on it

It's commented out code in isodoc:

isodoc/lib/isodoc/html_function/html.rb

    def html_toc(docxml)
=begin
      idx = docxml.at("//div[@id = 'toc']") or return docxml
      toc = "<ul>"
      tocidx = 0
      docxml.xpath("//main//h1 | //main//h2[not(@class = 'TermNum')]").each do |h|
        h["id"] ||= "toc#{tocidx}"
        toc += html_toc_entry(h.name == "h1" ? 1 : 2, h)
        tocidx += 1
      end
      idx.children = "#{toc}</ul>"
=end
      docxml
    end

Note that the XPath selector which headings to include in the ToC is now being handled by this supplied piece of Javascript, generated dynamically by Ruby:

    def toclevel
      <<~HEAD.freeze
    function toclevel() { var i; var text = "";
      for(i = 1; i <= #{@htmlToClevels}; i++) {
        if (i > 1) { text += ","; } text += "h" + i + ":not(:empty):not(.TermNum)"; } 
      return text;}
      HEAD
    end

That is in effect a dynamic version of "//main//h1 | //main//h2[not(@class = 'TermNum')]" above, which now excludes empty header bodies as well as TermNum.

I think you and Ronald need to discuss the point in generating Static ToC for HTML at all, given that Ronald now is talking about bundling jQuery with the HTML code in metanorma/metanorma#59

This is a ticket that has not been actioned in a year, but it is pointless to action it if the distribution strategy for HTML output is going to change so radically.

Which I myself think is insane, but that's now a discussion between @ronaldtse and you, @strogonoff. @ronaldtse, be clear on what you are trying to achieve here, because I think metanorma/metanorma#59 (if you're going to implement this) renders this ticket obsolete.

[strogonoff]

I think you and Ronald need to discuss the point in generating Static ToC for HTML at all, given that Ronald now is talking about bundling jQuery with the HTML code in metanorma/metanorma#59

After a quick exchange with Ronald, I’ll get static ToC done. jQuery may still need to be bundled, even if new ToC doesn’t use it other parts would.

[strogonoff]

@opoudjis I may be missing something, but the document works with static ToC as is.

Meaning:

— With code commented and JS disabled, ToC doesn’t work (as expected)
— With code uncommented and JS disabled, ToC works (except for highlighting current item, also as expected)
— With code uncommented and JS enabled, ToC behavior is identical

Could you clarify why the script may need to be modified?

[strogonoff]

Tested on isodoc-rice & Safari. Is there a browser-specific issue where the static ToC breaks because of that jQuery plugin?

[strogonoff]

@opoudjis To be more precise:

mouseover does highlight items, but it is not sticky: on click, the class "toc-active" ("activeClass" within the script) needs to be added to the clicked list item.

This works for me the same with or without static ToC. (Obviously not with JS disabled.)

the functionality of smoothScrolling, which automatically scrolls the sidebar when the main window is scrolled, needs to be replicated.

This does not work for me, again with or without static ToC. (Maybe I misunderstand how it’s supposed to work, I just don’t see any difference in behavior when scrolling. Sidebar scroll position is never affected by main window scroll in my tests.)

[opoudjis]

Huh. These are indeed broken. Ok, I'll regenerate, hold on.

[opoudjis]

OK, sorry. This is what's meant to happen:

• The version of the HTML I sent you was the one without highlighting of the current ToC item. Use the attached instead.
• The expected smoothscrolling behaviour in the given script is an animation of scrolling, not synchronised scrolling, so you can ignore it. I am convinced that I have seen synchronised scrolling in the past, but I can't replicate it now.

The missing activeClass functionality is:

j = function(b, c) {
                /* ... */
                a("li", d).removeClass(i), a(b.target).parent().addClass(i)
            },

so basically, function("onclick", e.addClass("toc-active")). Or however it is meant to work.

Rather than play middleman about dodgy functionality in a 10 year old ToC script, I invite @ronaldtse to communicate to you direct. You now have a dynamic and a static version of the ToC page attached here. Ronald, you tell Anton what you see missing (apart from the on-click class functionality.)

rice_alt.html.dynamic.zip
rice_alt.html.static.zip

That may include implementing simultaneous scrolling... Oh, I see: this was never implemented in the source ToC script, this was something Ronald asked for. metanorma/metanorma-iso#190. So Anton, you may or may not choose to take that ticket on too, as part of this work. But this is between you two now.

[opoudjis]

So the original scope of the ticket is now minimal: it's merely giving me a one line javascript command to change css class on click.

But the potential scope of this ticket is a lot bigger: implement whatever @ronaldtse would like to make the HTML ToC pretty, including simultaneous scrolling.

When you've worked out what the JS should be, let me know, and I will add it to the isodoc template.

[strogonoff]

Nick, the highlight of the active item in sidebar works for me with the uncommented version & ToC fully static, with existing JS. I’ll attach a screencast.

…

On 30 Jul 2019, at 10:26 AM, Nick Nicholas ***@***.***> wrote: So the original scope of the ticket is now minimal: it's merely giving me a one line javascript command to change css class on click. But the potential scope of this ticket is a lot bigger: implement whatever @ronaldtse would like to make the HTML ToC pretty, including simultaneous scrolling. When you've worked out what the JS should be, let me know, and I will add it to the isodoc template. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[strogonoff]

@opoudjis Here’s what I see. Tab on the left is the original (without static ToC), tab on the right the version with uncommented code you pointed to (with static ToC).

This is isodoc-rice built using the documented method. I uncommented your code in the isodoc gem, and verified that ToC appears in HTML after that. No JS modifications made so far.

Active item highlight works on both. Scrolling sync does not work on either.

[opoudjis]

Scrolling sync indeed does not exist anywhere, it was a feature request by Ronald.

You are looking at the .html file in the screenshot. Look at the .alt.html file, which highlights the clicked on TOC item by adding a CSS class to it. The static version can't be doing it, because I've commented out the TOC script that does that.

[strogonoff]

@opoudjis I am not looking at your attachments, I am looking at the document I built myself as described here. I built it two times, one with uncommented code in the gem. I don’t see any difference in ToC behavior.

[opoudjis]

Uncommenting the isodoc code is not sufficient. The point of uncommenting the isodoc code is that we should no longer need to call the ToC script, as is done e.g. in the first script in, metanorma-iso/lib/isodoc/iso/html/scripts.html, $('#toc').toc({.....})

If you do not remove the ToC script call from the HTML file, then the ToC script still ends up being run, and building the ToC dynamically. Which means there is no point in generating the ToC statically. That script also highlights clicked ToC entries, by assigning a CSS class to it.

If you do remove the ToC script call from the HTML file, then there is nothing to highlight the clicked on ToC entry. I don't need help doing that, that is a one-line JS function.

However, your task is to liaise with Ronald, work out if anything else needs to accompany the ToC as a javascript script (especially his request for synchronised scrolling), and give me whatever is needed as a new javascript script, which does not construct the ToC dynamically, but which does do whatever other rendering control is needed.

[strogonoff]

If you do not remove the ToC script call from the HTML file, then the ToC script still ends up being run, and building the ToC dynamically. Which means there is no point in generating the ToC statically. That script also highlights clicked ToC entries, by assigning a CSS class to it.

I disagree:

1. The point of having static ToC is to make the document degrade gracefully in case of absent or restricted JS environment.
2. The point of having dynamic ToC is to retain the dynamic ToC functionality where JS environment allows.
3. Leaving both on is the quickest way to resolve the actual problem the customer is facing, causing no difference in behavior perceptible by the customer.

A proper longer-term solution can follow this. However, I believe we should address the problem ASAP and then refactor if we want to. (If ToC was broken in presence of new static ToC, then this would be necessary right away, but it looks like it’s not.)

[strogonoff]

I think we agree on principle, I just suggest that we uncomment the static ToC as soon as customer confirms it solves their problem (dynamic ToC doesn’t break static ToC from my tests), and later refactor & improve on that (filed #113 for that)

[opoudjis]

Agree with you, I've discussed this independently with Ronald. So, I am now going to uncomment the isodoc code, and make sure it responds to gem-specific settings of permitted ToC styles.

[strogonoff]

It looks like html_toc function in this isodoc repo doesn’t affect metanorma-ogc deliverables. I believe the primary complaint was from the OGC guys. I’m not sure whether we should reopen this or create another one in OGC

[opoudjis]

No, under this ticket, I need to remove all overriding html_toc function from gems, I hadn't realised they had been there (effectively disabling static HTML TOC).