Changes to Pandoc's options to facilitate wrapper scripts:

+ removed -d/--debug option
+ added --dump-args option, which prints the name of the output file
  (or '-' for STDOUT) and all the command-line arguments (excluding
  Pandoc options and their arguments), one per line, then exits.  Note
  that special wrapper options will be treated as arguments if they
  follow '--' at the end of the command line.  Thus,
     pandoc --dump-args -o foo.html foo.txt -- -e latin1 
  will print the following to STDOUT:
     foo.html
     foo.txt
     -e
     latin1
+ added --ignore-args option, which causes Pandoc to ignore all
  (non-option) arguments, including any special options that occur
  after '--' at the end of the command line.
+ '-' now means STDIN as the name of an input file, STDOUT as the
  name of an output file.  So,
     pandoc -o - -
  will take input from STDIN and print output to STDOUT.  Note that
  if multiple '-o' options are specified on the same line, the last
  one takes precedence.  So, in a script,
     pandoc "$@" -o - 
  will guarantee output to STDOUT, even if the '-o' option was used.
+ documented these changes in man pages, README, and changelog.


git-svn-id: https://pandoc.googlecode.com/svn/trunk@454 788f1e2b-df1e-0410-8736-df70ead52e1b

README

@@ -203,6 +203,7 @@ Command-line options
 ====================
 
 Various command-line options can be used to customize the output.
+For further documentation, see the `pandoc(1)` man page.
 
 `-f`, `--from`, `-r`, or `--read` can be used to specify the input
 format -- the format Pandoc will be converting *from*.  Available
@@ -216,8 +217,9 @@ are `native`, `html`, `s5`, `docbook`, `latex`, `markdown`, `rst`, and
 `-s` or `--standalone` indicates that a standalone document is to be
 produced (with appropriate headers and footers), rather than a fragment.
 
-`-o` or `--output` specifies the name of the output file.  If no output
+`-o` or `--output` specifies the name of the output file.  If this
-filename is given, output will be sent to STDOUT.
+option is not specified, or if its argument is `-`, output will be sent
+to STDOUT.
 
 `-p` or `--preserve-tabs` causes tabs in the source text to be
 preserved, rather than converted to spaces (the default).
@@ -284,21 +286,33 @@ is for lists to be displayed all at once.
 `-N` or `--number-sections` causes sections to be numbered in LaTeX
 output.  By default, sections are not numbered.
 
-`-d` or `--debug` causes a debugging message to be written to STDERR.
+`--dump-args` is intended to make it easier to create wrapper scripts
-The format of the message is as follows:
+that use Pandoc.  It causes Pandoc to dump information about the arguments
+with which it was called to STDOUT, then exit.  The first line printed
+is the name of the output file specified using the `-o` or `--output`
+option, or `-` if output would go to STDOUT.  The remaining lines, if any,
+list command-line arguments.  These will include the names of input
+files and any special options passed after ` -- ` on the command line.
+So, for example,
 
-    OUTPUT=foo
+    pandoc --dump-args -o foo.html -s foo.txt appendix.txt -- -e latin1
-    INPUT=bar
-    INPUT=Foo Baz
 
-Here `OUTPUT=` is followed by the name of the output file specified
+will cause the following to be printed to STDOUT:
-using `-o`, if any.  If no output file was specified, `OUTPUT=`
+
-will appear with nothing following it.  Lines beginning `INPUT=`
+    foo.html
-specify input files.  If there are no input files, no `INPUT=` lines
+    foo.txt
-will be printed.  The `-d` option forces output to be written to
+    appendix.txt
-STDOUT, even if an output file was specified using the `-o` option.
+    -e
-(This option is provided to make it easier to write wrappers for
+    latin1
-`pandoc`.)
+
+`--ignore-args` causes Pandoc to ignore all command-line arguments.
+Regular Pandoc options are not ignored.  Thus, for example,
+
+    pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
+
+is equivalent to
+
+    pandoc -o foo.html -s   
 
 `-v` or `--version` prints the version number to STDERR.
 

debian/changelog

@@ -8,12 +8,7 @@ pandoc (0.3) unstable; urgency=low
     + Added '--strict' option for maximum compatibility with official
       Markdown syntax.
     + Added '-o/--output' option to send output to a file.
-    + Added '-d/--debug' option:
+    + Added '--dump-args' and '--ignore-args' options (for use in wrappers).
-      - Prints OUTPUT= followed by output filename (or blank) to stderr.
-      - Prints INPUT= followed by input filename to stderr, for each 
-        input file (if any).
-      - Sends output to STDOUT, even if output file was specified.
-      - This is intended mainly to make it easier to write wrappers.
     + Modified '-v' and '-h' output to go to STDERR, not STDOUT, and return
       error condition (2).  This is helpful for writing wrappers.
     + Reformatted usage message so that it doesn't wrap illegibly.

man/man1/pandoc.1

@@ -93,7 +93,8 @@ Produce output with an appropriate header and footer (e.g. a
 standalone HTML, LaTeX, or RTF file, not a fragment).
 .TP
 .B \-o FILE, \-\-output=FILE
-Write output to \fIFILE\fR instead of STDOUT.
+Write output to \fIFILE\fR instead of STDOUT.  If \fIFILE\fR is
+`\-', output will go to STDOUT.
 .TP
 .B \-p, \-\-preserve-tabs
 Preserve tabs instead of converting them to spaces.
@@ -151,10 +152,25 @@ markdown, rst, rtf\fR).
 .B \-T \fISTRING\fB, \-\-title-prefix=\fISTRING\fB
 Specify \fISTRING\fR as a prefix to the HTML window title.
 .TP
-.B \-d, \-\-debug
+.B \-\-dump\-args
-Print debugging information (names of input and output files) to
+Print information about command\-line arguments to STDOUT, then exit.
-STDERR.  Write output to STDOUT, even if an output file was specified
+The first line of output contains the name of the output file specified
-using the \fB\-o\fR option.
+with the \fB\-o\fR option, or `\-' (for STDOUT) if no output file was
+specified.  The remaining lines contain the command\-line arguments,
+one per line, in the order they appear.  These do not include regular
+Pandoc options and their arguments, but do include any options appearing
+after a `\-\-' separator at the end of the line.
+This option is intended primarily for use in wrapper scripts.
+.TP
+.B \-\-ignore\-args
+Ignore command\-line arguments (for use in wrapper scripts).
+Regular Pandoc options are not ignored.  Thus, for example,
+.IP
+.B pandoc \-\-ignore\-args \-o foo.html \-s foo.txt -- -e latin1
+.IP
+is equivalent to
+.IP
+.B pandoc \-o foo.html \-s
 .TP
 .B \-v, \-\-version
 Print version.

src/Main.hs

@@ -111,7 +111,8 @@ data Opt = Opt
     , optIncremental       :: Bool    -- ^ Use incremental lists in S5
     , optSmart             :: Bool    -- ^ Use smart typography
     , optASCIIMathML       :: Bool    -- ^ Use ASCIIMathML in HTML
-    , optDebug             :: Bool    -- ^ Output debug messages 
+    , optDumpArgs          :: Bool    -- ^ Output command-line arguments
+    , optIgnoreArgs        :: Bool    -- ^ Ignore command-line arguments
     , optStrict            :: Bool    -- ^ Use strict markdown syntax
     }
 
@@ -130,12 +131,13 @@ defaultOpts = Opt
     , optIncludeAfterBody  = ""
     , optCustomHeader      = "DEFAULT"
     , optTitlePrefix       = ""
-    , optOutputFile        = ""    -- null for stdout
+    , optOutputFile        = "-"    -- "-" means stdout
     , optNumberSections    = False
     , optIncremental       = False
     , optSmart             = False
     , optASCIIMathML       = False
-    , optDebug             = False
+    , optDumpArgs          = False
+    , optIgnoreArgs        = False
     , optStrict            = False
     }
 
@@ -267,10 +269,15 @@ options =
                   "FORMAT")
                  "" -- "Print default header for FORMAT"
 
-    , Option "d" ["debug"]
+    , Option "" ["dump-args"]
                  (NoArg
-                  (\opt -> return opt { optDebug = True }))
+                  (\opt -> return opt { optDumpArgs = True }))
-                 "" -- "Print debug messages to stderr, output to stdout"
+                 "" -- "Print output filename and arguments to stdout."
+
+     , Option "" ["ignore-args"]
+                 (NoArg
+                  (\opt -> return opt { optIgnoreArgs = True }))
+                 "" -- "Ignore command-line arguments."
     
     , Option "v" ["version"]
                  (NoArg
@@ -278,7 +285,7 @@ options =
                      prg <- getProgName
                      hPutStrLn stderr (prg ++ " " ++ version ++ 
                                        copyrightMessage)
-                     exitWith $ ExitFailure 2))
+                     exitWith $ ExitFailure 4))
                  "" -- "Print version"
 
     , Option "h" ["help"]
@@ -317,7 +324,7 @@ defaultReaderName (x:xs) =
 
 -- Determine default writer based on output file extension
 defaultWriterName :: String -> String
-defaultWriterName "" = "html" -- no output file
+defaultWriterName "-" = "html" -- no output file
 defaultWriterName x =
   let x' = map toLower x in
   case (matchRegex (mkRegex ".*\\.(.*)") x') of
@@ -341,20 +348,20 @@ defaultWriterName x =
 
 main = do
 
-  args <- getArgs
+  rawArgs <- getArgs
   prg <- getProgName
   let compatMode = (prg == "hsmarkdown")
 
-  let (actions, sources, errors) = if compatMode
+  let (actions, args, errors) = if compatMode
-                                     then ([], args, [])
+                                  then ([], rawArgs, [])
-                                     else getOpt Permute options args
+                                  else getOpt Permute options rawArgs
 
   if (not (null errors))
     then do
       name <- getProgName
       mapM (\e -> hPutStrLn stderr e) errors
       hPutStr stderr (usageMessage name options)
-      exitWith $ ExitFailure 2
+      exitWith $ ExitFailure 3 
     else
       return ()
 
@@ -384,10 +391,13 @@ main = do
               , optIncremental       = incremental
               , optSmart             = smart
               , optASCIIMathML       = asciiMathML
-			  , optDebug             = debug
+              , optDumpArgs          = dumpArgs
+              , optIgnoreArgs        = ignoreArgs
               , optStrict            = strict
              } = opts
 
+  let sources = if ignoreArgs then [] else args
+
   -- assign reader and writer based on options and filenames
   let readerName' = if null readerName 
                       then defaultReaderName sources
@@ -405,14 +415,15 @@ main = do
      Just (w,h) -> return (w, h)
      Nothing    -> error ("Unknown writer: " ++ writerName')
 
-  output <- if ((null outputFile) || debug)
+  output <- if (outputFile == "-")
               then return stdout 
               else openFile outputFile WriteMode
 
-  if debug 
+  if dumpArgs
     then do
-        hPutStrLn stderr ("OUTPUT=" ++ outputFile)
+        hPutStrLn stdout outputFile
-        hPutStr stderr $ concatMap (\s -> "INPUT=" ++ s ++ "\n") sources
+        mapM (\arg -> hPutStrLn stdout arg) args
+        exitWith $ ExitSuccess
     else return ()
 
   let tabFilter = if preserveTabs then id else (tabsToSpaces tabStop)