Re: [PROPOSAL] New function `org-headings-to-point' and displayer.

[Adam Porter <adam@alphapapa.net>]

[-- Attachment #1: Type: text/plain, Size: 929 bytes --]

Karl Fogel <kfogel@red-bean.com> writes:

> Thank you, Adam -- I didn't know about those.  I had searched for
> something like that before implementing my own, but I think I searched
> using the term "heading" or something instead of "outline",
> unfortunately, so I never found them.

Org is like Emacs in that it has many nooks and crannies that even
experienced users are unfamiliar with.  There's always something more to
discover.

> Now that I know about `org-display-outline-path', the one improvement
> I'd like to make is to enable it to display the headings with
> per-level indentation, and treat the first level specially (with an
> anchoring dot instead of a directional arrow), as my code did.  It's a
> lot more readable that way displayed in the minibuffer.

You might consider adjusting your fontification settings.  The
single-line outline path can be quite readable with the right faces (see
attached example).

[-- Attachment #2: example --]
[-- Type: image/png, Size: 25545 bytes --]

[-- Attachment #3: Type: text/plain, Size: 2038 bytes --]


> I suppose I would implement this by adding two new optional arguments to `org-display-outline-path':
>
>   * `per-level-indentation': add a newline followed by <this string LEVEL-1 times> in front of each SEPARATOR
>
>   * `level-1-prefix': a special prefix for the first level's heading

I'd recommend against adding more optional arguments to that function,
because it already has four.  Emacs/Org already have enough problems
with code like (org-whatever nil t nil t nil nil t).

> ...and make corresponding changes to the helper functions of course.

Please consider such changes very carefully, because those functions are
used by a number of other packages.  It's already difficult, and often
frustrating, for package authors to maintain code that works across Org
versions, which persist in the wild for years.  Today Org 9.3 was
released with more breaking changes, and I'm just waiting for the bug
reports to roll in on my packages so I can add more conditional
definitions and aliases to meet the needs of the variety of users out
there.

> There should also be some way to access the new functionality
> interactively; the solution might be a new interactive wrapper
> function with its own name, or maybe some new variables?  I don't
> know; I haven't thought it all the way through yet.

> Is there any interest in or opposition to such a patch?  I'd like to
> get a sense of whether it would be able to land in Org Mode before I
> start working on it.

I'd recommend simply making a new interactive function, putting it in
your personal config, and sharing it publicly (e.g. here and on
/r/orgmode).  Use it "in anger" for a while, and solicit feedback from
other users for a while.  Then, if it still seems widely useful enough
to deserve being added to Org proper, apply what you've learned in the
meantime to improve and simplify its implementation before proposing a
patch.

You might also consider sending it to my "unpackaged.el" repo, which
might make a good home for it: http://github.com/alphapapa/unpackaged.el