Write an official documentation

[xmailla]

I was thinking this while looking at my notes. I find it a shame that howm is so confidential among emacs users. What is missing? First of all, I would say only a documentation "worthy of the name" starting from the beginning: what is a nowm note, its basic structure, the philosophy behind howm, etc. There is obviously the great work done by Emacs101 (by the way, why not integrate that as an official doc?) but you have to look for it elsewhere than in the official distribution, it is a PDF so, not so easy to use in addition (an info page would be so much more practical).

In short, why not write a complete documentation, in Info format (and not only in Japanese :) ) to give all the light that this mode deserves?

[Emacs101]

@xmailla A great idea would be to create an interactive tutorial, similar to the built-in Emacs tutorial, where new users can learn by doing. This requires careful consideration of the pedagogical aspect, such as how to design and present information in a step-by-step manner that is easy to understand, and how to avoid overwhelming users with technical details.

Another way for everyone to take part in the popularization of howm is by creating videos that showcase the benefits of this package. Let’s be honest, people often omit tutorials but enjoy watching videos on YouTube. :)

[xmailla]

I really prefer reading a documentation above watching some videos. Takes less time to read than to watch someone doing random things ;)

[Emacs101]

I like reading better, but I still watch a lot of Emacs videos. :)

By the way how did you discovered about howm? Was it Reddit, Youtube or other sources?

Some people have told me they prefer the ePub format because it is easier to use. I think it is more convenient for reading on small devices. So I'm thinking about creating ePub alternative to PDF. That would require redoing the illustration, though.

[xmailla]

By the way how did you discovered about howm? Was it Reddit, Youtube or other sources?

I rediscovered it in fact. I was a new howm user in 2008/2009 and then, I stopped doing all hacking activities (hack as in making free software).

I reinstalled emacs in january and browsed my old archives of notes (a mix of howm, records and org)

[jabirali]

Some people have told me they prefer the ePub format because it is easier to use. I think it is more convenient for reading on small devices. So I'm thinking about creating ePub alternative to PDF.

Just to add one more data point: I actually read most of your tutorial on my phone. It worked fine, it’s not uncommon that I look at PDFs on my phone. I just had to rotate a bit between landscape mode for reading text and portrait mode for looking at figures.

But if there was an ePub version I would have chosen that. It’s not just that the text reflows, but also that the ePub reader that comes with my phone supports changing the font and background color, which is more comfy for evening reading.

[kaorahi]

why not write a complete documentation

That's ideal, but I'm just a lazy person. People have been hoping for an official English manual for years, but it still hasn't happened. So I really appreciate @Emacs101's effort in creating such a comprehensive tutorial.

See also: https://github.com/Emacs101/howm-manual/issues/3

[kaorahi]

A bit off-topic, but what are the advantages of howm over org-roam? I don't have an answer to this common question, as I'm not familiar with org. Could it be the mental ease of the "goto" and "come-from" links? Or is the real-time preview in the list view also somewhat uncommon?

Or is it simply that howm is "lightweight", just in the sense that it doesn't require an external database?

(a cheap trial of a short video about the above features)

https://github.com/user-attachments/assets/5a7d0e5f-d4e4-46ef-8f11-3a7af70afbdc

[xmailla]

I do not know Org either (or at least org-roam). For one, I really do not like the cryptic markup language nature of Org and Org is so big that it just discourages me :)

[jabirali]

A bit off-topic, but what are the advantages of howm over org-roam? I don't have an answer to this common question, as I'm not familiar with org.

In my case, I have tried Org Roam, but I find that Howm fits my workflow better.

I tried different organizational systems over the years, but the way that I currently take notes is based on habits I adopted using Logseq some years ago (~2021-2023). Logseq has a daily journal where you write everything, with the format being an "outline" with "wiki links". On disk, the format looks like this:

2025-02-11.md:
  - [[emacs]] [[howm]] This is a note about Howm
    - Here is some comment
    - Here is another comment
      - Here is an indented comment
  - [[some topic]] [[some person]] [[talk]]
    - This is a note about a conference talk
    - Here is some comment

2024-02-10.md:
  - [[howm]] [[workflow]] This is a note about workflows in Howm
    - Here is some comment

Then if you click a link like [[howm]], the app constructs a "transclusion view" that looks like this:

howm:
  2025-02-11:
    - [[emacs]] [[howm]] This is a note about Howm
      - Here is some comment
      - Here is another comment
        - Here is an indented comment
  2024-02-10:
    - [[howm]] [[workflow]] This is a note about workflows in Howm
      - Here is some comment

So this is basically a version of what you called "write fragmentarily, read collectively", where you use backlinks to construct a buffer that shows all your thoughts on that topic over time. You can also write stuff directly at the top of this view; that is called creating a "page" and ends up in howm.md. So it basically merges the concept of "links" and "tags".

For various reasons, I switched back from Logseq to Emacs + Org-mode. However, I wasn't quite happy with most organizational approaches. Org Roam came close, but has some drawbacks that I felt increased friction:

• In Logseq, you can link to a "page" that doesn't yet exist – just type [[howm]] regardless of whether howm.md exists or not. But org-roam-node-insert insists that you create and save a note when trying to link it.
• I found the org-roam-buffer interface cumbersome for "collective reading". That ruined much of the point for me.
• I really dislike the Org Roam link format. By default, it is like [[id:569c8fa0-ff64-4f99-b0d3-5d553cebb841][example]]. You can customize the ID format, but you can't get rid of the IDs. (It renders like example in Org-mode, but it’s in the way if you ever look at the notes via grep, magit, or outside Emacs.)

Howm resolved all of these issues and a bit more:

• The keyword search collects my thoughts on a topic very nicely.
• I can easily link to topics that don't yet have a corresponding "page" yet.
• The comefrom links makes my backlink workflow much simpler. (This convinced me to try Howm.)
• It was easy to import old MarkDown and Org files into the system.

Could it be the mental ease of the "goto" and "come-from" links? Or is the real-time preview in the list view also somewhat uncommon?

I guess my answer would be yes, those things :)

Or is it simply that howm is "lightweight", just in the sense that it doesn't require an external database?

I like the lightweight aspect, but from my point of view that wasn't a deciding factor. The Org Roam database is just a fast cache for the plaintext files on disk, which from my perspective is more an implementation detail.

[Emacs101]

@xmailla Thank you for initiating this discussion. Currently, I am working on the LaTeX version of the manual. It has a more visually appealing layout, but apart from that, it doesn’t offer any additional advantages. This conversation has inspired me to focus more on ePub. Creating a document in that format is a workable short-term goal. I believe ePub will reach a wider audience.

@kaorahi In my opinion, howm strikes the perfect balance between simplicity and functionality. Unlike many other applications that tempt me with unnecessary features, howm keeps me focused on my notes.

Efficient navigation through the notes is the second important aspect. Working with lists is a key element of the system for me. Using Yukio Noguchi's concepts is very beneficial. The preview and search functions are top-notch. Howm's interface offers a great contextual understanding of the information presented.

Another important aspect is the clever linking system, which enhances a discoverability of other notes. Again, it provides a context.

[kaorahi]

Thanks! So is this answer appropriate? Is this worth adding to README?

Q. How does howm compare to Org-roam?

A. Most things you can do in howm are probably possible in Org-roam as well. But howm is more minimalistic and loose in every way. It might feel easygoing and flexible for those who prefer a relaxed approach. The author of howm believes that not aiming for perfect organization is the key to maintaining long-term note-taking without becoming unmanageable. Users seem to appreciate its balance between simplicity and functionality, as well as its smooth navigation UI that helps with reading many fragmentary notes collectively.

Though I'm a little hesitant to say "minimalistic", considering the tutorial is 84 pages long. :p

[jabirali]

@kaorahi: I think it sounds like a good idea to add an FAQ at the bottom of the README; probably, how Howm compares to Org Roam should be there, and perhaps a list of companion apps for other systems like in #36 might be useful too.

I think the text above seems good. I would consider also mention the "comefrom links", which I think is a truly unique feature of Howm; Org Roam can "look for things that link to here" if you ask it, but as far as I know there is no direct equivalent to a "comefrom link". For me, that was a unique feature that initially convinced me to try Howm after trying Org Roam.

Good question regarding "minimalistic". It would at least be correct to say that users feel that it is more minimalistic :). For comparison "the org manual" is 334 pages, and Org Roam inherits most features for e.g. task management and link resolution from Org itself. The "roam" part streamlines the "wiki" workflow in Org (e.g. creating notes, creating links, and finding notes).

[kaorahi]

How about this?

Users seem to appreciate its balance between simplicity and functionality, as well as its smooth navigation UI. The UI, along with the backlink feature, helps with reading many fragmentary notes collectively.

[Emacs101]

Users seem to appreciate its balance between simplicity and functionality, as well as its smooth navigation UI. The UI, along with the backlink feature, helps with reading many fragmentary notes collectively.

Well put!

I agree that the term "minimalistic" is too vague. For me it is very close to "Pareto Optimality", but I don't know how to describe it better. :)

I think not only the backlinks feature, but a whole idea of "link-as-search" distinguishes howm from org-roam. But "come-from" links are certainly unique.

[kaorahi]

too long?

The UI, along with the search-based link/backlink system, helps with reading many fragmentary notes collectively.

I don't think this answer needs to be complete. Actually, I'm just considering how to promote howm in a compact way.

[Emacs101]

too long?

@kaorahi I would say that this is exactly the optimum. :)

[kaorahi]

Another FAQ:

Q. I've heard howm is unbearably slow, actually?

A. There are a few performance options. Once enabled, searches are usually instant, even for 20 years of notes.

[kaorahi]

Thanks, and congrats on the EPUB version! https://github.com/Emacs101/howm-manual

[Emacs101]

Thanks, and congrats on the EPUB version! https://github.com/Emacs101/howm-manual

Howm 1.5.5 certainly deserved a revised tutorial in PDF, along with an additional one in ePub format. Thank you for all the improvements you've made to the package.