--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.
Original issue reported on code.google.com by gwe...@gmail.com on 1 Apr 2009 at 3:36
suok-kim / pandoc

--help output is misleading/confusing #139
