Re: `with` as a list.

[Mario Frasca <mario@anche.no>]

On 03/06/2020 10:29, Bastien wrote:
> The few lines above is what we called the "changelog".  It should be
> the first part of the commit message -- after which you can add more
> free-form context and explanations, if needed.

this "Changelog", and I'm sure I am the stiffy one, isn't clear from the 
description.  browsing through the other contributions, I recognize this 
structure:

the "Changelog" is the second block, (preferably) without any empty 
lines.  the next empty line will end the "Changelog" and start the less 
formal comments. (unsure about this).

changes are grouped by file, each changed file is introduced by a line 
starting with an asterisk '*', and the complete path of the file.  then 
follows the function affected, in single parentheses, a colon ':', and 
the description of the change.  if the change is relative to 
documentation, the parentheses include title of the affected paragraph.  
finally the description, formatted as per your html page.

if the next change is in the same file, you skip the leading '*' and 
file name and the line should start with the parenthesized affected object.

----------------------------

for example (two files, two different changes --- code and doc):

* lisp/org.el (org-read-date-analyze): Add support for HHhMM time
input, in similar way as for am/pm times.
* doc/org-manual.org (The date/time prompt): Add example to illustrate
the feature.

----------------------------

other example (two affected files, single description --- code):

* testing/lisp/test-ob-tangle.el (ob-tangle/jump-to-org):
* testing/lisp/test-org-attach.el (test-org-attach/dir): Rig
org-file-apps so that temporary files are visited inside Emacs.

----------------------------

(one file, two different changes --- doc):

* doc/org-manual.org (Capturing column view): Replace stale binding
with mention of org-dynamic-block-insert-dblock, and refer to
org-columns-insert-dblock rather than its obsolete variant.
(The clock table): Prune references to stale binding, rewrite
org-dynamic-block-insert-dblock key sequence in a clearer manner, and
add a dedicated entry for org-clock-report.

----------------------------

slightly sloppy example (two files, single description, not clear what's 
affected):

* lisp/org-clock.el:
* lisp/org-colview.el: Autoload call to org-dynamic-block-define.

----------------------------

etc/ORG-NEWS is an exception, and should be mentioned as first.
are empty lines acceptable?  or will your parser fail to understand?

* etc/ORG-NEWS: Announce the change.

* lisp/org-keys.el (org-mode-map): Rebind C-j to a command emulating
`electric-newline-and-maybe-indent'.

* lisp/org.el (org-cdlatex-environment-indent): Stop using the now
obsolete function.
(org--newline): New helper function.
(org-return): Use it to transparently handle `electric-indent-mode'.
(org-return-and-maybe-indent): New command to emulate
`electric-newline-and-maybe-indent' while taking care of Org special
cases (tables, links, timestamps).

----------------------------