Emacspeak discussion list

[Tim Cross <theophilusx AT gmail.com>]

I sent this yesterday, but only did a reply instead of a wide reply, so
sending it again so that it goes to the list.....


There have already been some good answers in this thread. Raman's advice
on finding what works for you is spot on. I often dedicate a bit of time
on a regular basis to just try out new things that I've seen, heard
about, thought of etc. Very little ends up becoming part of my toolbox,
but I do often get ideas which I use to refine things I do use.

Some things I've observed/discovered.

- Folding. I find how useful this is depends on many factors. The
  language, the code style being used and how the project is
  structured. For example, some langauges have a high ratio of
  boilerplate code and I find folding can be useful for such
  langauges. Others have less or have smaller functions/procedures or
  are broken up into more and smaller files and I find folding less
  useful. I do find it necessary to change the key bindings as often the
  default bindings are combersome. However, this is standard with
  emacs. (see note at the end however)

- Emacs has a huge wealth of build-in tools which even many seasoned
  Emacs users are unaware of. One of my favorite new-ish packages is
  eglot. While lots of people have jumped on the LSP bandwagon and many
  people use lsp-mode, I really like eglot because not only does it
  give you an LSP implementation, it is built on top of existing
  standard tools like xref, eldoc, project, flymake etc. These are all
  existing emacs utilities and what is really nice is that once you know
  them, you can also use them in other projects even without eglot. For
  example, I enjoy using CLojure and CLojureScript. However, even though
  there is an LSP server for CLojure and ClojureScript, I don't use it
  because Cider, the intergrated enironment for Clojure, already has a
  lot of LSP like functionality. However, I do leverage off xref,
  flymake etc to further enhance/extend that environment. In particular,
  xref is a really powerful and useful utility for jumping around in
  your code base e.g. quickly jumping from where a function is used to
  where it is defined and jumping back again etc.

- Two more tools which I think are largely overlooked and have lots of
  potential for improving persoal workflows are abbrev mode and
  bookmarks. In particular, bookmarks are extgremely powerful when it
  comes to large and complex code bases.

- I quite like the stuff done by Protesilaos Stavrou (Prot), the author
  of the modus themes, fontaine and dnote. In particular, I like his
  denote setup as a good starting point for organising my org
  files. What I particularly like about much of what he does is he also
  focuses on leveraging existing built-in Emacs functionality rather
  than re-inventing things and creating all new packages. He also does
  some pretty good videos and his documentation and write ups are very
  details and well written. Highly recommended soruce. 

- Lately I've been using the devdocs package. This uses the
  https://devdocs.io site to provide documentation in emacs using
  eww. It has some nice features and being able to access documentation
  in a more consistent manner is nice (I was already using eww a lot to
  browse documentation, but often had to do a bit of customisation for
  each language to get it to work well. Devdocs goes some of the way to
  providing similar functionality in a more stnadardised manner). 

- Finally, a package which I've only been using for a little while, but
  which seems to offer some interesting potential is hyperbole. This is
  actually a very old package which has some similarities with org
  mode. It is much much older than org mode, but I'm finding it can be
  useful in conjunction with org mode. I'm still figuring out the best
  way to integrate it into my workflow, but so far, it has been
  interesting.

This last point is probably my main point in this reply. As I read your
initial post and you spoke about maintaining an org file and links into
different parts of the code base, I thought of hyperbole's dyunamic
linking capabilities.

The hyperbole manual starts with this

"Hyperbole includes easy-to-use, powerful hypertextual buttons without
the need to learn a markup language; a hierarchical, record-based
contact manager; a rapid window and frame control system; and a
powerful multi-level auto-numbered outliner.  All features are aimed
at making textual information management and display fast and easy."

With hyperbole, you have text patterns which become hyperlinks. What
this means is that you can easily have dynamic links inside your code
files which can link to other places within the same file, other files
in the project or other resources (such as documentations). How this is
different to org-mode is that these links can be inside your actual
code, not a separate file. So, for example, you could have references to
functions/variables/documentation in a comment header for a function and
be able to jump to them very quickly using hyperbole. Nice thing is that
the information can be structured in such a way that it is also still
useful to others reading the code who may not be using emacs. 

Note that I don't see hyperbole as a replacement for org mode, but
rather as an augmentation. Many people use both org mode and
hyperbole. There is even a section in the manual on using both modes and
the hyperbole authors have actually made a number of adjustments so that
the two modes can work in conjunction with each other.

There is also a lot to hyperbole that I don't use. For example, it has
quite a sophisticated document authoring system as well as a
contacts/rolladex type application.

In the long term, I may not even continue to use hyperbole, but I do
find it a good source of ideas regarding other ways to use Emacs and
what can be done. Often, this is the challenge with Emacs - you can
pretty do whatever you can think of, having the food to think of new
things is sometimes the bigger challenge. 

Key bindings note. In some respects, this is possibly the most
challenging part of Emacs and an area where I often see people making
mistakes. The problem is, too many things we want on convenient key
bindings and not enough binding space available. Utilities like hydra
can really help here. However, getting the right balance between customising
and sticking with the standard defaults can be a challenge. For me, this
was something I had to learn largely through trial and error. However,
what I did learn was that it is important to understand and be
comfortable with defining and change key bindings and understanding how
they work i.e. mode versus global, prefixes, sparse key maps etc. The
right bindings will depend heavily on what you do and personal
preferences. Personally, I now use evil mode and tend to follow the VI
key binding approach. I love modal editors and above all, love being
able to navigate around with simple key bindings which don't require
difficult combinations of ctl, alt and shift that make me move my
fingers from the home row. For example, folding/unforlding functionality
is bound to the 'z' prefix in normal mode, so opening/closing a fold is
just 'zo' or 'zc'. Much easier than C-c C-i or C-c @ C-a etc. 

For me, my emacs experience has been largely about cherry picking. I try
out lots of things, but end up only using a very small part and usually
in a way which fits with how I like to work (whihc itself evolves over
time). I don't worry about falling ito rabbit holes or getting lost. I
limit how much time I allow for experimentation, I maintain at least 2
emacs configurations - my main daily driver production setup and my
experimental setup. Once an experimental idea has reached a sufficiently
stable, clear and possibly useful stage, I migrate it to my production
setup. Once or twice a year, I go through my production setup and
anything which is in there that I've not used for 6 or more months, I
archive so that my production setup is as small as possible and less
likely to have conflicts, bugs or performance problems.

My emacs configuiration is a living thing. It changes regularly and is
stilll evolving even after nearly 30 years of Emacs use. Some may
consider that a negative, but I find it a positive. 

Tim
"Robert Melton" (via emacspeak Mailing List) <emacspeak AT emacspeak.net> writes:

> Raman--
>
> Thanks for the tips!  Some more comments inline below. 
>
>> 1. +1 on learning the org bits;
>> 2. See the emacspeak blog article on taking smart notes.
>
> https://emacspeak.blogspot.com/2022/10/learn-smarter-by-taking-rich-hypertext.html
>
> The above post was a great read, and between you and Tim I really think I 
> am 
> incredibly underusing bookmarks. 
>
>
>> 3. What exactly do you mean by "folding" -- there are multiple ways of
>>   doing that.
>> 4. Good to know you hate the experience, but pointless you saying say
>>   so without saying why you "hate" it.
>> 5. In general, it's not worth hating things --- at least in your tools,
>>   use what works for you, ignore the rest.
>
> I laughed out loud, fair enough.  I was posting here after getting 
> frustrated 
> with yafolding, outline-mode, origami and a few others.  I had search 
> issues 
> and sometimes with origami even issues reopening folds, which seemed 
> incredibly odd.  I guess the way I cam away on this was "the juice isn't 
> worth  the squeeze". 
>
>
>> 6. See the blog articles I posted over the  holidays.
>
> They were great!  I actually discovered comint from them and I built my 
> own little interface to an "Apple Reminders" CLI app. 
>
>
>> 7. Read "How to ask questions the smart way" by ESR --it'll make a
>>   difference to the responses you generate.
>
> Read it last time you linked it, wasn't lack of knowledge, was a missive 
> sent off in a state of generalized frustration with the incredibly obtuse 
> and undocumented codebase I am working on. Not an excuse, also, 
> the amount of things I randomly tried was far too long a list to call out.
> In the end, I think I fell into the trap of "if you don't want to deal with 
> the problem make a new more tractable problem!"  ---  Hence dug in 
> on tools which no matter how good can't save you from poorly written
> codebase.  
>
>
>> 8. Use emacs' xref and eglot integration to advantage
>
> This with the Python LSP that mostly can grok the project is all that has 
> kept me sane thus far. 
>
>
>> 9. Chase down the author of the code and see if they have a design-doc.
>> 10. If they dont, then write one as you understand their code, it'll
>>    help the project as well as you.
>
> This is a great point, and I have actually touched base with the client and 
> gotten this work pulled into the scope. Will take a bit to understand the 
> original authors intent, but not sure I could leave something more valuable
> behind for the next person. 
>
>
>> 11. Depending on the language, exercise your understanding by writing 
>> tests.
>> 12. All of the above are good software engineering practice; emacs is a
>>    tool that helps you do those well --- or poorly depending on how
>>    well you know to use your tools.
>> 
>
> Absolutely, every time I dig around the Emacspeak codebase and build system 
> I learn a little more.  But still learning all the dials and levers, I have 
> just scratched
> the surface of all the features built into Emacs, and only started recently 
> doing any
> non-trivial customizations.