Re: Comment conventions, adding an explicit Header.

[phillip.lord@newcastle.ac.uk (Phillip Lord)]

Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> True. Currently, I handle the first line specially (as does emacs)
>> because otherwise you end up with level 1 header with, for example, the
>> lexical-binding instruction in it.
>
> outline-minor-mode doesn't handle it specially.  I don't mind having the
> lexical-binding thingy in there, since it means that when the file
> "fully folded" I can still immediately know whether the file is using
> lexical-binding or not.

This is true. Likewise, the same is true with the summary. Of course,
you can still see this in the org mode file, and it never folds. But as
a comment, it will not get rendered to any output.

It's not ideal, but I wanted to get something working, to see if it
makes sense first.

>> Also, in the org-mode transformation I translate this into a org-mode
>> comment.  The reason for this is that org-mode also has a "start of file"
>> semantics -- the lines before the first header is special.
>
> Not knowing what this "special" implies, it's hard to judge whether it's
> important.

I'm not a high-power org-mode user either, am afraid, so it's hard for
me to judge too. Things defined before the start, generally apply to the
whole document, so things like new "drawers" are defined here, or
keywords for TODO boxes.

Likewise, titles for output, latex headers and so on.



> The few files that use ";;;" for sectioning *within* the code itself
> don't seem to use "single word with a colon" very much.  E.g. a quick
> grep shows things like:
>
> lisp/wid-edit.el:;;; Utility functions.
> lisp/wid-edit.el:;;; Widget text specifications.
> lisp/wid-edit.el:;;; Widget Properties.
> lisp/view.el:;;; Commands that enter or exit view mode.
> lisp/view.el:;;; Some help routines.
> lisp/view.el:;;; Commands for moving around in the buffer.
> lisp/vc/ediff-util.el:;;; Build keymaps
> lisp/vc/ediff-util.el:;;; Setup functions
> lisp/vc/ediff-util.el:;;; Commands for working with Ediff
> lisp/vc/ediff-util.el:;;; Copying diffs.


Indeed. These will not currently be treated as sections. I could make
them so. In practice, files do need modifying to work with my code. Most
obviously, org-mode needs all the code blocks to be marked up.
I have been doing this by marking ALL of the file after the header,
and then splitting the org code blocks later. I fix sectioning as I go.

All good feedback. Can I conclude that so far there would be no show
stopping problem with adding a ";;; Header:" line where it was wanted?

Phil