Headlines require both space and star

Headlines require both space and star

[Ryan Tate]

Hello, I am writing to suggest that the documents reflect that 
both a star and space are required to create a headline, not just 
a star.

Today I learned org mode through the manual, compact guide, "Org 
mode beginning at the basics" at orgmode.org and David O'Toole 
tutorial at orgmode.org.

I spent about 15 minutes trying to figure out why folding wasn't 
"working" in the very first org doc I then created.

It turns out I was not including a space after the star in my 
headlines. My doc looked like this:

*Intro
**First Part
**Second Part
***Sub part
**Third Part

etc.

When I did add spaces after the stars, suddenly the headlines were 
recognized (color changes) and folding worked as described in the 
manual at last. (I am on GNU Emacs 26.3 (build 1, 
x86_64-redhat-linux-gnu, GTK+ Version 3.24.11) of 2019-12-10)

I went to see if I missed something when I read the docs. Here are 
various ways headlines are described, none seem to mention the 
space after the star being required:

Manual, compact guide: " The headlines in Org start with one or 
more stars, on the left margin3. For example..." 
https://orgmode.org/manual/Headlines.html#Headlines
https://orgmode.org/guide/Headlines.html#Headlines

Org mode beginning at the basics: "This is a headline, it starts 
with one or more stars.  A heading has one star, a sub-heading 
two, etc."
https://orgmode.org/worg/org-tutorials/org4beginners.html

David O'Toole Org Tutorial: "First-level headlines begin with one 
star; second-level headlines begin with two stars, and so on. "
https://orgmode.org/worg/org-tutorials/orgtutorial_dto.html

I am presuming that the requirement of a space after a star has 
been omitted from the docs and is not an implementation error. If 
the latter I could probably put together a bug report for the code 
itself. If the former, I would simply suggest that the docs be 
amended to fully describe the actual requirements of headlines so 
others who do read the friendly manual as I did do not waste their 
own 15 minutes :-) If people are open to this, and a more proper 
patch is required, I would be happy to submit one in a more 
elaborate and correct format.

If this has been brought up before, or I am misunderstanding, I 
apologize in advance; the gmane gateway seems to be down so I 
cannot search the archives at the moment.

Cheers and thanks for org mode.

       Ryan

Re: Headlines require both space and star

[Nicolas Goaziou]

Hello,

Ryan Tate <ryantate@ryantate.com> writes:

> Hello, I am writing to suggest that the documents reflect that both
> a star and space are required to create a headline, not just a star.

[...]

> If people are open to this, and a more proper patch is
> required, I would be happy to submit one in a more elaborate and
> correct format.

OK, documentation could be clearer here. Patches are welcome, of course!

Thank you.

Regards,

-- 
Nicolas Goaziou

Re: Headlines require both space and star

[Bastien]

Hi Ryan,

I've tried to make this a bit clearer in the documentation and the
tutorial:

https://code.orgmode.org/bzg/org-mode/commit/27ec1c2cff
https://code.orgmode.org/bzg/worg/commit/b42f8d20a4

Thanks,

-- 
 Bastien