(enhancement) double proposal for the TOC

[ousia]

The proposal for both TOC title and placement can be simplified without the need of any YAML metadata field.

@ryangray proposed this before, but I didn’t get his proposal then (Ryan, my apologies for not having understood your proposal, which was simpler and better).

All it is required is reserving unique identifier names for sections with automatically–generated contents. In this case it would be {#toc}.

Titles would be included in headings themselves:

# Contents {#toc}

# Inhalt {#toc}

# Περιεχόμενα {#toc}

This way they could also be placed where the user wants.

The same logic could be applied for references (reserving identifier {#references}) and footnotes (reserving name {#footnotes}).

I append the original proposal as a comment for historical purposes.

As already discussed in the mailing list, it would be useful for the users to change the title of the TOC and the place the TOC wherever they want in their document.

My double proposal would be the following:

1. Add a field named toc in the YAML metadata.

   Title should be specified as:

   toc: The Contents
   

   If the field is empty (or contains only spaces), TOC title should be removed.

   The default option remains the same, if there is no toc field in the YAML metadata.

   This hard codes the title, but it is the user who does it and for each document.

2. Allow different placement from its default location.

   The easiest way would be to add a first-level title, such as in:

   # tableofcontents
   

3. Both options should be independent from each other.

   Any of these previous options enables internally the --toc option in pandoc.

Could these suggestions be implemented in pandoc?

[jmuheim]

👍 I like your proposals.

[ryangray]

I've been wanting this too: a way to specify in the doc that it should have a TOC rather than just at the command line. I have a use where I like to convert the documents automatically, so it can't tell the author's intent and choose to set such options on certain files without making some convention that gets pre-processed to allow the script to set options.

I'm wondering if it might be simpler to make use of the fact that when the TOC is generated, it gets the ID of "TOC" and the fact that you can specify the ID of a header. You could simply tag the header you want to be the TOC section with the ID "TOC" and the TOC contents could be inserted there:

% TOC Sample

# Table of Contents {#TOC}

# Section A

Section A content.

# Section B

Section B content.

Given the default header ID names, you could just use "TOC" as the header, although in that case, you may want the TOC section title to be empty.

If you decided that the generated TOC would replace any Markdown content in this section, this could actually allow you to manually make a TOC in the source file for plain text readability (which you would have to maintain) that would get replaced with the hyperlinked one:

% TOC Sample

# Table of Contents {#TOC}

- Section A
- Section B

# Section A

Section A content.

# Section B

Section B content.

You could maintain the plain text TOC by running the source through pandoc and emitting it in Markdown, which with this feature, would put the header list back into the designated TOC section, replacing the old list of headers. A drawback here might be that you would need to specify any extension enables and disables that you are using when running the conversion

The hard part of coding this would be that it is a big change from how it works now which is the template handles it by adding it at the beginning if it is enabled. To put it anywhere would move that to being emitted in the body. A compromise could be to leave it at the top and just allow the TOC title to be set via YAML, enabling the --toc option as described.

-Ryan

On Sep 6, 2014, at 2:19 PM, Pablo Rodríguez notifications@github.com wrote:

As already discussed in the mailing list, it would be useful for the users to change the title of the TOC and the place the TOC wherever they want in their document.

My double proposal would be the following:

Add a field named toc in the YAML metadata.

Title should be specified as:

toc: The Contents
If the field is empty (or contains only spaces), TOC title should be removed.

The default option remains the same, if there is no toc field in the YAML metadata.

This hard codes the title, but it is the user who does it and for each document.

Allow different placement from its default location.

The easiest way would be to add a first-level title, such as in:

tableofcontents

Both options should be independent from each other.

Any of these previous options enables internally the --toc option in pandoc.

Could these suggestions be implemented in pandoc?

—
Reply to this email directly or view it on GitHub.

[ousia]

I'm wondering if it might be simpler to make use of the fact that when the TOC is generated, it gets the ID of "TOC" and the fact that you can specify the ID of a header. You could simply tag the header you want to be the TOC section with the ID "TOC" and the TOC contents could be inserted there:

Many thanks for your reply, @ryangray.

I would rather use the lowercase #toc instead.

Given the default header ID names, you could just use "TOC" as the header, although in that case, you may want the TOC section title to be empty.

Your method is simpler, but if the user wants to have the title specified in the YAML metadata, it has to be typed again. If the title changes (what is often the case when you’re writting a book), it has to be replaced twice. I think this should be avoided.

A compromise solution would be to repeat the title from YAML metadata with the following:

# toc {#toc}

BTW, other identifiers and classes should be allowed with the table of contents, such as in:

# Inhalt {#toc #inhalt .hidden}

If you decided that the generated TOC would replace any Markdown content in this section, this could actually allow you to manually make a TOC in the source file for plain text readability (which you would have to maintain) that would get replaced with the hyperlinked one:

[I must confess I’m not sure I get it.]

Do you really think that it makes sense to write a table of content that doesn’t get in the final document?

I guess that adding a comment could do the job here.

[ryangray]

On Oct 18, 2014, at 11:58 AM, Pablo Rodríguez notifications@github.com wrote:

Given the default header ID names, you could just use "TOC" as the header, although in that case, you may want the TOC section title to be empty.

Your method is simpler, but if the user wants to have the title specified in the YAML metadata, it has to be typed again. If the title changes (what is often the case when you’re writting a book), it has to be replaced twice. I think this should be avoided.

A compromise solution would be to repeat the title from YAML metadata with the following:

toc {#toc}

Well, the IDs are not case sensitive as I recall, so that is equivalent to

# toc

since Pandoc will give it the ID of "#toc". I used #TOC since that's the ID pandoc assigns to the section it generates.

Anyway, I think that the compromise sounds good. There could be a YAML variable, perhaps, "toc-title" that sets the title (if present) in the case where you just name the section "toc" or "TOC":

---

toc-title: Contents
...

toc

Section 1

[...]

eqivalent to:

Contents {#toc}

Section 1

[...]

If you decided that the generated TOC would replace any Markdown content in this section, this could actually allow you to manually make a TOC in the source file for plain text readability (which you would have to maintain) that would get replaced with the hyperlinked one:

[I must confess I’m not sure I get it.]

Do you really think that it makes sense to write a table of content that doesn’t get in the final document?

I worded that a wrong when I said "which you would have to maintain". You wouldn't have to manually edit that section; you would manually run pandoc to make a new markdown version where it replaced that section with the new markdown toc text. It's probably not worth it since you'd have to run pandoc to convert your markdown file to a markdown file and give several options depending on your preferences in order to not change the style:

pandoc -s --toc --to=markdown --atx-headers myfile.md -o myfile.md

Currently, Pandoc will insert the generated toc content into a section with the ID of #toc now, but for markdown format output, it doesn't get put into a section like with HTML.

For example, the source:

Section 1

Some stuff.

Section 2

More stuff.

If you could designate the toc section and that section's content was replaced with the generated toc content, you could output to markdown format and Pandoc would put the toc in that section with the #toc ID, and that markdown source could be run back through Pandoc again to get the toc content updated without duplicating the toc in the resulting output.

For the example source, pandoc --toc -s --to=markdown --atx-headers might output:

toc

• Section 1
• Section 2

Section 1

Some stuff.

Section 2

More stuff.

Then, if we edit this file and add a section 3:

Section 3

Yet more stuff.

then outputs with --toc would replace the "# toc" section with the updated content, with the markdown version becoming:

toc

• Section 1
• Section 2
• Section 3

Section 1

Some stuff.

Section 2

More stuff.

Section 3

Yet more stuff.

rather than duplicating the toc as it would now.

We could use this as our new source file if we wanted. The benefit here would be having a readable toc at the top that we wouldn't have to manually update or remove when we edit the file. In other words, at this point, passing the result again through pandoc --toc -s --to=markdown --atx-headers repeatedly would result in the same output.

Also, the toc section could also be removed if the --toc option is not used.

As you mention, you could also have the toc section title set from a YAML variable like, say, "toc-title" as well.

This part was just a little idea that your original post made me think of and now seems like it's not really that useful for the work involved.

-Ryan

[ousia]

@ryangray, many thanks for your reply. Sorry for not having answered before, but it seems that I erased your reply before having read it.

Well, the IDs are not case sensitive as I recall, so that is equivalent to

# toc

since Pandoc will give it the ID of "#toc".

I used #TOC since that's the ID pandoc assigns to the section it generates.

At least in HTML, identifiers seem to be case-sensitive.

Anyway, I think that the compromise sounds good. There could be a YAML variable, perhaps, "toc-title" that sets the title (if present) in the case where you just name the section "toc" or "TOC":

Why not simply tocto the YAML field?

Sorry, I still don’t get what you are trying to describe with the toc within the Markdown document. Allow me to quote a single sentence:

I worded that a wrong when I said "which you would have to maintain".

It took me a while to understand that the quoted part was written by me. It isn’t only the typo. In your reply, there is no way to distinguish my replies from the words I reply to (your ones). The only way to distinguish has been to read my previous message again.

And even with your own message, I don’t know why you marked it as a comment.

Sorry, I have to guess what could describe the benefit of your proposal:

We could use this as our new source file if we wanted. The benefit here would be having a readable toc at the top that we wouldn't have to manually update or remove when we edit the file. In other words, at this point, passing the result again through pandoc --toc -s --to=markdown --atx-headers repeatedly would result in the same output.

If I get it right, the best way to do it would be to generate an ePub file and browse it with calibre. At least, this is what I do. calibre allows ePub document reloading, which eases the thing a bit.

Is this what you meant?

[lierdakil]

Proposal №2 raises an interesting question: what should we do with other meta-fields, like title, subtitle, authors, date and abstract? I feel like there should be a general templating extension for all of this, really. Pandoc's Markdown does support LaTeX commands, but using ,e.g. \meta{toc}, seems hacky and unintuitive. What's more, this kinda defeats the purpose of Markdown itself... In short, this seems a little more complex than just replacing #toc with table of contents.

[tolot27]

#458 is on the way. 😄

What about making the whole order of components configurable?

There is a line in the sources:

let meta' = title ++ subtitle ++ authors ++ date ++ toc ++ abstract

Making just this line configurable via YAML would solve the entire "order problem". Later on, it can be extended by list of figures (lof) and list of tables (lot) or even later by bib|ref to allow ordering of all main components of a documents.

[lierdakil]

@tolot27 this line is from docx writer code. Other writers have other ideas about what goes where -- and we have to consider all of them here. Which is, relatively speaking, hard.