5dda65b · typeable/pandoc

git.iko.soy/typeable/pandoc

on master help sign in

Changes to Pandoc's options to facilitate wrapper scripts:

5dda65bfiddlosopher20 years ago

README+31−17

compare with master

unifiedsplit

@@ -203,6 +203,7 @@ Command-line options

203====================

204

205Various command-line options can be used to customize the output.

206+For further documentation, see the `pandoc(1)` man page.

206

207

207`-f`, `--from`, `-r`, or `--read` can be used to specify the input

208`-f`, `--from`, `-r`, or `--read` can be used to specify the input

208format -- the format Pandoc will be converting *from*. Available

209format -- the format Pandoc will be converting *from*. Available

@@ -216,8 +217,9 @@ are `native`, `html`, `s5`, `docbook`, `latex`, `markdown`, `rst`, and

216`-s` or `--standalone` indicates that a standalone document is to be

217`-s` or `--standalone` indicates that a standalone document is to be

217produced (with appropriate headers and footers), rather than a fragment.

218produced (with appropriate headers and footers), rather than a fragment.

218

219

219−`-o` or `--output` specifies the name of the output file. If no output

220+`-o` or `--output` specifies the name of the output file. If this

220−filename is given, output will be sent to STDOUT.

221+option is not specified, or if its argument is `-`, output will be sent

222+to STDOUT.

221

223

222`-p` or `--preserve-tabs` causes tabs in the source text to be

224`-p` or `--preserve-tabs` causes tabs in the source text to be

223preserved, rather than converted to spaces (the default).

225preserved, rather than converted to spaces (the default).

@@ -284,21 +286,33 @@ is for lists to be displayed all at once.

284`-N` or `--number-sections` causes sections to be numbered in LaTeX

286`-N` or `--number-sections` causes sections to be numbered in LaTeX

285output. By default, sections are not numbered.

287output. By default, sections are not numbered.

286

288

287−`-d` or `--debug` causes a debugging message to be written to STDERR.

289+`--dump-args` is intended to make it easier to create wrapper scripts

288−The format of the message is as follows:

290+that use Pandoc. It causes Pandoc to dump information about the arguments

289−

291+with which it was called to STDOUT, then exit. The first line printed

290− OUTPUT=foo

291− INPUT=bar

292− INPUT=Foo Baz

293−

294−Here `OUTPUT=` is followed by the name of the output file specified

292+is the name of the output file specified using the `-o` or `--output`

295−using `-o`, if any. If no output file was specified, `OUTPUT=`

293+option, or `-` if output would go to STDOUT. The remaining lines, if any,

296−will appear with nothing following it. Lines beginning `INPUT=`

294+list command-line arguments. These will include the names of input

297−specify input files. If there are no input files, no `INPUT=` lines

295+files and any special options passed after ` -- ` on the command line.

298−will be printed. The `-d` option forces output to be written to

296+So, for example,

299−STDOUT, even if an output file was specified using the `-o` option.

297+

300−(This option is provided to make it easier to write wrappers for

298+ pandoc --dump-args -o foo.html -s foo.txt appendix.txt -- -e latin1

301−`pandoc`.)

299+

300+will cause the following to be printed to STDOUT:

301+

302+ foo.html

303+ foo.txt

304+ appendix.txt

305+ -e

306+ latin1

307+

308+`--ignore-args` causes Pandoc to ignore all command-line arguments.

309+Regular Pandoc options are not ignored. Thus, for example,

310+

311+ pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1

312+

313+is equivalent to

314+

315+ pandoc -o foo.html -s

302

316

303`-v` or `--version` prints the version number to STDERR.

317`-v` or `--version` prints the version number to STDERR.

304

318

debian/changelog+1−6

@@ -8,12 +8,7 @@ pandoc (0.3) unstable; urgency=low

8 + Added '--strict' option for maximum compatibility with official

9 Markdown syntax.

10 + Added '-o/--output' option to send output to a file.

11− + Added '-d/--debug' option:

11+ + Added '--dump-args' and '--ignore-args' options (for use in wrappers).

12− - Prints OUTPUT= followed by output filename (or blank) to stderr.

13− - Prints INPUT= followed by input filename to stderr, for each

14− input file (if any).

15− - Sends output to STDOUT, even if output file was specified.

16− - This is intended mainly to make it easier to write wrappers.

17 + Modified '-v' and '-h' output to go to STDERR, not STDOUT, and return

12 + Modified '-v' and '-h' output to go to STDERR, not STDOUT, and return

18 error condition (2). This is helpful for writing wrappers.

13 error condition (2). This is helpful for writing wrappers.

19 + Reformatted usage message so that it doesn't wrap illegibly.

14 + Reformatted usage message so that it doesn't wrap illegibly.

man/man1/pandoc.1+21−5

@@ -93,7 +93,8 @@ Produce output with an appropriate header and footer (e.g. a

93standalone HTML, LaTeX, or RTF file, not a fragment).

94.TP

95.B \-o FILE, \-\-output=FILE

96−Write output to \fIFILE\fR instead of STDOUT.

96+Write output to \fIFILE\fR instead of STDOUT. If \fIFILE\fR is

97+`\-', output will go to STDOUT.

97.TP

98.TP

98.B \-p, \-\-preserve-tabs

99.B \-p, \-\-preserve-tabs

99Preserve tabs instead of converting them to spaces.

100Preserve tabs instead of converting them to spaces.

@@ -151,10 +152,25 @@ markdown, rst, rtf\fR).

151.B \-T \fISTRING\fB, \-\-title-prefix=\fISTRING\fB

152.B \-T \fISTRING\fB, \-\-title-prefix=\fISTRING\fB

152Specify \fISTRING\fR as a prefix to the HTML window title.

153Specify \fISTRING\fR as a prefix to the HTML window title.

153.TP

154.TP

154−.B \-d, \-\-debug

155+.B \-\-dump\-args

155−Print debugging information (names of input and output files) to

156+Print information about command\-line arguments to STDOUT, then exit.

156−STDERR. Write output to STDOUT, even if an output file was specified

157+The first line of output contains the name of the output file specified

157−using the \fB\-o\fR option.

158+with the \fB\-o\fR option, or `\-' (for STDOUT) if no output file was

159+specified. The remaining lines contain the command\-line arguments,

160+one per line, in the order they appear. These do not include regular

161+Pandoc options and their arguments, but do include any options appearing

162+after a `\-\-' separator at the end of the line.

163+This option is intended primarily for use in wrapper scripts.

164+.TP

165+.B \-\-ignore\-args

166+Ignore command\-line arguments (for use in wrapper scripts).

167+Regular Pandoc options are not ignored. Thus, for example,

168+.IP

169+.B pandoc \-\-ignore\-args \-o foo.html \-s foo.txt -- -e latin1

170+.IP

171+is equivalent to

172+.IP

173+.B pandoc \-o foo.html \-s

158.TP

174.TP

159.B \-v, \-\-version

175.B \-v, \-\-version

160Print version.

176Print version.

src/Main.hs+30−19

@@ -111,7 +111,8 @@ data Opt = Opt

111 , optIncremental :: Bool -- ^ Use incremental lists in S5

112 , optSmart :: Bool -- ^ Use smart typography

113 , optASCIIMathML :: Bool -- ^ Use ASCIIMathML in HTML

114− , optDebug :: Bool -- ^ Output debug messages

114+ , optDumpArgs :: Bool -- ^ Output command-line arguments

115+ , optIgnoreArgs :: Bool -- ^ Ignore command-line arguments

115 , optStrict :: Bool -- ^ Use strict markdown syntax

116 , optStrict :: Bool -- ^ Use strict markdown syntax

116 }

117 }

117

118

@@ -130,12 +131,13 @@ defaultOpts = Opt

130 , optIncludeAfterBody = ""

131 , optIncludeAfterBody = ""

131 , optCustomHeader = "DEFAULT"

132 , optCustomHeader = "DEFAULT"

132 , optTitlePrefix = ""

133 , optTitlePrefix = ""

133− , optOutputFile = "" -- null for stdout

134+ , optOutputFile = "-" -- "-" means stdout

134 , optNumberSections = False

135 , optNumberSections = False

135 , optIncremental = False

136 , optIncremental = False

136 , optSmart = False

137 , optSmart = False

137 , optASCIIMathML = False

138 , optASCIIMathML = False

138− , optDebug = False

139+ , optDumpArgs = False

140+ , optIgnoreArgs = False

139 , optStrict = False

141 , optStrict = False

140 }

142 }

141

143

@@ -267,10 +269,15 @@ options =

267 "FORMAT")

269 "FORMAT")

268 "" -- "Print default header for FORMAT"

270 "" -- "Print default header for FORMAT"

269

271

270− , Option "d" ["debug"]

272+ , Option "" ["dump-args"]

271 (NoArg

273 (NoArg

272− (\opt -> return opt { optDebug = True }))

274+ (\opt -> return opt { optDumpArgs = True }))

273− "" -- "Print debug messages to stderr, output to stdout"

275+ "" -- "Print output filename and arguments to stdout."

276+

277+ , Option "" ["ignore-args"]

278+ (NoArg

279+ (\opt -> return opt { optIgnoreArgs = True }))

280+ "" -- "Ignore command-line arguments."

274

281

275 , Option "v" ["version"]

282 , Option "v" ["version"]

276 (NoArg

283 (NoArg

@@ -278,7 +285,7 @@ options =

278 prg <- getProgName

285 prg <- getProgName

279 hPutStrLn stderr (prg ++ " " ++ version ++

286 hPutStrLn stderr (prg ++ " " ++ version ++

280 copyrightMessage)

287 copyrightMessage)

281− exitWith $ ExitFailure 2))

288+ exitWith $ ExitFailure 4))

282 "" -- "Print version"

289 "" -- "Print version"

283

290

284 , Option "h" ["help"]

291 , Option "h" ["help"]

@@ -317,7 +324,7 @@ defaultReaderName (x:xs) =

317

324

318-- Determine default writer based on output file extension

325-- Determine default writer based on output file extension

319defaultWriterName :: String -> String

326defaultWriterName :: String -> String

320−defaultWriterName "" = "html" -- no output file

327+defaultWriterName "-" = "html" -- no output file

321defaultWriterName x =

328defaultWriterName x =

322 let x' = map toLower x in

329 let x' = map toLower x in

323 case (matchRegex (mkRegex ".*\\.(.*)") x') of

330 case (matchRegex (mkRegex ".*\\.(.*)") x') of

@@ -341,20 +348,20 @@ defaultWriterName x =

341

348

342main = do

349main = do

343

350

344− args <- getArgs

351+ rawArgs <- getArgs

345 prg <- getProgName

352 prg <- getProgName

346 let compatMode = (prg == "hsmarkdown")

353 let compatMode = (prg == "hsmarkdown")

347

354

348− let (actions, sources, errors) = if compatMode

355+ let (actions, args, errors) = if compatMode

349− then ([], args, [])

356+ then ([], rawArgs, [])

350− else getOpt Permute options args

357+ else getOpt Permute options rawArgs

351

358

352 if (not (null errors))

359 if (not (null errors))

353 then do

360 then do

354 name <- getProgName

361 name <- getProgName

355 mapM (\e -> hPutStrLn stderr e) errors

362 mapM (\e -> hPutStrLn stderr e) errors

356 hPutStr stderr (usageMessage name options)

363 hPutStr stderr (usageMessage name options)

357− exitWith $ ExitFailure 2

364+ exitWith $ ExitFailure 3

358 else

365 else

359 return ()

366 return ()

360

367

@@ -384,10 +391,13 @@ main = do

384 , optIncremental = incremental

391 , optIncremental = incremental

385 , optSmart = smart

392 , optSmart = smart

386 , optASCIIMathML = asciiMathML

393 , optASCIIMathML = asciiMathML

387− , optDebug = debug

394+ , optDumpArgs = dumpArgs

395+ , optIgnoreArgs = ignoreArgs

388 , optStrict = strict

396 , optStrict = strict

389 } = opts

397 } = opts

390

398

399+ let sources = if ignoreArgs then [] else args

400+

391 -- assign reader and writer based on options and filenames

401 -- assign reader and writer based on options and filenames

392 let readerName' = if null readerName

402 let readerName' = if null readerName

393 then defaultReaderName sources

403 then defaultReaderName sources

@@ -405,14 +415,15 @@ main = do

405 Just (w,h) -> return (w, h)

415 Just (w,h) -> return (w, h)

406 Nothing -> error ("Unknown writer: " ++ writerName')

416 Nothing -> error ("Unknown writer: " ++ writerName')

407

417

408− output <- if ((null outputFile) || debug)

418+ output <- if (outputFile == "-")

409 then return stdout

419 then return stdout

410 else openFile outputFile WriteMode

420 else openFile outputFile WriteMode

411

421

412− if debug

422+ if dumpArgs

413− then do

423+ then do

414− hPutStrLn stderr ("OUTPUT=" ++ outputFile)

424+ hPutStrLn stdout outputFile

415− hPutStr stderr $ concatMap (\s -> "INPUT=" ++ s ++ "\n") sources

425+ mapM (\arg -> hPutStrLn stdout arg) args

426+ exitWith $ ExitSuccess

416 else return ()

427 else return ()

417

428

418 let tabFilter = if preserveTabs then id else (tabsToSpaces tabStop)

429 let tabFilter = if preserveTabs then id else (tabsToSpaces tabStop)