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
