From 5dda65b5dc9213f74f7d33777e002fae903d1cd1 Mon Sep 17 00:00:00 2001 From: fiddlosopher Date: Mon, 8 Jan 2007 08:11:08 +0000 Subject: 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 | 48 +++++++++++++++++++++++++++++++----------------- debian/changelog | 7 +------ man/man1/pandoc.1 | 26 +++++++++++++++++++++----- src/Main.hs | 49 ++++++++++++++++++++++++++++++------------------- 4 files changed, 83 insertions(+), 47 deletions(-) diff --git a/README b/README index 9ce52049d..de1efc1bc 100644 --- a/README +++ b/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 -filename is given, output will be sent to STDOUT. +`-o` or `--output` specifies the name of the output file. If this +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. -The format of the message is as follows: - - OUTPUT=foo - INPUT=bar - INPUT=Foo Baz - -Here `OUTPUT=` is followed by the name of the output file specified -using `-o`, if any. If no output file was specified, `OUTPUT=` -will appear with nothing following it. Lines beginning `INPUT=` -specify input files. If there are no input files, no `INPUT=` lines -will be printed. The `-d` option forces output to be written to -STDOUT, even if an output file was specified using the `-o` option. -(This option is provided to make it easier to write wrappers for -`pandoc`.) +`--dump-args` is intended to make it easier to create wrapper scripts +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, + + pandoc --dump-args -o foo.html -s foo.txt appendix.txt -- -e latin1 + +will cause the following to be printed to STDOUT: + + foo.html + foo.txt + appendix.txt + -e + latin1 + +`--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. diff --git a/debian/changelog b/debian/changelog index 682b2e54a..a06c40579 100644 --- a/debian/changelog +++ b/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: - - 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. + + Added '--dump-args' and '--ignore-args' options (for use in 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. diff --git a/man/man1/pandoc.1 b/man/man1/pandoc.1 index 199551f22..8c3c62e15 100644 --- a/man/man1/pandoc.1 +++ b/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 -Print debugging information (names of input and output files) to -STDERR. Write output to STDOUT, even if an output file was specified -using the \fB\-o\fR option. +.B \-\-dump\-args +Print information about command\-line arguments to STDOUT, then exit. +The first line of output contains the name of the output file specified +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. diff --git a/src/Main.hs b/src/Main.hs index b5de582d3..32576074b 100644 --- a/src/Main.hs +++ b/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 })) - "" -- "Print debug messages to stderr, output to stdout" + (\opt -> return opt { optDumpArgs = True })) + "" -- "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 - then ([], args, []) - else getOpt Permute options args + let (actions, args, errors) = if compatMode + then ([], rawArgs, []) + 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 - then do - hPutStrLn stderr ("OUTPUT=" ++ outputFile) - hPutStr stderr $ concatMap (\s -> "INPUT=" ++ s ++ "\n") sources + if dumpArgs + then do + hPutStrLn stdout outputFile + mapM (\arg -> hPutStrLn stdout arg) args + exitWith $ ExitSuccess else return () let tabFilter = if preserveTabs then id else (tabsToSpaces tabStop) -- cgit v1.2.3