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

[Bastien Guerry]

Hi Nicolas,

> "manual.org" was updated a month ago, and, so far, nobody complained
> about it. So, I think it's a good time to discuss about what could be
> done next.

Having the manual in .org is a great achievement, congrats to anyone
who worked on this titanic task!

I'm all for editing manual.org instead of org.texi in the long run.

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

fill-column: 70
org-list-description-max-indent: 5
org-edit-src-content-indentation: ?
org-src-preserve-indentation: ?

This is necessary so that contributors don't mess up accidentally with
the desired format.

Can we grow a list here:
https://bimestriel.framapad.org/p/22KTn231su

Also, why are :PROPERTIES: drawers at the beginning of the line?  I
have them aligned with the headline in my configuration, which I find
much more readable. Can we fix this?

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?

- Line 1077: Why indenting this list ?

- It would be nice to have #+[kvc]index with multiple entries per line.

- Line 1303 : Why "- =[fn:NAME]= ::" lives on a single line here?

- Line 21228 ("possible, including the version"): a macro spanning
  over multiple lines is not fontified.

- Footnotes: it would be nice to get an overview of a footnote when
  the pointer is hovering on some [fn:x] reference.

> The first obvious step is to move the file into "doc/" directory. Then
> I assume we could delete "org.texi" and "org.info" there and generate
> new ones from the Org file. For example, the following command, called
> from the "manual.org" file,
>
>     (let ((org-texinfo-logfiles-extensions
>            (cons "texi" org-texinfo-logfiles-extensions)))
>       (org-texinfo-export-to-info))
>
> produces an "org.info" file without an "org.texi". It thus prevents
> direct editing of "org.texi". I assume this could be called by "make
> info" target.

We still need to create org.texi for inclusion into Emacs repository.

> So basically, the idea would be to not provide anymore an "org.texi"
> file. Only "manual.org" and "org.info". Emacs developers already apply
> fixes to ORG-NEWS, which is a plain Org file, so I guess it would not
> make their life harder if "manual.org" replaces "org.texi".
>
> WDYT?

I think it's a great step forward but a big one, so let's move
carefully here.

Thanks!

-- 
 Bastien