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

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

Hello,

Bastien Guerry <bzg@gnu.org> writes:

> Before moving manual.org into doc/, I'd suggest we agree on editing
> variables like `fill-column' and the like:
>
> fill-column: 70

This is already the case.

> org-list-description-max-indent: 5
> org-edit-src-content-indentation: ?

It is 2. I'd favor 0, but I don't care much.

> org-src-preserve-indentation: ?

nil.

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

> 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).

> I have them aligned with the headline in my configuration, which
> I find much more readable. Can we fix this?

There is nothing to "fix": this is a configuration option, per above.

> IMO the above questions should be resolved before exposing manual.org
> to collaboration.
>
> Some other micro-reports/requests, not blocking anything:
>
> - Line 1013: Why an orphan dash?  Because of #+vindex entries?

Yes.

> - Line 1077: Why indenting this list ?

Fixed. Note that it didn't change output.

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

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

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

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

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

Note that I made a few design choices I didn't write about, e.g.,:

  - use fixed-width area for one-line examples,
  - use example blocks for Org syntax instead of "begin_src org",
  - internal links to headlines always start with a star,
  - 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.

Thank you for the review.

Regards,

-- 
Nicolas Goaziou                                                0x80A93738