outline-minor-mode heading levels in C, C++, and html

outline-minor-mode heading levels in C, C++, and html

[Heime]

How does one include outline-minor-mode heading levels in C and C++.

And how about html ?

Re: outline-minor-mode heading levels in C, C++, and html

[Joel Reicher]

Heime <heimeborgia@protonmail.com> writes:

> How does one include outline-minor-mode heading levels in C and 
> C++.
>
> And how about html ?

Do you mean how do you configure outline-minor-mode to activate 
automatically for the C, C++, and HTML major modes, or do you mean 
you are not seeing headings you want to see?

Regards,

        - Joel

Re: outline-minor-mode heading levels in C, C++, and html

[Heime]

Sent with Proton Mail secure email.

On Wednesday, August 14th, 2024 at 11:53 PM, Joel Reicher <joel.reicher@gmail.com> wrote:

> Heime heimeborgia@protonmail.com writes:
> 
> > How does one include outline-minor-mode heading levels in C and
> > C++.
> > 
> > And how about html ?
> 
> 
> Do you mean how do you configure outline-minor-mode to activate
> automatically for the C, C++, and HTML major modes, or do you mean
> you are not seeing headings you want to see? - Joel

In elisp one uses

;;; Level 1 Heading
;;;; Level 2 Heading
;;;;; Level 3 Heading

What does one use for the aforementioned major-modes to do the same ?

Re: outline-minor-mode heading levels in C, C++, and html

[Yuri Khan]

On Wed, 14 Aug 2024 at 20:59, Heime <heimeborgia@protonmail.com> wrote:

> In elisp one uses
>
> ;;; Level 1 Heading
> ;;;; Level 2 Heading
> ;;;;; Level 3 Heading
>
> What does one use for the aforementioned major-modes to do the same ?

That would be a decision for the project maintainer to make. If you
are lucky to work on a project in C or C++ whose code style is
tailored for Emacs users.

In C++ or C that allows line comments //, I would use ///, //// and
further. If the project reserves /// for documentation comments, then
start with //// for headings.

In C that insists on /* */ comments only, /** would be for doc
comments and /*** and further free for headings.

In HTML, I’d be tempted to use natural headings <h1> <h2> and so on.

These are only examples; other people might choose different heading
styles. Like they might say “our dominant IDE uses #pragma
region/#pragma endregion for code folding”.

Re: outline-minor-mode heading levels in C, C++, and html

[Heime]

On Thursday, August 15th, 2024 at 4:45 AM, Yuri Khan <yuri.v.khan@gmail.com> wrote:

> On Wed, 14 Aug 2024 at 20:59, Heime heimeborgia@protonmail.com wrote:
> 
> > In elisp one uses
> > 
> > ;;; Level 1 Heading
> > ;;;; Level 2 Heading
> > ;;;;; Level 3 Heading
> > 
> > What does one use for the aforementioned major-modes to do the same ?
> 
> 
> That would be a decision for the project maintainer to make. If you
> are lucky to work on a project in C or C++ whose code style is
> tailored for Emacs users.
> 
> In C++ or C that allows line comments //, I would use ///, //// and
> further. If the project reserves /// for documentation comments, then
> start with //// for headings.
> 
> In C that insists on /* / comments only, /* would be for doc
> comments and /*** and further free for headings.
> 
> In HTML, I’d be tempted to use natural headings <h1> <h2> and so on.
> 
> 
> These are only examples; other people might choose different heading
> styles. Like they might say “our dominant IDE uses #pragma
> region/#pragma endregion for code folding”.

What does emacs outline-minor-mode automatically apply for declaring headings
in C++, C and Html modes ?

Re: outline-minor-mode heading levels in C, C++, and html

[Yuri Khan]

On Wed, 14 Aug 2024 at 23:55, Heime <heimeborgia@protonmail.com> wrote:

> What does emacs outline-minor-mode automatically apply for declaring headings
> in C++, C and Html modes ?

Does it though?

Re: outline-minor-mode heading levels in C, C++, and html

[Heime]

Sent with Proton Mail secure email.

On Thursday, August 15th, 2024 at 6:08 AM, Yuri Khan <yuri.v.khan@gmail.com> wrote:

> On Wed, 14 Aug 2024 at 23:55, Heime heimeborgia@protonmail.com wrote:
> 
> > What does emacs outline-minor-mode automatically apply for declaring headings
> > in C++, C and Html modes ?
> 
> 
> Does it though?

Does it or does it not ???

Re: outline-minor-mode heading levels in C, C++, and html

[Joel Reicher]

Heime <heimeborgia@protonmail.com> writes:

> In elisp one uses
>
> ;;; Level 1 Heading
> ;;;; Level 2 Heading
> ;;;;; Level 3 Heading

This is common, but not universal, and is not part of elisp.

For example advice.el in my Emacs installation has this:


;; @ Overview, or how to read this file: 
;; ===================================== You can use 
;; `outline-mode' to help you read this documentation (set 
;; `outline-regexp' to `";; @+"'). 


You can see that very section of comments uses the alternative 
convention that it describes, and that's the important point: it's 
a *convention*.

One way you might be able to see the convention in use (if any) by 
a particular mode, or file local or directory local variables, is 
to check the value of outline-regexp from a buffer with the file 
and mode you're interested in.

Regards,

        - Joel

Re: outline-minor-mode heading levels in C, C++, and html

[Joel Reicher]

Re-sending with some fixed formatting. Sorry about that.

Joel Reicher <joel.reicher@gmail.com> writes:

> Heime <heimeborgia@protonmail.com> writes:
>
>> In elisp one uses
>>
>> ;;; Level 1 Heading
>> ;;;; Level 2 Heading
>> ;;;;; Level 3 Heading
>
> This is common, but not universal, and is not part of elisp.
>
> For example advice.el in my Emacs installation has this:
>
>
> ;; @ Overview, or how to read this file:
> ;; =====================================
> ;;  You can use `outline-mode' to help you read this 
> documentation (set
> ;; `outline-regexp' to `";; @+"').
>
>
> You can see that very section of comments uses the alternative 
> convention that it describes, and that's the important point: 
> it's  a *convention*.
>
> One way you might be able to see the convention in use (if any) 
> by  a particular mode, or file local or directory local 
> variables, is  to check the value of outline-regexp from a 
> buffer with the file  and mode you're interested in.
>
> Regards,
>
>         - Joel

Re: outline-minor-mode heading levels in C, C++, and html

[Heime]

On Friday, August 16th, 2024 at 12:34 AM, Joel Reicher <joel.reicher@gmail.com> wrote:

> Heime heimeborgia@protonmail.com writes:
> 
> > In elisp one uses
> > 
> > ;;; Level 1 Heading
> > ;;;; Level 2 Heading
> > ;;;;; Level 3 Heading
> 
> 
> This is common, but not universal, and is not part of elisp.

Is it the default embedded in outline-minor-mode ?  I do understand that
the heading patterns are modified by some projects.  But I am only looking
at what outline-minor-mode does.
 
> For example advice.el in my Emacs installation has this:
> 
> 
> ;; @ Overview, or how to read this file:
> ;; ===================================== You can use
> ;; `outline-mode' to help you read this documentation (set ;;` outline-regexp' to `";; @+"').
> 
> 
> You can see that very section of comments uses the alternative
> convention that it describes, and that's the important point: it's
> a convention.
> 
> One way you might be able to see the convention in use (if any) by
> a particular mode, or file local or directory local variables, is
> to check the value of outline-regexp from a buffer with the file
> and mode you're interested in.
> 
> Regards,
> 
> - Joel

Re: outline-minor-mode heading levels in C, C++, and html

[Joel Reicher]

Heime <heimeborgia@protonmail.com> writes:

> On Friday, August 16th, 2024 at 12:34 AM, Joel Reicher 
> <joel.reicher@gmail.com> wrote:
>
>> Heime heimeborgia@protonmail.com writes:
>>
>>> In elisp one uses
>>>
>>> ;;; Level 1 Heading
>>> ;;;; Level 2 Heading
>>> ;;;;; Level 3 Heading
>>
>> This is common, but not universal, and is not part of elisp.
>
> Is it the default embedded in outline-minor-mode ?

No, it isn't.

> I do understand that the heading patterns are modified by some 
> projects.  But I am only looking at what outline-minor-mode 
> does.

Outline minor mode provides an abstraction that needs to be 
implemented by the major mode in use.

The outline-regexp variable is a large part of that abstraction, 
which is why I've tried to direct your attention to it. If and 
when a major mode sets that to a sensible value, it is providing 
the implementation for outline-minor-mode that would otherwise be 
missing.

Not default. Missing.

Regards,

        - Joel

Re: outline-minor-mode heading levels in C, C++, and html

[Heime]

On Friday, August 16th, 2024 at 12:05 PM, Joel Reicher <joel.reicher@gmail.com> wrote:

> Heime heimeborgia@protonmail.com writes:
> 
> > On Friday, August 16th, 2024 at 12:34 AM, Joel Reicher
> > joel.reicher@gmail.com wrote:
> > 
> > > Heime heimeborgia@protonmail.com writes:
> > > 
> > > > In elisp one uses
> > > > 
> > > > ;;; Level 1 Heading
> > > > ;;;; Level 2 Heading
> > > > ;;;;; Level 3 Heading
> > > 
> > > This is common, but not universal, and is not part of elisp.
> > 
> > Is it the default embedded in outline-minor-mode ?
> 
> 
> No, it isn't.
> 
> > I do understand that the heading patterns are modified by some
> > projects. But I am only looking at what outline-minor-mode
> > does.
> 
> 
> Outline minor mode provides an abstraction that needs to be
> implemented by the major mode in use.
> 
> The outline-regexp variable is a large part of that abstraction,
> which is why I've tried to direct your attention to it. If and
> when a major mode sets that to a sensible value, it is providing
> the implementation for outline-minor-mode that would otherwise be
> missing.
> 
> Not default. Missing. - Joel

When I do "emacs -Q" and switch "outline-minor-mode" in an elisp buffer,
I do get the headings ";;;", ";;;;" automatically.

However you said that it is the "emacs-lisp-mode" that is setting
"outline-regexp" and "outline-heading-alist", not "outline-minor-mode".

Ok.  I thought that "outline-minor-mode" had defaults for various major
modes.  We could check so that the major programming languages and
others would have them defined with something.  Because it is not so
easy to change them when they are not set up.  Have had significant
trouble with them.

Re: outline-minor-mode heading levels in C, C++, and html

[Stefan Monnier via Users list for the GNU Emacs text editor]

> This is common, but not universal, and is not part of elisp.

That depends whether you consider

    @section Tips on Writing Comments

to be part of the "definition" of ELisp.


        Stefan

Re: outline-minor-mode heading levels in C, C++, and html

[Joel Reicher]

Stefan Monnier via Users list for the GNU Emacs text editor 
<help-gnu-emacs@gnu.org> writes:

>> This is common, but not universal, and is not part of elisp.
>
> That depends whether you consider
>
>     @section Tips on Writing Comments
>
> to be part of the "definition" of ELisp.

It would depend on what you take to be a language's definition, of 
course, but I don't want to be philosophical.

I think many people take a language to be defined by the behaviour 
of the tooling for that language, although this understanding 
would probably vary according to experience, mindset, and 
hairstyle.

For a programming language the syntax would be determined by the 
compiler/interpreter, and the semantics by the runtime behaviour.

That's why I think it's useful to regard this commenting 
idiom/convention as not part of elisp, because, as far as I know, 
it's not "comprehended" by the runtime tooling.

It is, however, comprehended by the outline-regexp value set in 
lisp-mode, so I think it might make sense to talk about this as 
lisp-mode's comment syntax, because although a major mode is 
usually regarded as supporting a language rather than defining 
one, the major mode in this case is the tooling that determines 
the behaviour.

Cheers,

        - Joel