[elpa] externals/org b21d11c 2/4: Document new :tangle-mode forms

[ELPA Syncer]

branch: externals/org
commit b21d11c614d7416db08a52c9a66c13ceefeb87bc
Author: TEC <tec@tecosaur.com>
Commit: TEC <tec@tecosaur.com>

    Document new :tangle-mode forms
    
    * etc/ORG-NEWS: Mention new forms that :tangle-mode accepts.
    
    * doc/org-manual.org (Header arguments): Mention new forms that
    :tangle-mode accepts.
---
 doc/org-manual.org | 24 +++++++++++++++++-------
 etc/ORG-NEWS       | 12 ++++++++++++
 2 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 61030a9..1d02139 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -18182,13 +18182,23 @@ the tangled file's executable permission.
 
 #+cindex: @samp{tangle-mode}, header argument
 The =tangle-mode= header argument specifies what permissions to set
-for tangled files by ~set-file-modes~.  For example, to make
-a read-only tangled file, use =:tangle-mode (identity #o444)=.  To
-make it executable, use =:tangle-mode (identity #o755)=.  It also
-overrides executable permission granted by =shebang=.  When multiple
-source code blocks tangle to a single file with different and
-conflicting =tangle-mode= header arguments, Org's behavior is
-undefined.
+for tangled files by ~set-file-modes~.  Permissions are given by an
+octal value, which can be provided calling the ~identity~ function on
+an elisp octal value. For instance, to create a read-only file one may
+use =:tangle-mode (identity #o444)=. To reduce the verbosity required,
+a octal shorthand is defined, =oXXX= (=o= for octal). Using this, our
+read-only example is =:tangle-mode o444=. Omitting the =o= prefix will
+cause the argument to be interpreted as an integer, which can lead to
+unexpected results (=444= is the same as =o674=).
+Two other shorthands are recognised, ls-style strings like
+=rw-r--r--=, and chmod-style permissions like =g+w=.
+Note that chmod-style permissions are based on
+~org-babel-tangle-default-file-mode~, which is =#o544= by default.
+
+When =:tangle-mode= and =:shebang= are both specified, the give
+=:tangle-mode= will override the permissions from =:shebang=. When
+multiple source code blocks tangle to a single file with conflicting
+=:tangle-mode= header arguments, Org's behaviour is undefined.
 
 #+cindex: @samp{no-expand}, header argument
 By default Org expands code blocks during tangling.  The =no-expand=
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 7bb7fe5..e618feb 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -103,6 +103,18 @@ The =dvipng= option in ~org-preview-latex-process-alist~ 
has a new
 property =transparent-image-converter= which is used instead of
 =image-converter= when producing transparent images.
 
+*** =:tangle-mode= now accepts more permissions formats
+
+Previously =:tangle-mode (identity #o755)= was the only reasonable way
+to set the file mode. ~org-babel-interpret-file-mode~ has been
+introduced which will accept three new formats:
++ Short octals, e.g. =:tangle-mode o755=
++ ls-style, e.g. =:tangle-mode rwxrw-rw-=
++ chmod-style, e.g. =:tangle-mode u+x=
+
+Chmod-style permissions are based on the new variable
+~org-babel-tangle-default-file-mode~.
+
 * Version 9.5
 
 ** Important announcements and breaking changes