--help output is misleading/confusing

I was pondering why my SICP writeups seem to be rather lacking in syntax highlighting, even though I had carefully specified the language for all the code-blocks, when it occurred to me that perhaps highlighting-kate wasn't being used.

So I checked the docs first, and read:

"If pandoc has been compiled with syntax highlighting support, then the code block above will appear highlighted, with numbered lines. (To see which languages are supported, do pandoc --version.)"

Fine.

[10:39 PM] 66.2Mb$ pandoc --version pandoc 1.2 -citeproc -highlighting

Copyright (C) 2006-8 John MacFarlane Web: http://johnmacfarlane.net/pandoc This is free software; see the source for copying conditions. There is no warranty, not even for merchantability or fitness for a particular purpose.

See? -highlighting is an option! Case settled, right? I don't remember enabling citeproc support, though...

After poking around, I see -highlighting means the exact opposite of what it looks like to me, a Linux user. Apparently the '-' here is not an 'option' hyphen but a negation or subtraction hyphen!

Carefully I look in my pandoc repo and enable highlighting, and now things seem to be better:

[11:25 PM] .1Mb$ pandoc --version pandoc 1.2 -citeproc +highlighting Compiled with syntax highlighting support for: Ada, Alert, Asp, Awk, Bash, Bibtex, C, Cmake, Coldfusion, Commonlisp, Cpp, Css, D, Djangotemplate, Doxygen, Dtd, Eiffel, Erlang, Fortran, Haskell, Html, Java, Javadoc, Javascript, Json, Latex, Lex, LiterateHaskell, Lua, Makefile, Matlab, Mediawiki, Modula3, Nasm, Objectivec, Ocaml, Pascal, Perl, Php, Postscript, Prolog, Python, Rhtml, Ruby, Scala, Scheme, Sgml, Sql, SqlMysql, SqlPostgresql, Tcl, Texinfo, Xml, Xslt, Yacc Copyright (C) 2006-8 John MacFarlane Web: http://johnmacfarlane.net/pandoc This is free software; see the source for copying conditions. There is no warranty, not even for merchantability or fitness for a particular purpose.

Now that I've specifically enabled one of the features, I see the convention is - and +. (And while I don't see any coloring in pandoc-generated HTML for either Scheme or Haskell, I do see the appropriate HTML code.)

This convention is confusing in the default setting of having neither citeproc or highlighting; something like 'disabled: foo, bar\nenabled: ' would not be so ambiguous. Alternatively (and inferiorly), the readme could be improved to cover this convention.

Google Code Info: Issue #: 139 Author: gwe...@gmail.com Created On: 2009-04-01T03:36:34.000Z Closed On: 2009-05-02T02:37:51.000Z

jgm / pandoc

--help output is misleading/confusing #215