Make MANUAL's TOC collapsable

[Mauro Bieg]

I was just thinking about how to split the MANUAL.html into several smaller pages without breaking the links with hashes.

I've an attempt to a solution: use JavaScript to only show the relevant section. For this to work, we need pandoc --section-divs MANUAL.html, then inject the following js at the bottom of the file (maybe put it in collapseTOC.js and rename that file):

(function(){
var defaultSection = 'description';
var sections = jQuery('main > div > section');
var sectionIdents = [];
var toSection = {}; // map from every hash in document to section
var tocItems = jQuery('#toc > ul > li');

sections.each(function(i, el) {
  var sectionIdent = el.getAttribute('id');
  sectionIdents.push(sectionIdent);
  toSection[sectionIdent] = sectionIdent;
  $(el).find('[id]').each(function(i, child) {
    toSection[child.getAttribute('id')] = sectionIdent;
  });
});

sections.each(function(i, el) {
  if (sectionIdents[i-1]) {
    $(el).append('<a href="#' + sectionIdents[i-1] + '">Previous Section</a>');
  }
  if (sectionIdents[i+1]) {
    $(el).append('<a href="#' + sectionIdents[i+1] + '">Next Section</a>');
  }
});

function showOnlyCurrentSection() {
  var targetSection = toSection[location.hash.substr(1)] || defaultSection;
  sections.each(function(i, el) {
    if (el.getAttribute('id') === targetSection) {
      el.style.display = 'block';
    } else {
      el.style.display = 'none';
    }
  });
  tocItems.each(function(i, el) {
    var children = el.children;
    var subSections = children[1];
    if (subSections) {
      if (children[0].getAttribute('href').substr(1) === targetSection) {
        subSections.style.display = 'block';
      } else {
        subSections.style.display = 'none';
      }
    }
  });
}
window.addEventListener('hashchange', showOnlyCurrentSection, false);
showOnlyCurrentSection();
})();

TODO:

• styling of the next/previous buttons
• make better sections (roll the synopsis into description, group the Producing slide shows with pandoc, EPUB and Jupiter into one?)

[John MacFarlane]

What's the motivation for this?

[Mauro Bieg]

This might be subjective, but to me it feels like the MANUAL is getting too long to comfortably fit into a single page for someone who reads it the first time. Especially the table of contents is overwhelming: you have to scroll down more than a screen's height to even find the link to "Pandoc’s Markdown", which is probably one of the more important sections to people new to pandoc.

I've attached a rough demo: MANUAL.html.zip

[John MacFarlane]

Personally I always prefer to have it all in one page, because then you can search for stuff easily.
If the issue is with the TOC, perhaps we could add some javascript to make the levels collapsible, so initially it only shows the top-level divisions?

[Mauro Bieg]

Finally got around to making a pull. What do you think?

We should probably also make better sections:

• roll the synopsis into description. Possibly rename that to "Usage" or something?
• group the "Producing slide shows with pandoc", "Creating EPUBs with pandoc" and "Creating Jupyter notebooks with pandoc" into a common section

[John MacFarlane]

Lovely!

roll the synopsis into description and rename as Usage

We generate the man page from the same source, and it's traditional in man pages to start with Synopsis and Description sections. So I'd be inclined to keep this.

group the "Producing slide shows with pandoc", "Creating EPUBs with pandoc" and "Creating Jupyter notebooks with pandoc" into a common section

Open to suggestions about how to do this.

[John MacFarlane]

By the way: you use jquery here; did you look into whether bootstrap has a built-in way of doing this? Do we use jquery anywhere else in the site?

[Mauro Bieg]

Thanks!

Ah, I assumed we use jQuery in other places as well, since we have it... but I don't know. But nowadays it would certainly be possible to get rid of it... gonna submit a pull using querySelectorAll which is supported in IE>=8.

[Mauro Bieg]

Not sure what we're actually using the bootstrap js for (which requires jQuery), probably only to make the main navigation collapsable (sidebar-nav)? We could do that with the same approach now and get rid of both the JavaScript parts of Bootstrap and by extension jQuery...

[Mauro Bieg]

Open to suggestions about how to do this.

Maybe:

• ...
• Pandoc’s Markdown
• Other formats
  • Slide shows
  • EPUBs
  • Jupyter notebooks

Or "Some other format", "Notes about other formats", or "Other output formats" (but at some point we might want to add a section about some input format like org-mode...), ...? Maybe someone on pandoc-discuss has a better idea...

[Mauro Bieg]

it's traditional in man pages to start with Synopsis and Description sections. So I'd be inclined to keep this.

Yeah, that makes sense. It's just that the "Using pandoc" subsection is somewhat buried.