How to add a visible table of contents (HTML) to Pandoc?

pt
ptmkenny
Posts: 22
Joined: Fri May 04, 2018 8:43 am
Platform: Mac + Windows

Thu May 17, 2018 5:00 pm Post

I'm trying to compile to Pandoc and I don't see my table of contents.

Compile for: Pandoc -> ePub
On "Table of Contents" tab: Generate HTML table of contents is checked

The generated ePub has a working table of contents menu (nav.xhtml), but it's not included in the "spine" in content.opf:

Code: Select all

  <spine toc="ncx">
    <itemref idref="cover_xhtml"/>
    <itemref idref="title_page_xhtml" linear="yes"/>
    <itemref idref="ch001_xhtml"/>
    <itemref idref="ch002_xhtml"/>
    <itemref idref="ch003_xhtml"/>
    <itemref idref="ch004_xhtml"/>
    <itemref idref="ch005_xhtml"/>
    <itemref idref="ch006_xhtml"/>
    <itemref idref="ch007_xhtml"/>
    <itemref idref="ch008_xhtml"/>
    <itemref idref="ch009_xhtml"/>
    <itemref idref="ch010_xhtml"/>
    <itemref idref="ch011_xhtml"/>
    <itemref idref="ch012_xhtml"/>
    <itemref idref="ch013_xhtml"/>
  </spine>


If I add it to the "spine" it then shows up in the book properly:

Code: Select all

    <itemref idref="cover_xhtml"/>
    <itemref idref="nav" linear="yes"/>
    <itemref idref="ch001_xhtml"/>


In other compile formats, "Generate HTML table of contents" means "put an HTML table of contents in the book"-- does this mean something different with Pandoc, or is this a bug?

Also, I wanted to get more finely grained control over the Pandoc output (changing command-line compile settings). I tried editing the format with "Pandoc-> ePub" selected, but I couldn't find any way to change the command-line compile settings. When I set "Compile for" to "MultiMarkdown", however, a "Processing" tab appeared in the compile format settings. Is this the correct way to modify command line settings for Pandoc?

EDIT: To answer the second part of the question, yes, you need to use the MultiMarkdown compile option. See 24.22.1 in the manual.

User avatar
nontroppo
Posts: 964
Joined: Mon Mar 05, 2007 5:22 pm
Platform: Mac
Location: Airstrip One

Fri May 18, 2018 7:05 am Post

As you've found, the built-in Pandoc->X options are somewhat limited, and you can use Multimarkdown setting to compile to Pandoc and run Pandoc automatically with many other settings from the post-processing panel. This misnaming is quite confusing, and hopefully will be cleaned up to be more accurate in a future release (Pandoc support was added quite late in development AFAIK which is why it got bolted on to the MMD setting, a quick fix is just call MultiMarkdown as "Markdown", then specify MMD/Pandoc in the post-processing pane)...

As to the TOC problem, perhaps you can send a minimal example that demonstrates the problem?

User avatar
KB
Site Admin
Posts: 19667
Joined: Tue Jun 13, 2006 11:23 pm
Platform: Mac
Location: Truro, Cornwall
Contact:

Fri May 18, 2018 3:44 pm Post

Ian, I'm not sure what you mean by the misnaming. You asked for an option to use Pandoc syntax in the MMD post-processing pane, and I added it. It does mean that you can generate Pandoc from MultiMarkdown, but it would be confusing to rename it to both as it is primarily MultiMarkdown. There are no plans to change this or "clean it up".

PTMKenny: I'm looking into this. It looks as though the ToC pane was left in the Compile area for this format by mistake, when it currently does nothing. I'll add support for --toc and --toc-depth here.

All the best,
Keith
"You can't waltz in here, use my toaster, and start spouting universal truths without qualification."

User avatar
nontroppo
Posts: 964
Joined: Mon Mar 05, 2007 5:22 pm
Platform: Mac
Location: Airstrip One

Fri May 18, 2018 4:54 pm Post

Hi Keith, sorry if I was not clear. Pandoc and MMD are two separate (but highly compatible) equal variants of Markdown. Currently a user sees an option to use Multimarkdown, and it does not mention Pandoc.It is like having an option called DOCX but actually it can also output a Wordperfect file 8) In my mind, because they are both kinds [⊂] of Markdown, and all the options apply equally to both, then calling that compile section Markdown would be technically more accurate:
menu.png
menu.png (39.58 KiB) Viewed 250 times

I thought AmberV mentioned this recently and perhaps I read into his reply that this was not set in stone. Anyway this is all pretty minor, the important thing is Scrivener can do it even if it isn't entirely semantically correct!!! :D

User avatar
KB
Site Admin
Posts: 19667
Joined: Tue Jun 13, 2006 11:23 pm
Platform: Mac
Location: Truro, Cornwall
Contact:

Fri May 18, 2018 5:51 pm Post

I'll confer with Ioa, but in my off-the-top-of-my-head opinion, this would be misleading because a lot of what Scrivener does during export is MultiMarkdown-specific. For instance, footnotes are not part of the official Markdown spec, but are part of MultiMarkdown. The only time the "MultiMarkdown" option is ever not "semantically correct" is when "Use Pandoc syntax" is turned on in "Processing" in a particular Format - an option I am now regretting adding. :)
"You can't waltz in here, use my toaster, and start spouting universal truths without qualification."

pt
ptmkenny
Posts: 22
Joined: Fri May 04, 2018 8:43 am
Platform: Mac + Windows

Sat May 19, 2018 9:31 am Post

KB wrote:I'm looking into this. It looks as though the ToC pane was left in the Compile area for this format by mistake, when it currently does nothing. I'll add support for --toc and --toc-depth here.


Thanks Keith!

User avatar
nontroppo
Posts: 964
Joined: Mon Mar 05, 2007 5:22 pm
Platform: Mac
Location: Airstrip One

Sat May 19, 2018 3:18 pm Post

KB wrote:The only time the "MultiMarkdown" option is ever not "semantically correct" is when "Use Pandoc syntax" is turned on in "Processing" in a particular Format - an option I am now regretting adding. :)


I'm really sorry if I've offended you somehow; that was not my intention at all! This was the post where I thought AmberV sounded equivocal to me about the naming of that option: viewtopic.php?p=261566#p261566 — I really want to reiterate this is all quite minor semantics, no big deal. :shock:

User avatar
KB
Site Admin
Posts: 19667
Joined: Tue Jun 13, 2006 11:23 pm
Platform: Mac
Location: Truro, Cornwall
Contact:

Sat May 19, 2018 3:29 pm Post

nontroppo wrote:
KB wrote:The only time the "MultiMarkdown" option is ever not "semantically correct" is when "Use Pandoc syntax" is turned on in "Processing" in a particular Format - an option I am now regretting adding. :)


I'm really sorry if I've offended you somehow; that was not my intention at all! This was the post where I thought AmberV sounded equivocal to me about the naming of that option: http://literatureandlatte.com/forum/vie ... 66#p261566 — I really want to reiterate this is all quite minor semantics, no big deal. :shock:


Not at all - that was intended as a joke! Sorry it it came off the wrong way. I very much appreciate all of your feedback - I wouldn't have taken so much of it on board if I did not. I've asked Ioa for his thoughts on this when he gets back from his long weekend.
"You can't waltz in here, use my toaster, and start spouting universal truths without qualification."

User avatar
nontroppo
Posts: 964
Joined: Mon Mar 05, 2007 5:22 pm
Platform: Mac
Location: Airstrip One

Sun May 20, 2018 12:47 pm Post

I'll give my humour filter a dust and polish then :lol:

Online
User avatar
AmberV
Posts: 21449
Joined: Sun Jun 18, 2006 4:30 am
Platform: Mac + Linux
Location: Santiago de Compostela, Galiza
Contact:

Tue May 22, 2018 2:11 pm Post

Well as I noted in the referenced thread, I do agree it isn’t 100% accurate to call the bulk of Scrivener’s Markdown syntax generation as “MultiMarkdown”, because the bulk of what it generates is in fact valid to a number of dialects that support tables and footnotes. There are some extensions to this common bulk that are MMD specific, like how it marks cross-referencing labels in headings, and specifies image sizes—those are things that do need special treatment to make a Pandoc native document (opposed to one that requires using the markdown_mmd formatter).

But on the other hand, what is a good word for this collective pool of extended syntax that is now adopted by a wide variety of parsers? To my knowledge there isn’t a good word for that, or any collective attempt to create a central specification for these extensions that we could refer to. The closest thing is CommonMark, but that’s at the moment an attempt to clarify Gruber Markdown—the very core of what various parsers work from, so that they all can have a compatibility at that core level. I’ll admit it isn’t something I researched too heavily however. I’ve seen a lot of terms thrown around over the years for these extensions, but nothing that sticks in a way you’d want it included among such things as “web page” and “ePub”.

My main problem with using “Markdown” as a label is that in context with MMD and Pandoc options below it in the menu, to my mind anyway that would signify Gruber or CommonMark core syntax—with no support for tables, footnotes, labels and so forth.

As time goes by, I wonder if we’ll see some convergence, and with it a common name we can use—perhaps CommonMark will flesh out into that role even, and become the sort of word that all people recognise. I think for now it’s worth waiting, given the lack of solid alternatives.

Well, that’s what I meant by saying that for the moment it has crystallised, in the other post. That was meant to imply that although I feel it is something that could use clarification, for the moment it works well enough and generates minimal confusion from what we’ve seen thus far since launch. I would hope the documentation, which is revised to be agnostic on the Pandoc/MMD capabilities of the software, helps.
.:.
Ioa Petra'ka
“Whole sight, or all the rest is desolation.” —John Fowles