Feature request: make heading symbol customizable

[meditans]

It would be nice to be able to customize the symbol that marks a heading, because the default sometimes conflicts with established conventions for programming languages.

For example, in Haskell, line comments begin with --, but the special syntax -- * is reserved for special comment that will be used by the documentation tool to decide the layout of the generated HTML documentation. So when using outorg, the documentation exporter can't be used.

This problem would be averted if one could customize the symbol indicating org-like comments, after the normal comment prefix. For example, choosing -- % or -- - as prefixes in the Haskell case wouldn't conflict with any preexisting convention.

One would indicate the org-like headings with -- %, -- %%..., and the chosen symbol would be converted to the usual *, **... org-mode syntax when using outorg-edit-as-org and back when using outorg-copy-edits-and-exit.

[tj64]

Hi. I think you can do this already in outshine:

(defcustom outshine-regexp-base-char "*" "Character used in outline-regexp base." :group 'outshine :type 'string)

but this may of course have side-effects in other major-modes. Maybe try to set this as file local variable in your Haskell files.

Outshine must be generic, the only real exception is oldshool Elisp headers (;;; 1st level). It should work for all major modes, but there are special cases like this that must be considered separateley (e.g. R had a few of them).

Let me know if this outshine custom helps.

[meditans]

Thanks, this solution is very good for outshine, I'm now using '(outshine-regexp-base-char "@") in custom-set-variables. However I still have problems when trying to use out-org; for example, the haskell file:

-- @ Header

-- Some text
module Lib (someFunc) where

-- | This is a haddock comment
someFunc :: IO ()
someFunc = putStrLn "someFunc"

produces, when I use outorg-edit-as-org the file:

@ Header

Some text
#+begin_src haskell
module Lib (someFunc) where
#+end_src

| This is a haddock comment
#+begin_src haskell
someFunc :: IO ()
someFunc = putStrLn "someFunc"
#+end_src

The main problem here is that org-mode expects * Header instead of @ Header to be able to work properly. Could this translation happen automatically, especially since the value of outshine-regexp-base-char can be queried?

An ancillary point, though probably more difficult and overall not as important as the first one, might be having the haddock comment inside the source block, like in:

@ Header

Some text
#+begin_src haskell
module Lib (someFunc) where
#+end_src

#+begin_src haskell
-- | This is a haddock comment
someFunc :: IO ()
someFunc = putStrLn "someFunc"
#+end_src

What do you think about these issues?

[meditans]

Sorry @tj64, I forgot to ping you! :)

[tj64]

Hi, conversion to outorg with customizable base-char should be doable, maybe this weekend.
I don't know what an Haddock comment is, whats the advantage of having it inside the source block? Are they always located directly on top of source, or might there be blank lines or other comments in between? Would a Haddock comment on its own in a source block be any useful?

[tj64]

you see, I completely forgot about the outshine thread about Haddock comments ;-)

[langston-barrett]

I would also be interested in this feature. Normally, Haddock comments immediately proceed definitions, as in

-- | This is an explanation of what foo does
foo :: bar
foo = doSomething

There are also module-level haddock comments. It's a lot like javadoc or doxygen, if you're familiar.

I think it'd be good to put haddock comments on functions inside the src block, since they have their own (non-org) syntax.