Provide example in output

[ghost]

Replicate

In a Unix-y OS:

1. echo "# Hello" > hello.md
2. pandoc --standalone -s hello.md -o hello.html

Expected

Pandoc informs user as to how to eliminate the warning by way of example.

Example Output

[WARNING] This document format requires a nonempty <title> element.
  Please specify either 'title' or 'pagetitle' in the metadata.
  Falling back to 'hello'
  Example: pandoc --standalone --metadata title="Document Title" -s hello.md -o hello.html

Actual

Pandoc informs the user of the problem, but no suggestions as to an immediate solution.

Related

This issue is related to #4048.

[jgm]

Pandoc informs the user of the problem, but no suggestions as to an immediate solution.

It says: "Please specify either title or pagetitle in the metadata." I would have thought that's a suggestion for an immediate solution. Granted, you have to know how to specify fields in metadata. But this is all in the manual. As it stands, then, the warning gives you a helpful suggestion about what you need to look up in the manual. Should the warning go further and reproduce or summarize pieces of the manual? That seems like more than a warning is normally expected to do.

[jgm]

The particular example given might make people think that this is what you have to do to specify metadata. But it's just one option. A better one, if your source is markdown, would be to use a YAML metadata block. And in future versions of pandoc, --metadata-file would be available for all source formats. Should we be steering them to the --metadata flag when these other options are available?

You may be right that giving an example like this is a good idea, but I'm not sold on the idea yet.

[ghost]

You may be right that giving an example like this is a good idea, but I'm not sold on the idea yet.

I'm reminded of the following joke:

A helicopter was flying above Seattle when a malfunction disabled the aircraft's communications equipment. Due to light fog, the pilot couldn't determine how to reach the airport, but saw a tall building. She flew toward it, drew a handwritten sign, and then held it against the helicopter's window. The sign read, "WHERE AM I?" in large letters. People in the building quickly drafted a large sign and held it up in response. Their sign read: "YOU ARE IN A HELICOPTER." The pilot smiled, waved, mapped a course to SEATAC airport, and landed safely. After landing, the co-pilot asked her how "YOU ARE IN A HELICOPTER" helped determine their position. The pilot replied, "I knew that had to be the Microsoft building in Redmond because, like their technical support, online help, and product documentation, the response they gave me was technically correct, but completely useless."

It seems systemic that we, as software developers, write help that indicates the problem but seldom provides a solution. This then results in numerous people asking questions about what to do next. It's also one of the reasons why StackOverflow is so popular: nobody has the time or desire to fully RTFM--especially when TFMs are dozens to hundreds of pages long.

Since YAML headers are a possible solution, nothing precludes stating that as well. Or link to online documentation that provides further examples. Such as:

[WARNING] This document format requires a nonempty <title> element.
  Please specify either 'title' or 'pagetitle' in the metadata.
  Falling back to 'hello'
  Example: pandoc --standalone --metadata title="Document Title" -s hello.md -o hello.html
  For more possibilities see: http://pandoc.org/faqs.html#html-output-requires-nonempty-title

[jgm]

I like the joke, and I appreciate the point. But about

nobody has the time or desire to fully RTFM

In this case, all they have to do is open up the manual and search for "metadata," and they should pretty quickly find the information they need. I would not be too sympathetic to someone who is unwilling to take a few seconds to do that, but doesn't mind imposing on others' time to ask questions.

I looked at some of the questions you linked to. Note that many of them concern other tools that are using pandoc under the hood. In these cases the example you gave would be no help. I think people are asking the questions because they don't know the message is coming from pandoc and so don't even know where to begin looking for an answer.

[ghost]

In this case, all they have to do is open up the manual and search for "metadata," and they should pretty quickly find the information they need.

Agreed. And yet clicking a link is even faster and opens up the possibility of having more people contribute to improve the product documentation. (I have modified numerous pages on the Context Garden wiki because changing the wiki is far faster and simpler than modifying Context's console help.)

[elviejo79]

I had this same problem, while using emacs markdown-mode and the solution was:

First update pandoc to the newest verison.

In ubuntu my version was 2.9.x.x

So I had to update using the .deb package.
See here for the instructions: https://stackoverflow.com/a/61101060/54848
now I had pandoc 2.14.x.x

Then I had to add the metadata as part of my markdown file:

---
pagetitle: 'This is another title'
---

I had to use pagetitle since just title didn't work.

finally I could generate the html with:

pandoc --from gfm --to html5