Question about man output and -- versus [em]

[Iustin Pop]

Hi,

I'm not sure whether this is a user error or pandoc being too eager.

When using pandoc to generate man pages, it's common to have lots of
"--" (two dashes) for command line options. This is left as-is in the
html output, for example, but the man output converts these into \[em],
which means on text terminals these look like a single dash, and
furthermore copy-paste into a shell is broken.

It is possible to quote the first dash (i.e. write "\--"), but this
becomes cumbersome when writing long documents, and it's very easy to
forget doing it.

Thoughts? Would it make more sense to do this only when the --smart
option is on, as the man page implies already (but seems to be untrue)?

thanks,
iustin

[fiddlosopher]

What I generally do is put the options in code spans:

`--my-option`

and then the hyphens will be left as-is. As you point out,
escaping the first hyphen is another possibility.

Looking at the source code (pandoc.hs), I see that pandoc
sets the 'smart' option automatically if the output format
is LaTeX, ConTeXt, or man. I recall the rationale for
LaTeX and ConTeXt -- leaving quotes as "dumb" will always
give you ugly results there. I think that this was also
the motivation for man, since by default a ' in man is
rendered (not in terminals, but e.g. in PS or HTML output)
as a curly right quote. However, I've recently changed
the man writer a bit, so that it will escape ' as \[aq],
so it would probably make sense to allow man output without
--smart.

Any thoughts?

John

[John MacFarlane]

+++ fiddlosopher [Dec 29 11 10:56 ]:

> What I generally do is put the options in code spans:
>
> `--my-option`
>
> and then the hyphens will be left as-is. As you point out,
> escaping the first hyphen is another possibility.
>
> Looking at the source code (pandoc.hs), I see that pandoc
> sets the 'smart' option automatically if the output format
> is LaTeX, ConTeXt, or man. I recall the rationale for
> LaTeX and ConTeXt -- leaving quotes as "dumb" will always
> give you ugly results there. I think that this was also
> the motivation for man, since by default a ' in man is
> rendered (not in terminals, but e.g. in PS or HTML output)
> as a curly right quote. However, I've recently changed
> the man writer a bit, so that it will escape ' as \[aq],
> so it would probably make sense to allow man output without
> --smart.
>
> Any thoughts?

I've changed pandoc so it doesn't automatically use --smart
for man output.

[Iustin Pop]

Thanks, that makes sense. Yay!

iustin