Markdown writer: default to using ATX headings.

Previously we used Setext (underlined) headings by default.
The default is now ATX (`##` style).

* Add the `--markdown-headings=atx|setext` option.
* Deprecate `--atx-headers`.
* Add constructor 'ATXHeadingInLHS` constructor to `LogMessage` [API change].
* Support `markdown-headings` in defaults files.
* Document new options in MANUAL.

Closes #6662.

1 files changed, 49 insertions, 36 deletions

diff --git a/src/Text/Pandoc/Logging.hs b/src/Text/Pandoc/Logging.hs
index 5c9330b7b..825fdaadb 100644
--- a/src/Text/Pandoc/Logging.hs
+++ b/src/Text/Pandoc/Logging.hs
@@ -31,6 +31,7 @@ import Data.Aeson.Encode.Pretty (Config (..), defConfig, encodePretty',
 import qualified Data.ByteString.Lazy as BL
 import Data.Data (Data, toConstr)
 import qualified Data.Text as Text
+import Data.Text (Text)
 import Data.Typeable (Typeable)
 import GHC.Generics (Generic)
 import Text.Pandoc.Definition
@@ -59,45 +60,46 @@ instance FromYAML Verbosity where
          _         -> mzero
 
 data LogMessage =
-    SkippedContent Text.Text SourcePos
-  | IgnoredElement Text.Text
-  | DuplicateLinkReference Text.Text SourcePos
-  | DuplicateNoteReference Text.Text SourcePos
-  | NoteDefinedButNotUsed Text.Text SourcePos
-  | DuplicateIdentifier Text.Text SourcePos
-  | ReferenceNotFound Text.Text SourcePos
-  | CircularReference Text.Text SourcePos
-  | UndefinedToggle Text.Text SourcePos
-  | ParsingUnescaped Text.Text SourcePos
-  | CouldNotLoadIncludeFile Text.Text SourcePos
-  | MacroAlreadyDefined Text.Text SourcePos
+    SkippedContent Text SourcePos
+  | IgnoredElement Text
+  | DuplicateLinkReference Text SourcePos
+  | DuplicateNoteReference Text SourcePos
+  | NoteDefinedButNotUsed Text SourcePos
+  | DuplicateIdentifier Text SourcePos
+  | ReferenceNotFound Text SourcePos
+  | CircularReference Text SourcePos
+  | UndefinedToggle Text SourcePos
+  | ParsingUnescaped Text SourcePos
+  | CouldNotLoadIncludeFile Text SourcePos
+  | MacroAlreadyDefined Text SourcePos
   | InlineNotRendered Inline
   | BlockNotRendered Block
-  | DocxParserWarning Text.Text
-  | IgnoredIOError Text.Text
-  | CouldNotFetchResource Text.Text Text.Text
-  | CouldNotDetermineImageSize Text.Text Text.Text
-  | CouldNotConvertImage Text.Text Text.Text
-  | CouldNotDetermineMimeType Text.Text
-  | CouldNotConvertTeXMath Text.Text Text.Text
-  | CouldNotParseCSS Text.Text
-  | Fetching Text.Text
-  | Extracting Text.Text
-  | NoTitleElement Text.Text
+  | DocxParserWarning Text
+  | IgnoredIOError Text
+  | CouldNotFetchResource Text Text
+  | CouldNotDetermineImageSize Text Text
+  | CouldNotConvertImage Text Text
+  | CouldNotDetermineMimeType Text
+  | CouldNotConvertTeXMath Text Text
+  | CouldNotParseCSS Text
+  | Fetching Text
+  | Extracting Text
+  | NoTitleElement Text
   | NoLangSpecified
-  | InvalidLang Text.Text
-  | CouldNotHighlight Text.Text
-  | MissingCharacter Text.Text
-  | Deprecated Text.Text Text.Text
-  | NoTranslation Text.Text
-  | CouldNotLoadTranslations Text.Text Text.Text
-  | UnusualConversion Text.Text
-  | UnexpectedXmlElement Text.Text Text.Text
-  | UnknownOrgExportOption Text.Text
-  | CouldNotDeduceFormat [Text.Text] Text.Text
+  | InvalidLang Text
+  | CouldNotHighlight Text
+  | MissingCharacter Text
+  | Deprecated Text Text
+  | NoTranslation Text
+  | CouldNotLoadTranslations Text Text
+  | UnusualConversion Text
+  | UnexpectedXmlElement Text Text
+  | UnknownOrgExportOption Text
+  | CouldNotDeduceFormat [Text] Text
   | RunningFilter FilePath
   | FilterCompleted FilePath Integer
-  | CiteprocWarning Text.Text
+  | CiteprocWarning Text
+  | ATXHeadingInLHS Int Text
   deriving (Show, Eq, Data, Ord, Typeable, Generic)
 
 instance ToJSON LogMessage where
@@ -224,8 +226,11 @@ instance ToJSON LogMessage where
            ,"milliseconds" .= Text.pack (show ms) ]
       CiteprocWarning msg ->
            ["message" .= msg]
+      ATXHeadingInLHS lvl contents ->
+           ["level" .= lvl
+           ,"contents" .= contents]
 
-showPos :: SourcePos -> Text.Text
+showPos :: SourcePos -> Text
 showPos pos = Text.pack $ sn ++ "line " ++
      show (sourceLine pos) ++ " column " ++ show (sourceColumn pos)
   where sn = if sourceName pos == "source" || sourceName pos == ""
@@ -238,7 +243,7 @@ encodeLogMessages ms =
       keyOrder [ "type", "verbosity", "contents", "message", "path",
                  "source", "line", "column" ] } ms
 
-showLogMessage :: LogMessage -> Text.Text
+showLogMessage :: LogMessage -> Text
 showLogMessage msg =
   case msg of
        SkippedContent s pos ->
@@ -333,6 +338,13 @@ showLogMessage msg =
        FilterCompleted fp ms -> "Completed filter " <> Text.pack fp <>
           " in " <> Text.pack (show ms) <> " ms"
        CiteprocWarning ms -> "Citeproc: " <> ms
+       ATXHeadingInLHS lvl contents ->
+         "Rendering heading '" <> contents <> "' as a paragraph.\n" <>
+         "ATX headings cannot be used in literate Haskell, because " <>
+         "'#' is not\nallowed in column 1." <>
+         if lvl < 3
+            then " Consider using --markdown-headings=setext."
+            else ""
 
 messageVerbosity :: LogMessage -> Verbosity
 messageVerbosity msg =
@@ -378,3 +390,4 @@ messageVerbosity msg =
        RunningFilter{}               -> INFO
        FilterCompleted{}             -> INFO
        CiteprocWarning{}             -> WARNING
+       ATXHeadingInLHS{}             -> WARNING