I fully agree with your points, and I believe "copy-pastability" is indeed critical for easy trials. I really appreciate your contribution to the modernization of this project.

By the way, what do you think about swapping the order of org-mode and markdown-mode? The latter combination seems like a more natural choice for new users these days, from my perspective.

I fully agree with your points, and I believe "copy-pastability" is indeed critical for easy trials. I really appreciate your contribution to the modernization of this project.

I’m happy I could contribute something back :)

By the way, what do you think about swapping the order of org-mode and markdown-mode? The latter combination seems like a more natural choice for new users these days, from my perspective.

I completely agree, that sounds like a good idea!

By the way, I also just noticed that I forgot the :ensure t keywords in the MarkDown and Org examples (it is just included in the initial simpler example). That might also be good to add in so that the package autoinstalls when needed.

Thx for the suggestion. Could you check this? (diff)

I'm not confident in either my coding or my English.

I think your suggestion looks great – both the code and the english :). I tested both versions now – starting from an empty init.el – and both versions work well. It's a good idea to remap the Org-mode prefix in the example to prevent conflicts.

I have two minor suggestions for improvements:

• The use-package macro has a keyword :bind, where :bind ("a" . b) is equivalent to (define-key global-map (kbd "a") 'b). This could perhaps be used to make the Org-mode version more compact.

• In my original PR, I added :after org and :after markdown-mode. The original reason was that I wanted to reuse the org-timestamp-formats variable to define the Howm timestamp, and this is not defined until Org has been loaded, and then I just did the same for the Markdown example in case people want to reuse something from there. But thinking about it now, this might be a bad idea: If people lazy-load either Org-mode or Markdown-mode, so that Emacs starts up faster by only loading those modes when you open the first *.md or *.org file, then Howm might not get loaded at all. It might therefore be safer to hardcode the timestamp format and remove those :after keywords to avoid surprises.

So perhaps then we could then revise the Markdown-mode version to (removed :after keyword):

(use-package howm
  :ensure t
  :init
  ;; Where to store the files?
  (setq howm-directory "~/Documents/Howm")
  (setq howm-home-directory howm-directory)
  ;; What format to use for the files?
  (setq howm-file-name-format "%Y-%m-%d-%H%M%S.md")
  (setq howm-view-title-header "#"))

And the Org-mode version to (removed :after keyword, added :bind keyword):

(use-package howm
  :ensure t
  :init
  ;; Where to store the files?
  (setq howm-directory "~/Documents/Howm")
  (setq howm-home-directory howm-directory)
  ;; What format to use for the files?
  (setq howm-file-name-format "%Y-%m-%d-%H%M%S.org")
  (setq howm-view-title-header "*")
  (setq howm-dtime-format "<%Y-%m-%d %a %H:%M>")
  ;; Avoid conflicts with Org-mode by changing Howm's prefix from "C-c ,".
  (setq howm-prefix (kbd "C-c ;"))
  :bind*
  ;; Conveniently open the Howm menu with "C-c ; ;".
  ("C-c ; ;" . howm-menu))

What do you think?

@artsi0m: I think that's an interesting approach as well, but in my opinion having the file extension reflect the file contents is also a useful convention.

For instance, if you keep the notes using a Markdown extension, then you can easily email a note to a colleague if needed and it will open correctly in their editor of choice. Or you can feed the note to an export tool like Quarto or Pandoc, and it understands how to parse it without further instruction.

If so, then maybe we should write some export routines, that would rename extension from txt to md, when exporting ?

I just really appreciate the markup agnostic aspect of howm.

@artsi0m Thanks for sharing a new idea. I think you are referring to something like -*- mode: org-mode -*- at the top of each note file. Please let me know if I've misunderstood.

I still believe this quick-start code is useful since it offers easy solutions for typical requests by new users. From what I've seen, it's rare to use multiple formats in one howm directory, and howm is not optimized for such cases. The key part of this quick-start code is setting howm-view-title-header so that it matches the target mode. This variable needs to be set BEFORE loading howm. It cannot be buffer local due to howm's code design.

"Major-mode free" is a core part of howm's identity, and I'll absolutely keep it. However, I would recommend sticking to a single format for all notes, at least for beginners.

@jabirali I usually add 'thx' lines to Changelog etc. with contributors' names and emails. Is it okay if I copy your full name and email from the commit log? If you'd prefer not, I can use your github ID instead, for example.

@kaorahi Sure, I'd be happy to be mentioned by name and email :)

@kaorahi

Thanks for sharing a new idea. I think you are referring to something like -*- mode: org-mode -*- at the top of each note file. Please let me know if I've misunderstood.

You understand it perfectly.

The key part of this quick-start code is setting howm-view-title-header so that it matches the target mode. This variable needs to be set BEFORE loading howm. It cannot be buffer local due to howm's code design.

I know about it, because I started using howm with org mode and needed to set it via use-package.
I switched away from it[0].
but I needed to wrote a separate python script for this
just to add prop-line and sed one liner to change org heading to howm .

I can put it in issue I already opened.
Together with elisp interactive function to add prop-line.

Oh, sorry. I realize you know about it already.

There will be three cases.

1. Alice usually uses org-mode, but she has heard about howm and wants to try how it works on her existing notes to get a feel for it.
2. Bob is using org-mode and now he wants to use both org and howm permanently on the same set of notes for some reason.
3. Carol has been using org-mode and now wants to switch from org to howm.

As this is a quick start guide, I assume we're focusing on Alice here. In this case, is the current guide ok? Do Bob and Carol need different settings?

Ideally, we'd have advanced documentation covering various tips, including #7, but I'm too lazy...

I agree that it's perhaps best to focus on Alice in the quickstart guide :).

People like Bob and Carol likely start out like Alice, but become more invested in Howm after giving it a try – at which point they will be more motivated to read other documentation with more detailed instructions and suggestions? (For instance, I personally found the tutorial by Andrei Sukhovskii to be very helpful.)

Regarding if they need different settings: I think Bob might want to set org-directory and howm-directory equal for some functionality to work, but other than that I think most things should "just work". There is of course some mutually exclusive functionality – it might not make sense to use both Org Agenda and Howm Reminders together, neither to use both Howm and Org Roam together, since these systems implement similar features in incompatible ways. Perhaps they can be glued together somehow, but that's certainly not a "quick start" project anymore ;). But for a user who just wants to use Org as a convenient format for writing/outlining/exporting and let Howm do the organizing, I think Alice's settings should work well.

I guess Carol's case is more complex? Is she planning to stop using Org as a format altogether, but she wants to keep her notes instead of starting from a new clean howm-directory? Because that might require automated conversion of Org-mode files to another plain-text format, including a conversion of links to be Howm-compatible. That sounds a bit complicated. But if she doesn't insist to convert her notes, she can likely use similar settings as Alice and Bob. She just might want to add the required settings to make Howm search her old note directory as well – so that she can e.g. link to her old notes from her new notes, or get search hits in her old note directory, while using pure Howm as an interface for all her new notes.

For more advanced configuration ideas beyond Alice's needs: Perhaps one possibility might be to create a Github Wiki for this repo? That way, various users could contribute more advanced examples of how to configure and use Howm to the repository. Letting part of the documentation arise as a self-organizing wiki might perhaps be fitting for Howm ;).

@kaorahi @jabirali

Sorry, I wouldn't argue anymore, you seem to be right.

Thanks to @shrysr, tips have already been written on the EmacsWiki page, so we can use that for further tip collection, including #7, org-mode know-hows, and more.

Great! I agree, EmacsWiki is a good place for listing such tips & tricks :)