Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

Bastien Guerry <bzg@gnu.org> writes:

> I've added (org-list-description-max-indent . 5)

OK.

> Me too, for the same argument.  But this points to a strong limitation
> to `org-adapt-indentation' for which I'd like to propose this change.
>
>        (setq org-adapt-indentation t) => current behavior
>      (setq org-adapt-indentation nil) => current behavior
> (setq org-adapt-indentation 'content) => only adapt content's
>      indentation, not that of the property drawer.

I proposed this very change some years ago, but it didn't get much
traction and wasn't implemented in the end.

>>> - Line 1013: Why an orphan dash?  Because of #+vindex entries?
>>
>> Yes.
>
> This is definitely a corner-case, but can we imagine another way of
> adding #+vindex entries here?

You can add the #+vindex entries at the end of the paragraph instead of
its beginning. However, cross references then point to the end of the
paragraph. I think the current state is better.

> I was noticing different styles, just wondering if there was a
> favorite one, as contributors may ask themselves.

Tag alone on its line is the favorite one because you cannot always
achieve the other option, i.e., contents on the same line as the tag.

> An "electric" display would also be good IMO.

Not sure what you mean here.

> It is mandatory, as long as the GNU standard for documentation is to
> provide it as a .texi file.

Too bad.

> I don't think providing it read-only is a good idea: people should be
> able to edit it and provide patches against it, even though we prefer
> to encourage patches against manual.org.

Is it really a bad idea to discourage people from editing an
auto-generated file? In any case, I have no strong opinion about this.

>>   - internal links to headlines always start with a star,
>
> No problem.  Is the leading star optional?

Of course. Without it, however, the internal link tries to match
a #+name keyword or a target first.

>>   - tags, node properties, are not shown with the surrounding columns,
>>   - when to use =...= or ~...~ markup: 
>>     - files or extensions use =...=,
>>     - anything that is meant to be written in the Org buffer uses =...=,
>>     - any meaningful token in a programming language uses ~...~.
>>
>> I used {{{var(...)}}} for meta-syntactic names, but we may simply use
>> capitals instead, depending on the output of HTML export. It doesn't
>> change anything in Info format.
>
> I guess the above should be part of a guideline on how to contribute
> to manual.org

Probably, but this is not important as long as manual.org has not moved
to core, IMO.

> - which btw should better be named org.org.

Why is that? "manual.org" is a lot more explicit. What is better in
"org.org"? Note that "manual.org" already exports to "org.texi".