emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* Bug: Org manual: Structure Editing: Clarify commands which use the Transient Mark region [9.3.6 (9.3.6-23-g01ee25-elpaplus @ /tmp/.emacs.d.tmp.99712ad4-61f4-4464-b003-d6d4eea9b98f/org-plus-contrib-20200309/)]
@ 2020-03-15 18:01 B Goodr
  2020-03-15 21:11 ` Kyle Meyer
  0 siblings, 1 reply; 7+ messages in thread
From: B Goodr @ 2020-03-15 18:01 UTC (permalink / raw)
  To: emacs-orgmode


[-- Attachment #1.1: Type: text/plain, Size: 1203 bytes --]

This is not a defect in functionality, only in the documentation
AFAIK. Find attached an Org file I used to tangle up the question
posted at https://emacs.stackexchange.com/q/56155/15483 .  At the time
I posted that question to stackexchange, I thought it was a behavioral
defect or a user-error on my part. Instead, now I think it is
something that needs improvement in the documentation.

The attached Org file launches an emacs -Q session as a child process
with a separate ".emacs.d" with nothing else in it, to guarantee it is
not polluted with my own special config.

The essential issue is this: The paragraph at the very bottom of the
Structure Editing page of the manual is misleading: It leads a user to
believe that all of the commands use the Transient Mark region, but some of
them do not or should not.  One possibility to fix this is to mention,
inside each described command in that page, which ones respect the
region, and which ones do not, possibly using footnotes for more
details.

Thanks to the Org contributors for a wonderful tool!

-Brent

P.S., OT:L Could not use M-x org-submit-bug-report directly as something is
messed up in my Emacs mail config that I can't fix right now.

[-- Attachment #1.2: Type: text/html, Size: 1403 bytes --]

[-- Attachment #2: OrgModePromoteDemoteMultipleHeadings.org --]
[-- Type: application/octet-stream, Size: 11065 bytes --]

* Org Mode Promote Demote Multiple Headings
  :PROPERTIES:
  :ID:       91eef3bf-3dfc-4a9b-92f3-1f712d72d5b1
  :tangle-dir: /tmp/org.mode.promote.demote.multiple.headings
  :END:

** Instructions for use

 1. Define the org-in-tangle-dir function (see that heading below).
 2. Use C-c C-v t, C-c C-v C-t. to tangle this buffer.
 3. Jump down to [[id:99712ad4-61f4-4464-b003-d6d4eea9b98f][runscript]] below and run it.
 4. Go to the tangle-dir property in the top heading and inspect its output (e.g., /tmp/org.mode.promote.demote.multiple.headings/post.txt)

** org-in-tangle-dir

#+NAME: org-in-tangle-dir
#+BEGIN_SRC emacs-lisp :results value :noweb yes :exports none
  ;; Define the function mentioned in: https://emacs.stackexchange.com/a/55859/15483
  ;;
  ;; I'm not using the usual "bg-" prefix as someday I will want this pushed
  ;; upstream to the org maintainers, so I use "org-" prefix.
  ;;
  (defun org-in-tangle-dir (sub-path)
    "Return the tangle-dir property from the current point, and use it as the directory to expand SUB-PATH to.
  This is used for tangling in Org files as indicated in https://emacs.stackexchange.com/q/46479/
  If there is no such tangle-dir property in the current tree or any parent, it returns the current
  current org buffers directory."
    (expand-file-name sub-path
		      (or
		       (org-entry-get (point) "tangle-dir" 'inherit)
		       default-directory)))
#+END_SRC


** emacs.stackexchange.com post
:PROPERTIES:
:ID:       782fa47a-c9a5-4725-90a3-85e124b88b93
:END:

Add this to the emacs.stackexchange.com post:

#+BEGIN_SRC text :noweb yes :tangle (org-in-tangle-dir "post.txt") :exports none :mkdirp yes
  # The Problem

  ,**Jump down to Update 1 below for my thoughts as to the chosen answer to this question.**

  I'm using Emacs version <<emacs-version()>> with Org Mode version
  <<org-mode-version()>> installed from Melpa.

  In the Org manual for [Structure Editing][1], I read this:

         When there is an active region - i.e., when Transient Mark mode is
      active - promotion and demotion work on all headlines in the region.  To
      select a region of headlines, it is best to place both point and mark at
      the beginning of a line, mark at the beginning of the first headline,
      and point at the line just after the last headline to change.  Note that
      when point is inside a table (see *note Tables::), the Meta-Cursor keys
      have different functionality.

  But when I make the transient Mark active and set both mark and point
  around more than one heading, type <M-S-left> (`org-shiftmetaleft`),
  it only promotes the first or last heading, depending upon which one
  mark and point are on at the time. I want it to do what I think the
  above implies, and promote all headings in the region. Ditto for
  demoting headings.

  Either this is a defect, or user error. Which is it? See MCVE below for details.

  # MCVE

  Store the following setup.el file into an experiment directory, say, <<experiment-dir()>>

  <!-- language: lang-el -->

      <<setup>>

  Launch emacs and load the above Elisp file under `-Q` conditions like this:

      <<runscript>>

  This will download the minimal amount of packages to retrieve the
  latest version of Org mode into a scratch directory at
  <<tmp-package-user-dir()>> so you may choose remove that directory
  later.

  Add the following lines into a small Org mode file:

      ,* Level 1 heading
      ,** Level 2 heading1
      ,** Level 2 heading2
      ,** Level 2 heading3

  Move point in front of the first asterisk in the "Level 2 heading"
  line. Then use M-h (`org-mark-element`) three times to mark the next
  three headings. Then type <M-S-left> (`org-shiftmetaleft`) and then
  only the first one, "Level 2 heading1", is promoted:

      ,* Level 1 heading
      ,* Level 2 heading1
      ,** Level 2 heading2
      ,** Level 2 heading3

  I tried moving point right after the last "g" in "level 4 heading" and
  it promoted only the last one, ignoring the region completely:

      ,* Level 1 heading
      ,** Level 2 heading1
      ,** Level 2 heading2
      ,* Level 2 heading3

  I've tried all sorts of things and never achieved the goal in this
  case which is to promote all three Level 2 headings into level 1:

      ,* Level 1 heading
      ,* Level 2 heading1
      ,* Level 2 heading2
      ,* Level 2 heading3

  https://emacs.stackexchange.com/a/54301/15483 seems to imply that it
  should work and I have something broken in my org mode or something.

  # Update 1

  If you look inside [Structure Editing][1] only see this:

      ‘M-<LEFT>’ (‘org-do-promote’)
           Promote current heading by one level.

      ‘M-<RIGHT>’ (‘org-do-demote’)
           Demote current heading by one level.

      ‘M-S-<LEFT>’ (‘org-promote-subtree’)
           Promote the current subtree by one level.

      ‘M-S-<RIGHT>’ (‘org-demote-subtree’)
           Demote the current subtree by one level.

    The last paragraph I quoted at the top of this question does not
  indicate the scope of commands that respect the marked region. That
  led me to conclude the region applies to them all, which is not the
  case.  Thus, the answer at
  https://emacs.stackexchange.com/a/56157/15483 is the correct answer.

  I consider this to be a defect in the Org Manual, not in the behavior:
  This question will be out of date with new manuals if/when this defect
  is fixed.

    [1]: https://orgmode.org/manual/Structure-Editing.html#Structure-Editing
#+END_SRC

** test-org-file
:PROPERTIES:
:ID:       ca2207e9-f3ce-40e7-b184-af53bac9c4d7
:END:

#+NAME: test-org-file
#+BEGIN_SRC text :noweb yes :tangle (org-in-tangle-dir "test.org") :exports none :mkdirp yes
  ,* Level 1 heading
  ,** Level 2 heading1
  ,** Level 2 heading2
  ,** Level 2 heading3
#+END_SRC

** experiment-dir

#+NAME: experiment-dir
#+BEGIN_SRC emacs-lisp :results value :noweb yes :exports none :var experiment_dir=(org-entry-get (point) "tangle-dir" 'inherit)
  experiment_dir
#+END_SRC

** tmp-package-user-dir

#+NAME: tmp-package-user-dir
#+BEGIN_SRC emacs-lisp :results value :noweb yes :exports none
  "/tmp/.emacs.d.tmp.99712ad4-61f4-4464-b003-d6d4eea9b98f"
#+END_SRC

** emacs-lisp-file
:PROPERTIES:
:ID:       5555868b-171e-48f5-89c8-01851c5b913f
:END:

#+NAME: setup
#+BEGIN_SRC emacs-lisp :results output :noweb yes :tangle (org-in-tangle-dir "setup.el") :exports none :mkdirp yes
  (defun my-use-package-setup ()


    ;; Derived from
    ;; https://github.com/chrispoole643/etc/blob/master/emacs/.emacs.d/init.el
    ;; referenced by
    ;; https://www.reddit.com/r/emacs/comments/5sx7j0/how_do_i_get_usepackage_to_ignore_the_bundled/
    ;;
    ;; Define org and melpa as package sources, and install `use-package' if it's not
    ;; already there. Always ensure packages being loaded are there (or else it'll
    ;; automatically download from melpa)
    ;;
    ;; I don't want to do it this way, as it is org-mode specific. This ordering and
    ;; prioritization has to happen before all use of use-package. Without this,
    ;; we run the risk of some other package we require pulling in the stock
    ;; version of Org mode shipped with Emacs, when we only want the latest
    ;; version.
    ;;
    (require 'package)

    ;; For this MCVE, I _have_ to set package-user-dir below in order to keep my
    ;; installation separate from the normal one, so as to prove that I am only
    ;; installing the minimum set of packages to reproduce the issue for the MCVE:
    (setq package-user-dir (expand-file-name "<<tmp-package-user-dir()>>"))

    (add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
    (add-to-list 'package-archives '("org" . "https://orgmode.org/elpa/") t)
    ;; Ensure that "org" and "melpa" are found first in this order (higher numbers are higher priority):
    (setq package-archive-priorities '(("org" . 3)
                                       ("melpa" . 2)
                                       ("gnu" . 1)))
    ;; This is the key!! -->  " The symbol ‘all’ says to load the latest installed
    ;; versions of all packages not specified by other elements." and for org-mode, this means always get that latest version.
    (setq package-load-list '(all))
    (package-initialize)

    ;; Not sure why we need this:
    (setq package-enable-at-startup nil)

    ;;
    ;; Install use-package unconditionally. For some reason the existing
    ;; use-package version failed so we have to waste initialization time doing it
    ;; every time, and cannot use this:
    ;;
    ;;   ;; Install use-package:
    ;;   (unless (package-installed-p 'use-package)
    ;;     (message "Installing use-package")
    ;;     (package-refresh-contents)
    ;;     (package-install 'use-package))
    ;;
    ;; Reason is unknown.
    ;;
    (package-refresh-contents)
    (package-install 'use-package)

    ;; Require use-package:
    (require 'use-package)

    ;; Load org mode early to ensure that the latest org mode version gets picked up, not the
    ;; shipped version.
    ;;
    ;;   Reference https://github.com/jwiegley/use-package#package-installation
    ;;
    (require 'use-package-ensure)
    (setq use-package-always-ensure t))

  ;;
  ;; Get the package ordering and priority for using use-package:
  ;;
  ;;   Unfortunately, order does matter here: We have to do this setup _before_
  ;;   any and all use of use-package.
  ;;
  (my-use-package-setup)

  ;;
  ;; Get the org package:
  ;;
  (use-package org
    ;; Install both org and "contrib"-uted org-related packages:
    ;;
    ;;    See https://tinyurl.com/y2gt69kj that indicates that org-plus-contrib
    ;;    seems to be some sort of "mashup" package, that includes both org itself
    ;;    and the so-called "contrib" packages. I'm not sure which ones of those
    ;;    contrib packages I actually use so just grab them all.
    ;;
    :ensure org-plus-contrib
    :pin org)

#+END_SRC

** emacs-version block

#+NAME: emacs-version
#+BEGIN_SRC emacs-lisp
  ;; (emacs-version) function returns a lot of extra info whereas I just need the version number in the emacs-version variable:
  emacs-version
#+END_SRC
** org-mode-version block

#+NAME: org-mode-version
#+BEGIN_SRC emacs-lisp
  ;; (org-version) only returns the version number
  (org-version)
#+END_SRC
** runscript
:PROPERTIES:
:ID:       99712ad4-61f4-4464-b003-d6d4eea9b98f
:END:

#+NAME: runscript
#+BEGIN_SRC bash :results output :noweb yes :tangle (org-in-tangle-dir "runscript") :exports none :mkdirp yes :shebang "#!/bin/bash"
  #!/bin/bash

  exec 2>&1
  set -x
  experiment_dir='<<experiment-dir()>>'
  nohup emacs -Q \
         --debug-init \
         --load $experiment_dir/setup.el \
         $experiment_dir/test.org

#+END_SRC

#+RESULTS: runscript
: + experiment_dir=/tmp/org.mode.promote.demote.multiple.headings
: + sleep 1
: + nohup emacs -Q --debug-init --load /tmp/org.mode.promote.demote.multiple.headings/setup.el /tmp/org.mode.promote.demote.multiple.headings/test.org


^ permalink raw reply	[flat|nested] 7+ messages in thread
end of thread, other threads:[~2020-03-26 17:30 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-03-15 18:01 Bug: Org manual: Structure Editing: Clarify commands which use the Transient Mark region [9.3.6 (9.3.6-23-g01ee25-elpaplus @ /tmp/.emacs.d.tmp.99712ad4-61f4-4464-b003-d6d4eea9b98f/org-plus-contrib-20200309/)] B Goodr
2020-03-15 21:11 ` Kyle Meyer
2020-03-15 23:50   ` B Goodr
2020-03-18  3:43   ` Kyle Meyer
2020-03-25 15:54     ` B Goodr
2020-03-26  1:46       ` Kyle Meyer
2020-03-26 17:29         ` B Goodr

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).