journal: clarify that txn/posting comments must start with semicolon

hledger-lib/Hledger/Read/Common.hs

@@ -610,15 +610,15 @@ multilinecommentp = do
 
 emptyorcommentlinep :: JournalParser m ()
 emptyorcommentlinep = do
-  lift (many spacenonewline) >> (commentp <|> (lift (many spacenonewline) >> newline >> return ""))
+  lift (many spacenonewline) >> (linecommentp <|> (lift (many spacenonewline) >> newline >> return ""))
   return ()
 
 -- | Parse a possibly multi-line comment following a semicolon.
 followingcommentp :: JournalParser m Text
 followingcommentp =
   -- ptrace "followingcommentp"
-  do samelinecomment <- lift (many spacenonewline) >> (try semicoloncommentp <|> (newline >> return ""))
-     newlinecomments <- many (try (lift (some spacenonewline) >> semicoloncommentp))
+  do samelinecomment <- lift (many spacenonewline) >> (try commentp <|> (newline >> return ""))
+     newlinecomments <- many (try (lift (some spacenonewline) >> commentp))
      return $ T.unlines $ samelinecomment:newlinecomments
 
 -- | Parse a possibly multi-line comment following a semicolon, and
@@ -650,10 +650,10 @@ followingcommentandtagsp mdefdate = do
   -- to get good error positions.
   startpos <- getPosition
   commentandwhitespace :: String <- do
-    let semicoloncommentp' = (:) <$> char ';' <*> anyChar `manyTill` eolof
+    let commentp' = (:) <$> char ';' <*> anyChar `manyTill` eolof
     sp1 <- lift (many spacenonewline)
-    l1  <- try (lift semicoloncommentp') <|> (newline >> return "")
-    ls  <- lift . many $ try ((++) <$> some spacenonewline <*> semicoloncommentp')
+    l1  <- try (lift commentp') <|> (newline >> return "")
+    ls  <- lift . many $ try ((++) <$> some spacenonewline <*> commentp')
     return $ unlines $ (sp1 ++ l1) : ls
   let comment = T.pack $ unlines $ map (lstrip . dropWhile (==';') . strip) $ lines commentandwhitespace
   -- pdbg 0 $ "commentws:"++show commentandwhitespace
@@ -676,14 +676,15 @@ followingcommentandtagsp mdefdate = do
 
   return (comment, tags, mdate, mdate2)
 
+-- A transaction/posting comment must start with a semicolon.
+-- This parser ignores leading whitespace.
 commentp :: JournalParser m Text
-commentp = commentStartingWithp commentchars
+commentp = commentStartingWithp ";"
 
-commentchars :: [Char]
-commentchars = "#;*"
-
-semicoloncommentp :: JournalParser m Text
-semicoloncommentp = commentStartingWithp ";"
+-- A line (file-level) comment can start with a semicolon, hash,
+-- or star (allowing org nodes). This parser ignores leading whitespace.
+linecommentp :: JournalParser m Text
+linecommentp = commentStartingWithp ";#*" 
 
 commentStartingWithp :: [Char] -> JournalParser m Text
 commentStartingWithp cs = do

hledger-lib/doc/hledger_journal.5.m4.md

@@ -541,8 +541,9 @@ P 2010/1/1 € $1.40
 ## Comments
 
 Lines in the journal beginning with a semicolon (`;`) or hash (`#`) or
-asterisk (`*`) are comments, and will be ignored. (Asterisk comments
-make it easy to treat your journal like an org-mode outline in emacs.)
+star (`*`) are comments, and will be ignored. (Star comments cause
+org-mode nodes to be ignored, allowing emacs users to fold and navigate
+their journals with org-mode or orgstruct-mode.)
 
 Also, anything between [`comment` and `end comment` directives](#multi-line-comments) is a (multi-line) comment.
 If there is no `end comment`, the comment extends to the end of the file.
@@ -551,20 +552,21 @@ You can attach comments to a transaction by writing them after the
 description and/or indented on the following lines (before the
 postings).  Similarly, you can attach comments to an individual
 posting by writing them after the amount and/or indented on the
-following lines.
+following lines. 
+Transaction and posting comments must begin with a semicolon (`;`).
 
 Some examples:
 
 ```journal
-# a journal comment
+# a file comment
 
-; also a journal comment
+; also a file comment
 
 comment
-This is a multiline comment,
+This is a multiline file comment,
 which continues until a line
 where the "end comment" string
-appears on its own.
+appears on its own (or end of file).
 end comment
 
 2012/5/14 something  ; a transaction comment
@@ -573,7 +575,7 @@ end comment
     posting2
     ; a comment for posting 2
     ; another comment line for posting 2
-; a journal comment (because not indented)
+; a file comment (because not indented)
 ```
 
 ## Tags

tests/journal/comments.test

@@ -1,78 +1,56 @@
 # comment tests
 
-# 1. 
+# 1. several comment characters allowed for file characters; 
+# print shows in-transaction & posting comments;
+# comment line is preserved, starting column is not.
 hledger -f - print
 <<<
-2009/01/01 x
-    ; transaction comment 1
-    ; transaction comment 2
-    a  1
-    b
->>>
-2009/01/01 x
-    ; transaction comment 1
-    ; transaction comment 2
-    a               1
-    b
+; file comments, ignored
+# file comment using a hash
+* file comment using a star (org node)
+ ; file comments need not
+ # start in
+ * column 0
 
->>>=0
-
-# 2. 
-hledger -f - print
-<<<
-2009/01/01 x
-    a  1
-    b
-; comment line after postings
->>>
-2009/01/01 x
-    a               1
-    b
-
->>>=0
-
-# 3. print should preserve transaction (entry) comments and which line they're on
-hledger -f - print
-<<<
-; leading journal comment, not preserved
-
-; transaction preceding comment, not preserved
+; pre-transaction comment, ignored
 2009/1/1 x ; transaction same line comment
-    ; transaction new line comment
+      ; transaction new line comment
     a  1    ; posting 1 same line comment
     ; posting 1 new line comment
-    b
+    a
       ; posting 2 new line comment
-; journal comment right after the transaction, not preserved
+; file comment right after the transaction, ignored
 
-; trailing journal comment, not preserved
+; trailing file comment, ignored
 >>>
 2009/01/01 x    ; transaction same line comment
     ; transaction new line comment
     a               1    ; posting 1 same line comment
     ; posting 1 new line comment
-    b
+    a
     ; posting 2 new line comment
 
 >>>2
 >>>=0
 
-# 4. a posting comment should appear in print
+# 2. transaction comments must use ;
 hledger -f - print
 <<<
-2010/01/01 x
-    a               1    ; comment
-    b              -1
-
+2017/1/1 this # and * are not ; the comment
 >>>
-2010/01/01 x
-    a               1    ; comment
-    b              -1
+2017/01/01 this # and * are not    ; the comment
 
 >>>2
 >>>=0
 
-# 5. a posting comment should not appear in register
+# 3. posting comments must use ;
+hledger -f - print
+<<<
+2017/1/1
+  a  0  # hash & star not allowed for posting comments
+>>>=1
+
+# 4. register does not show comments
 hledger -f - register
 <<<
 2010/1/1 x
@@ -84,3 +62,4 @@ hledger -f - register
                                 b                               -1             0
 >>>2
 >>>=0
+