1da40d6 · typeable/pandoc

MANUAL.txt+13−5

compare with master

unifiedsplit

@@ -661,11 +661,19 @@ Options affecting specific writers

661

662`--chapters`

663

664+: Deprecated synonym for `--top-level-division=chapter`.

665+

666+`--top-level-division=[section|chapter|part]`

667+

664−: Treat top-level headers as chapters in LaTeX, ConTeXt, and DocBook

668+: Treat top-level headers as the given division type in LaTeX, ConTeXt,

669+ DocBook, and TEI output. The hierarchy order is part, chapter, then section;

670+ all headers are shifted such that the top-level header becomes the specified

665− output. When the LaTeX document class is set to `report`, `book`,

671+ type. The default is `section`. When the LaTeX document class is set to

666− or `memoir` (unless the `article` option is specified), this

672+ `report`, `book`, or `memoir` (unless the `article` option is specified),

667− option is implied. If `beamer` is the output format, top-level

673+ `chapter` is implied as the setting for this option. If `beamer` is the

668− headers will become `\part{..}`.

674+ output format, specifying either `chapter` or `part` will cause top-level

675+ headers to become `\part{..}`, while second-level headers remain as their

676+ default type.

669

677

670`-N`, `--number-sections`

678`-N`, `--number-sections`

671

679

pandoc.hs+15−5

@@ -183,7 +183,7 @@ data Opt = Opt

183 , optHtmlQTags :: Bool -- ^ Use <q> tags in HTML

184 , optHighlight :: Bool -- ^ Highlight source code

185 , optHighlightStyle :: Style -- ^ Style to use for highlighted code

186− , optChapters :: Bool -- ^ Use chapter for top-level sects

186+ , optTopLevelDivision :: Division -- ^ Type of the top-level divisions

187 , optHTMLMathMethod :: HTMLMathMethod -- ^ Method to print HTML math

188 , optReferenceODT :: Maybe FilePath -- ^ Path of reference.odt

189 , optReferenceDocx :: Maybe FilePath -- ^ Path of reference.docx

@@ -248,7 +248,7 @@ defaultOpts = Opt

248 , optHtmlQTags = False

249 , optHighlight = True

250 , optHighlightStyle = pygments

251− , optChapters = False

251+ , optTopLevelDivision = Section

252 , optHTMLMathMethod = PlainMath

253 , optReferenceODT = Nothing

254 , optReferenceDocx = Nothing

@@ -606,9 +606,19 @@ options =

606

607 , Option "" ["chapters"]

608 (NoArg

609− (\opt -> return opt { optChapters = True }))

609+ (\opt -> do warn $ "--chapters is deprecated. " ++

610+ "Use --top-level-divison=chapter instead."

611+ return opt { optTopLevelDivision = Chapter }))

610 "" -- "Use chapter for top-level sections in LaTeX, DocBook"

612 "" -- "Use chapter for top-level sections in LaTeX, DocBook"

611

613

614+ , Option "" ["top-level-division"]

615+ (ReqArg

616+ (\arg opt -> case safeRead (uppercaseFirstLetter arg) of

617+ Just dvsn -> return opt { optTopLevelDivision = dvsn }

618+ _ -> err 76 "could not parse top-level division")

619+ "[section|chapter|part]")

620+ "" -- "Use top-level division type in LaTeX, ConTeXt, DocBook"

621+

612 , Option "N" ["number-sections"]

622 , Option "N" ["number-sections"]

613 (NoArg

623 (NoArg

614 (\opt -> return opt { optNumberSections = True }))

624 (\opt -> return opt { optNumberSections = True }))

@@ -1122,7 +1132,7 @@ convertWithOpts opts args = do

1122 , optHtmlQTags = htmlQTags

1132 , optHtmlQTags = htmlQTags

1123 , optHighlight = highlight

1133 , optHighlight = highlight

1124 , optHighlightStyle = highlightStyle

1134 , optHighlightStyle = highlightStyle

1125− , optChapters = chapters

1135+ , optTopLevelDivision = topLevelDivision

1126 , optHTMLMathMethod = mathMethod'

1136 , optHTMLMathMethod = mathMethod'

1127 , optReferenceODT = referenceODT

1137 , optReferenceODT = referenceODT

1128 , optReferenceDocx = referenceDocx

1138 , optReferenceDocx = referenceDocx

@@ -1386,7 +1396,7 @@ convertWithOpts opts args = do

1386 writerUserDataDir = datadir,

1396 writerUserDataDir = datadir,

1387 writerHtml5 = html5,

1397 writerHtml5 = html5,

1388 writerHtmlQTags = htmlQTags,

1398 writerHtmlQTags = htmlQTags,

1389− writerChapters = chapters,

1399+ writerTopLevelDivision = topLevelDivision,

1390 writerListings = listings,

1400 writerListings = listings,

1391 writerBeamer = False,

1401 writerBeamer = False,

1392 writerSlideLevel = slideLevel,

1402 writerSlideLevel = slideLevel,

src/Text/Pandoc/Options.hs+9−2

@@ -43,6 +43,7 @@ module Text.Pandoc.Options ( Extension(..)

43 , HTMLSlideVariant (..)

44 , EPUBVersion (..)

45 , WrapOption (..)

46+ , Division (..)

46 , WriterOptions (..)

47 , WriterOptions (..)

47 , TrackChanges (..)

48 , TrackChanges (..)

48 , ReferenceLocation (..)

49 , ReferenceLocation (..)

@@ -337,6 +338,12 @@ data WrapOption = WrapAuto -- ^ Automatically wrap to width

337 | WrapPreserve -- ^ Preserve wrapping of input source

338 | WrapPreserve -- ^ Preserve wrapping of input source

338 deriving (Show, Read, Eq, Data, Typeable, Generic)

339 deriving (Show, Read, Eq, Data, Typeable, Generic)

339

340

341+-- | Options defining the type of top-level headers.

342+data Division = Part -- ^ Top-level headers become parts

343+ | Chapter -- ^ Top-level headers become chapters

344+ | Section -- ^ Top-level headers become sections

345+ deriving (Show, Read, Eq, Ord, Data, Typeable, Generic)

346+

340-- | Locations for footnotes and references in markdown output

347-- | Locations for footnotes and references in markdown output

341data ReferenceLocation = EndOfBlock -- ^ End of block

348data ReferenceLocation = EndOfBlock -- ^ End of block

342 | EndOfSection -- ^ prior to next section header (or end of document)

349 | EndOfSection -- ^ prior to next section header (or end of document)

@@ -373,7 +380,7 @@ data WriterOptions = WriterOptions

373 , writerHtmlQTags :: Bool -- ^ Use @<q>@ tags for quotes in HTML

380 , writerHtmlQTags :: Bool -- ^ Use @<q>@ tags for quotes in HTML

374 , writerBeamer :: Bool -- ^ Produce beamer LaTeX slide show

381 , writerBeamer :: Bool -- ^ Produce beamer LaTeX slide show

375 , writerSlideLevel :: Maybe Int -- ^ Force header level of slides

382 , writerSlideLevel :: Maybe Int -- ^ Force header level of slides

376− , writerChapters :: Bool -- ^ Use "chapter" for top-level sects

383+ , writerTopLevelDivision :: Division -- ^ Type of top-level divisions

377 , writerListings :: Bool -- ^ Use listings package for code

384 , writerListings :: Bool -- ^ Use listings package for code

378 , writerHighlight :: Bool -- ^ Highlight source code

385 , writerHighlight :: Bool -- ^ Highlight source code

379 , writerHighlightStyle :: Style -- ^ Style to use for highlighting

386 , writerHighlightStyle :: Style -- ^ Style to use for highlighting

@@ -421,7 +428,7 @@ instance Default WriterOptions where

421 , writerHtmlQTags = False

428 , writerHtmlQTags = False

422 , writerBeamer = False

429 , writerBeamer = False

423 , writerSlideLevel = Nothing

430 , writerSlideLevel = Nothing

424− , writerChapters = False

431+ , writerTopLevelDivision = Section

425 , writerListings = False

432 , writerListings = False

426 , writerHighlight = False

433 , writerHighlight = False

427 , writerHighlightStyle = pygments

434 , writerHighlightStyle = pygments

src/Text/Pandoc/Writers/ConTeXt.hs+21−15

@@ -83,9 +83,10 @@ pandocToConTeXt options (Pandoc meta blocks) = do

83 ]

84 let context = defField "toc" (writerTableOfContents options)

85 $ defField "placelist" (intercalate ("," :: String) $

86− take (writerTOCDepth options + if writerChapters options

86+ take (writerTOCDepth options +

87+ if writerTopLevelDivision options < Section

87− then 0

88+ then 0

88− else 1)

89+ else 1)

89 ["chapter","section","subsection","subsubsection",

90 ["chapter","section","subsection","subsubsection",

90 "subsubsubsection","subsubsubsubsection"])

91 "subsubsubsection","subsubsubsubsection"])

91 $ defField "body" main

92 $ defField "body" main

@@ -412,7 +413,7 @@ inlineToConTeXt (Span (_,_,kvs) ils) = do

412 Nothing -> txt

413 Nothing -> txt

413 fmap (wrapLang . wrapDir) $ inlineListToConTeXt ils

414 fmap (wrapLang . wrapDir) $ inlineListToConTeXt ils

414

415

415−-- | Craft the section header, inserting the secton reference, if supplied.

416+-- | Craft the section header, inserting the section reference, if supplied.

416sectionHeader :: Attr

417sectionHeader :: Attr

417 -> Int

418 -> Int

418 -> [Inline]

419 -> [Inline]

@@ -421,21 +422,26 @@ sectionHeader (ident,classes,_) hdrLevel lst = do

421 contents <- inlineListToConTeXt lst

422 contents <- inlineListToConTeXt lst

422 st <- get

423 st <- get

423 let opts = stOptions st

424 let opts = stOptions st

424− let level' = if writerChapters opts then hdrLevel - 1 else hdrLevel

425+ let level' = case writerTopLevelDivision opts of

426+ Part -> hdrLevel - 2

427+ Chapter -> hdrLevel - 1

428+ Section -> hdrLevel

425 let ident' = toLabel ident

429 let ident' = toLabel ident

426 let (section, chapter) = if "unnumbered" `elem` classes

430 let (section, chapter) = if "unnumbered" `elem` classes

427 then (text "subject", text "title")

431 then (text "subject", text "title")

428 else (text "section", text "chapter")

432 else (text "section", text "chapter")

429− return $ if level' >= 1 && level' <= 5

433+ return $ case level' of

434+ -1 -> text "\\part" <> braces contents

435+ 0 -> char '\\' <> chapter <> braces contents

430− then char '\\'

436+ n | n >= 1 && n <= 5 -> char '\\'

431− <> text (concat (replicate (level' - 1) "sub"))

437+ <> text (concat (replicate (n - 1) "sub"))

432− <> section

438+ <> section

439+ <> (if (not . null) ident'

433− <> (if (not . null) ident' then brackets (text ident') else empty)

440+ then brackets (text ident')

441+ else empty)

434− <> braces contents

442+ <> braces contents

435− <> blankline

443+ <> blankline

436− else if level' == 0

437− then char '\\' <> chapter <> braces contents

438− else contents <> blankline

444+ _ -> contents <> blankline

439

445

440fromBcp47' :: String -> String

446fromBcp47' :: String -> String

441fromBcp47' = fromBcp47 . splitBy (=='-')

447fromBcp47' = fromBcp47 . splitBy (=='-')

src/Text/Pandoc/Writers/Docbook.hs+14−9

@@ -79,12 +79,16 @@ writeDocbook opts (Pandoc meta blocks) =

79 colwidth = if writerWrapText opts == WrapAuto

80 then Just $ writerColumns opts

81 else Nothing

82− render' = render colwidth

82+ render' = render colwidth

83− opts' = if "/book>" `isSuffixOf`

84− (trimr $ writerTemplate opts)

83+ opts' = if ("/book>" `isSuffixOf` (trimr $ writerTemplate opts) &&

85− then opts{ writerChapters = True }

84+ writerTopLevelDivision opts >= Section)

85+ then opts{ writerTopLevelDivision = Chapter }

86− else opts

86+ else opts

87− startLvl = if writerChapters opts' then 0 else 1

87+ -- The numbering here follows LaTeX's internal numbering

88+ startLvl = case writerTopLevelDivision opts' of

89+ Part -> -1

90+ Chapter -> 0

91+ Section -> 1

88 auths' = map (authorToDocbook opts) $ docAuthors meta

92 auths' = map (authorToDocbook opts) $ docAuthors meta

89 meta' = B.setMeta "author" auths' meta

93 meta' = B.setMeta "author" auths' meta

90 Just metadata = metaToJSON opts

94 Just metadata = metaToJSON opts

@@ -111,11 +115,12 @@ elementToDocbook opts lvl (Sec _ _num (id',_,_) title elements) =

111 then [Blk (Para [])]

115 then [Blk (Para [])]

112 else elements

116 else elements

113 tag = case lvl of

117 tag = case lvl of

118+ -1 -> "part"

114− n | n == 0 -> "chapter"

119+ 0 -> "chapter"

115− | n >= 1 && n <= 5 -> if writerDocbook5 opts

120+ n | n >= 1 && n <= 5 -> if writerDocbook5 opts

116 then "section"

121 then "section"

117 else "sect" ++ show n

122 else "sect" ++ show n

118− | otherwise -> "simplesect"

123+ _ -> "simplesect"

119 idAttr = [("id", writerIdentifierPrefix opts ++ id') | not (null id')]

124 idAttr = [("id", writerIdentifierPrefix opts ++ id') | not (null id')]

120 nsAttr = if writerDocbook5 opts && lvl == 0 then [("xmlns", "http://docbook.org/ns/docbook"),("xmlns:xlink", "http://www.w3.org/1999/xlink")]

125 nsAttr = if writerDocbook5 opts && lvl == 0 then [("xmlns", "http://docbook.org/ns/docbook"),("xmlns:xlink", "http://www.w3.org/1999/xlink")]

121 else []

126 else []

src/Text/Pandoc/Writers/LaTeX.hs+13−4

@@ -87,7 +87,8 @@ writeLaTeX options document =

87 stOptions = options, stVerbInNote = False,

88 stTable = False, stStrikeout = False,

89 stUrl = False, stGraphics = False,

90− stLHS = False, stBook = writerChapters options,

90+ stLHS = False,

91+ stBook = writerTopLevelDivision options < Section,

91 stCsquotes = False, stHighlighting = False,

92 stCsquotes = False, stHighlighting = False,

92 stIncremental = writerIncremental options,

93 stIncremental = writerIncremental options,

93 stInternalLinks = [], stUsesEuro = False }

94 stInternalLinks = [], stUsesEuro = False }

@@ -750,10 +751,18 @@ sectionHeader unnumbered ident level lst = do

750 <> braces (text plain))

751 <> braces (text plain))

751 book <- gets stBook

752 book <- gets stBook

752 opts <- gets stOptions

753 opts <- gets stOptions

754+ let topLevelDivision = min (if book then Chapter else Section)

755+ (writerTopLevelDivision opts)

756+ let level' = if writerBeamer opts && topLevelDivision < Section

757+ -- beamer has parts but no chapters

753− let level' = if book || writerChapters opts then level - 1 else level

758+ then if level == 1 then -1 else level - 1

759+ else case topLevelDivision of

760+ Part -> level - 2

761+ Chapter -> level - 1

762+ Section -> level

754 let sectionType = case level' of

763 let sectionType = case level' of

755− 0 | writerBeamer opts -> "part"

764+ -1 -> "part"

756− | otherwise -> "chapter"

765+ 0 -> "chapter"

757 1 -> "section"

766 1 -> "section"

758 2 -> "subsection"

767 2 -> "subsection"

759 3 -> "subsubsection"

768 3 -> "subsubsection"

src/Text/Pandoc/Writers/TEI.hs+11−10

@@ -35,7 +35,7 @@ import Text.Pandoc.Shared

35import Text.Pandoc.Writers.Shared

36import Text.Pandoc.Options

37import Text.Pandoc.Templates (renderTemplate')

38−import Data.List ( stripPrefix, isPrefixOf, isSuffixOf )

38+import Data.List ( stripPrefix, isPrefixOf )

39import Data.Char ( toLower )

40import Text.Pandoc.Highlighting ( languages, languagesByExtension )

41import Text.Pandoc.Pretty

@@ -60,19 +60,18 @@ writeTEI opts (Pandoc meta blocks) =

60 then Just $ writerColumns opts

61 else Nothing

62 render' = render colwidth

63− opts' = if "/book>" `isSuffixOf`

63+ startLvl = case writerTopLevelDivision opts of

64− (trimr $ writerTemplate opts)

64+ Part -> -1

65− then opts{ writerChapters = True }

65+ Chapter -> 0

66− else opts

66+ Section -> 1

67− startLvl = if writerChapters opts' then 0 else 1

68 auths' = map (authorToTEI opts) $ docAuthors meta

67 auths' = map (authorToTEI opts) $ docAuthors meta

69 meta' = B.setMeta "author" auths' meta

68 meta' = B.setMeta "author" auths' meta

70 Just metadata = metaToJSON opts

69 Just metadata = metaToJSON opts

71 (Just . render colwidth . (vcat .

70 (Just . render colwidth . (vcat .

72− (map (elementToTEI opts' startLvl)) . hierarchicalize))

71+ (map (elementToTEI opts startLvl)) . hierarchicalize))

73− (Just . render colwidth . inlinesToTEI opts')

72+ (Just . render colwidth . inlinesToTEI opts)

74 meta'

73 meta'

75− main = render' $ vcat (map (elementToTEI opts' startLvl) elements)

74+ main = render' $ vcat (map (elementToTEI opts startLvl) elements)

76 context = defField "body" main

75 context = defField "body" main

77 $ defField "mathml" (case writerHTMLMathMethod opts of

76 $ defField "mathml" (case writerHTMLMathMethod opts of

78 MathML _ -> True

77 MathML _ -> True

@@ -90,8 +89,10 @@ elementToTEI opts lvl (Sec _ _num (id',_,_) title elements) =

90 let elements' = if null elements

89 let elements' = if null elements

91 then [Blk (Para [])]

90 then [Blk (Para [])]

92 else elements

91 else elements

92+ -- level numbering correspond to LaTeX internals

93 divType = case lvl of

94+ n | n == -1 -> "part"

94− n | n == 0 -> "chapter"

95+ | n == 0 -> "chapter"

95 | n >= 1 && n <= 5 -> "level" ++ show n

96 | n >= 1 && n <= 5 -> "level" ++ show n

96 | otherwise -> "section"

97 | otherwise -> "section"

97 in inTags True "div" [("type", divType) | not (null id')] $

98 in inTags True "div" [("type", divType) | not (null id')] $

tests/Tests/Writers/Docbook.hs+56−1

@@ -8,7 +8,10 @@ import Tests.Helpers

8import Text.Pandoc.Arbitrary()

9

10docbook :: (ToPandoc a) => a -> String

11−docbook = writeDocbook def{ writerWrapText = WrapNone } . toPandoc

11+docbook = docbookWithOpts def{ writerWrapText = WrapNone }

12+

13+docbookWithOpts :: ToPandoc a => WriterOptions -> a -> String

14+docbookWithOpts opts = writeDocbook opts . toPandoc

12

15

13{-

16{-

14 "my test" =: X =?> Y

17 "my test" =: X =?> Y

@@ -226,4 +229,56 @@ tests = [ testGroup "line blocks"

226 ]

229 ]

227 ]

230 ]

228 ]

231 ]

232+ , testGroup "writer options" $

233+ [ testGroup "top-level division" $

234+ let

235+ headers = header 1 (text "header1")

236+ <> header 2 (text "header2")

237+ <> header 3 (text "header3")

238+

239+ docbookTopLevelDiv :: (ToPandoc a) => Division -> a -> String

240+ docbookTopLevelDiv division =

241+ docbookWithOpts def{ writerTopLevelDivision = division }

242+ in

243+ [ test (docbookTopLevelDiv Section) "sections as top-level" $ headers =?>

244+ unlines [ "<sect1>"

245+ , " <title>header1</title>"

246+ , " <sect2>"

247+ , " <title>header2</title>"

248+ , " <sect3>"

249+ , " <title>header3</title>"

250+ , " <para>"

251+ , " </para>"

252+ , " </sect3>"

253+ , " </sect2>"

254+ , "</sect1>"

255+ ]

256+ , test (docbookTopLevelDiv Chapter) "chapters as top-level" $ headers =?>

257+ unlines [ "<chapter>"

258+ , " <title>header1</title>"

259+ , " <sect1>"

260+ , " <title>header2</title>"

261+ , " <sect2>"

262+ , " <title>header3</title>"

263+ , " <para>"

264+ , " </para>"

265+ , " </sect2>"

266+ , " </sect1>"

267+ , "</chapter>"

268+ ]

269+ , test (docbookTopLevelDiv Part) "parts as top-level" $ headers =?>

270+ unlines [ "<part>"

271+ , " <title>header1</title>"

272+ , " <chapter>"

273+ , " <title>header2</title>"

274+ , " <sect1>"

275+ , " <title>header3</title>"

276+ , " <para>"

277+ , " </para>"

278+ , " </sect1>"

279+ , " </chapter>"

280+ , "</part>"

281+ ]

282+ ]

283+ ]

229 ]

284 ]

tests/Tests/Writers/LaTeX.hs+56−5

@@ -2,16 +2,19 @@

2module Tests.Writers.LaTeX (tests) where

3

4import Test.Framework

5−import Text.Pandoc.Builder

6−import Text.Pandoc

7import Tests.Helpers

5import Tests.Helpers

8−import Text.Pandoc.Arbitrary()

6+import Text.Pandoc

7+import Text.Pandoc.Arbitrary ()

8+import Text.Pandoc.Builder

9

10latex :: (ToPandoc a) => a -> String

11−latex = writeLaTeX def{ writerHighlight = True } . toPandoc

11+latex = latexWithOpts def{ writerHighlight = True }

12

13latexListing :: (ToPandoc a) => a -> String

14−latexListing = writeLaTeX def{ writerListings = True } . toPandoc

14+latexListing = latexWithOpts def{ writerListings = True }

15+

16+latexWithOpts :: (ToPandoc a) => WriterOptions -> a -> String

17+latexWithOpts opts = writeLaTeX opts . toPandoc

15

18

16{-

19{-

17 "my test" =: X =?> Y

20 "my test" =: X =?> Y

@@ -78,4 +81,52 @@ tests = [ testGroup "code blocks"

78 , "backtick" =:

81 , "backtick" =:

79 code "`nu?`" =?> "\\texttt{\\textasciigrave{}nu?\\textasciigrave{}}"

82 code "`nu?`" =?> "\\texttt{\\textasciigrave{}nu?\\textasciigrave{}}"

80 ]

83 ]

84+ , testGroup "writer options"

85+ [ testGroup "top-level division" $

86+ let

87+ headers = header 1 (text "header1")

88+ <> header 2 (text "header2")

89+ <> header 3 (text "header3")

90+

91+ latexTopLevelDiv :: (ToPandoc a) => Division -> a -> String

92+ latexTopLevelDiv division =

93+ latexWithOpts def{ writerTopLevelDivision = division }

94+

95+ beamerTopLevelDiv :: (ToPandoc a) => Division -> a -> String

96+ beamerTopLevelDiv division =

97+ latexWithOpts def { writerTopLevelDivision = division

98+ , writerBeamer = True }

99+ in

100+ [ test (latexTopLevelDiv Section) "sections as top-level" $ headers =?>

101+ unlines [ "\\section{header1}\n"

102+ , "\\subsection{header2}\n"

103+ , "\\subsubsection{header3}"

104+ ]

105+ , test (latexTopLevelDiv Chapter) "chapters as top-level" $ headers =?>

106+ unlines [ "\\chapter{header1}\n"

107+ , "\\section{header2}\n"

108+ , "\\subsection{header3}"

109+ ]

110+ , test (latexTopLevelDiv Part) "parts as top-level" $ headers =?>

111+ unlines [ "\\part{header1}\n"

112+ , "\\chapter{header2}\n"

113+ , "\\section{header3}"

114+ ]

115+ , test (beamerTopLevelDiv Section) "sections as top-level in beamer" $ headers =?>

116+ unlines [ "\\section{header1}\n"

117+ , "\\subsection{header2}\n"

118+ , "\\subsubsection{header3}"

119+ ]

120+ , test (beamerTopLevelDiv Chapter) "chapters are as part in beamer" $ headers =?>

121+ unlines [ "\\part{header1}\n"

122+ , "\\section{header2}\n"

123+ , "\\subsection{header3}"

124+ ]

125+ , test (beamerTopLevelDiv Part) "parts as top-level in beamer" $ headers =?>

126+ unlines [ "\\part{header1}\n"

127+ , "\\section{header2}\n"

128+ , "\\subsection{header3}"

129+ ]

130+ ]

131+ ]

81 ]

132 ]