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

[Bastien Guerry <bzg@gnu.org>]

Hi Nicolas,

thanks for your answer.

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

>> fill-column: 70
>
> This is already the case.

Okay, I've found .dir-locals.el.

>> org-list-description-max-indent: 5
>> org-edit-src-content-indentation: ?
>
> It is 2. I'd favor 0, but I don't care much.

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

>> org-src-preserve-indentation: ?
>
> nil.

OK.

>> This is necessary so that contributors don't mess up accidentally with
>> the desired format.
>
> Why does it matter? We just put them in ".dir-locals.el" and be done
> with it. They override user's preferences anyway.

I meant: it matters to have .dir-locals.el, so we're all set.

>> Can we grow a list here:
>> https://bimestriel.framapad.org/p/22KTn231su
>>
>> Also, why are :PROPERTIES: drawers at the beginning of the line?
>
> I set `org-adapt-indentation' to nil in the file above. It gives more
> columns in a line, which I find more comfortable (e.g., text always
> starts at the same column).

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.

Having the property drawer at the beginning of the line while all
other metadata (e.g. SCHEDULED etc.) are aligned with the beginning
of the headline's content feels wrong.

Would anyone else use (setq org-adapt-indentation 'content) ?

>> - 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?

>> - Line 1077: Why indenting this list ?
>
> Fixed. Note that it didn't change output.

Thanks.  Noted.

>> - It would be nice to have #+[kvc]index with multiple entries per
>> line.
>
> I'm not sure I'd like it. The current state eases reviewing all index
> entries associated to a location.

Not that important anyway.

>> - Line 1303 : Why "- =[fn:NAME]= ::" lives on a single line here?
>
> It is on a single line like almost every item definition in the file. Am
> I missing something?

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

>> - Line 21228 ("possible, including the version"): a macro spanning
>>   over multiple lines is not fontified.
>
> This is a fontification bug, unrelated to "manual.org". I suggest to
> discuss about it in another thread.

Sure.

>> - Footnotes: it would be nice to get an overview of a footnote when
>>   the pointer is hovering on some [fn:x] reference.
>
> You can use C-c ' on a footnote reference.

An "electric" display would also be good IMO.

>> We still need to create org.texi for inclusion into Emacs repository.
>
> Why do we need it? If it is mandatory (I fail to see why, since we
> provide the source of the info file), can we include it read-only?

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

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.

> Note that I made a few design choices I didn't write about, e.g.,:
>
>   - use fixed-width area for one-line examples,

Agreed.

>   - use example blocks for Org syntax instead of "begin_src org",

Agreed.

>   - internal links to headlines always start with a star,

No problem.  Is the leading star optional?

>   - 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 - which btw should better be named org.org.

To be continued,

-- 
 Bastien