1da40d6 · typeable/pandoc

MANUAL.txt+13−5

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

661661

662662`--chapters`

663663

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

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

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

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

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

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

665+

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

667+

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

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

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

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

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.

669677

670678`-N`, `--number-sections`

671679

pandoc.hs+15−5

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

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

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

185185 , 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

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

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

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

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

248248 , optHtmlQTags = False

249249 , optHighlight = True

250250 , optHighlightStyle = pygments

251− , optChapters = False

251+ , optTopLevelDivision = Section

252252 , optHTMLMathMethod = PlainMath

253253 , optReferenceODT = Nothing

254254 , optReferenceDocx = Nothing

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

606606

607607 , Option "" ["chapters"]

608608 (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 }))

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

611613

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+

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

613623 (NoArg

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

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

11221132 , optHtmlQTags = htmlQTags

11231133 , optHighlight = highlight

11241134 , optHighlightStyle = highlightStyle

1125− , optChapters = chapters

1135+ , optTopLevelDivision = topLevelDivision

11261136 , optHTMLMathMethod = mathMethod'

11271137 , optReferenceODT = referenceODT

11281138 , optReferenceDocx = referenceDocx

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

13861396 writerUserDataDir = datadir,

13871397 writerHtml5 = html5,

13881398 writerHtmlQTags = htmlQTags,

1389− writerChapters = chapters,

1399+ writerTopLevelDivision = topLevelDivision,

13901400 writerListings = listings,

13911401 writerBeamer = False,

13921402 writerSlideLevel = slideLevel,

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

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

4343 , HTMLSlideVariant (..)

4444 , EPUBVersion (..)

4545 , WrapOption (..)

46+ , Division (..)

4647 , WriterOptions (..)

4748 , TrackChanges (..)

4849 , ReferenceLocation (..)

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

337338 | WrapPreserve -- ^ Preserve wrapping of input source

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

339340

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+

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

341348data ReferenceLocation = EndOfBlock -- ^ End of block

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

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

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

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

375382 , 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

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

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

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

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

421428 , writerHtmlQTags = False

422429 , writerBeamer = False

423430 , writerSlideLevel = Nothing

424− , writerChapters = False

431+ , writerTopLevelDivision = Section

425432 , writerListings = False

426433 , writerHighlight = False

427434 , writerHighlightStyle = pygments

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

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

8383 ]

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

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

86− take (writerTOCDepth options + if writerChapters options

87− then 0

88− else 1)

86+ take (writerTOCDepth options +

87+ if writerTopLevelDivision options < Section

88+ then 0

89+ else 1)

8990 ["chapter","section","subsection","subsubsection",

9091 "subsubsubsection","subsubsubsubsection"])

9192 $ defField "body" main

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

412413 Nothing -> txt

413414 fmap (wrapLang . wrapDir) $ inlineListToConTeXt ils

414415

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

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

416417sectionHeader :: Attr

417418 -> Int

418419 -> [Inline]

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

421422 contents <- inlineListToConTeXt lst

422423 st <- get

423424 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

425429 let ident' = toLabel ident

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

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

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

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

430− then char '\\'

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

432− <> section

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

434− <> braces contents

435− <> blankline

436− else if level' == 0

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

438− else contents <> blankline

433+ return $ case level' of

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

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

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

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

438+ <> section

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

440+ then brackets (text ident')

441+ else empty)

442+ <> braces contents

443+ <> blankline

444+ _ -> contents <> blankline

439445

440446fromBcp47' :: String -> String

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

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

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

7979 colwidth = if writerWrapText opts == WrapAuto

8080 then Just $ writerColumns opts

8181 else Nothing

82− render' = render colwidth

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

84− (trimr $ writerTemplate opts)

85− then opts{ writerChapters = True }

86− else opts

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

82+ render' = render colwidth

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

84+ writerTopLevelDivision opts >= Section)

85+ then opts{ writerTopLevelDivision = Chapter }

86+ else opts

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

88+ startLvl = case writerTopLevelDivision opts' of

89+ Part -> -1

90+ Chapter -> 0

91+ Section -> 1

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

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

9094 Just metadata = metaToJSON opts

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

111115 then [Blk (Para [])]

112116 else elements

113117 tag = case lvl of

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

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

118+ -1 -> "part"

119+ 0 -> "chapter"

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

116121 then "section"

117122 else "sect" ++ show n

118− | otherwise -> "simplesect"

123+ _ -> "simplesect"

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

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

121126 else []

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

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

8787 stOptions = options, stVerbInNote = False,

8888 stTable = False, stStrikeout = False,

8989 stUrl = False, stGraphics = False,

90− stLHS = False, stBook = writerChapters options,

90+ stLHS = False,

91+ stBook = writerTopLevelDivision options < Section,

9192 stCsquotes = False, stHighlighting = False,

9293 stIncremental = writerIncremental options,

9394 stInternalLinks = [], stUsesEuro = False }

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

750751 <> braces (text plain))

751752 book <- gets stBook

752753 opts <- gets stOptions

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

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

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

754763 let sectionType = case level' of

755− 0 | writerBeamer opts -> "part"

756− | otherwise -> "chapter"

764+ -1 -> "part"

765+ 0 -> "chapter"

757766 1 -> "section"

758767 2 -> "subsection"

759768 3 -> "subsubsection"

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

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

3535import Text.Pandoc.Writers.Shared

3636import Text.Pandoc.Options

3737import Text.Pandoc.Templates (renderTemplate')

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

38+import Data.List ( stripPrefix, isPrefixOf )

3939import Data.Char ( toLower )

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

4141import Text.Pandoc.Pretty

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

6060 then Just $ writerColumns opts

6161 else Nothing

6262 render' = render colwidth

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

64− (trimr $ writerTemplate opts)

65− then opts{ writerChapters = True }

66− else opts

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

63+ startLvl = case writerTopLevelDivision opts of

64+ Part -> -1

65+ Chapter -> 0

66+ Section -> 1

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

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

7069 Just metadata = metaToJSON opts

7170 (Just . render colwidth . (vcat .

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

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

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

72+ (Just . render colwidth . inlinesToTEI opts)

7473 meta'

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

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

7675 context = defField "body" main

7776 $ defField "mathml" (case writerHTMLMathMethod opts of

7877 MathML _ -> True

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

9089 let elements' = if null elements

9190 then [Blk (Para [])]

9291 else elements

92+ -- level numbering correspond to LaTeX internals

9393 divType = case lvl of

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

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

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

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

9697 | otherwise -> "section"

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

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

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

88import Text.Pandoc.Arbitrary()

99

1010docbook :: (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

1215

1316{-

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

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

226229 ]

227230 ]

228231 ]

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+ ]

229284 ]

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

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

22module Tests.Writers.LaTeX (tests) where

33

44import Test.Framework

5−import Text.Pandoc.Builder

6−import Text.Pandoc

75import Tests.Helpers

8−import Text.Pandoc.Arbitrary()

6+import Text.Pandoc

7+import Text.Pandoc.Arbitrary ()

8+import Text.Pandoc.Builder

99

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

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

11+latex = latexWithOpts def{ writerHighlight = True }

1212

1313latexListing :: (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

1518

1619{-

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

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

7881 , "backtick" =:

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

8083 ]

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+ ]

81132 ]