Convert README to org format

[edgar-vincent]

This replaces README.md with README.org, improves its wording and formatting, and adds a table of contents.

Fixes https://github.com/dengste/org-caldav/issues/258.

[jackkamm]

Hi @edgar-vincent , thanks for working on this, but I have a couple issues with the current PR:

1. Within emacs, the TOC links don't work. For example, when I try to org-follow the "Quick start" link, I get the message: org-link-search: No match for custom ID: quick-start.

Also, I'm not sure the TOC section is a good idea, as it'll require manual updating whenever the Readme changes. For TOC export it would be better to use Org's toc option (manual). I'm not sure if this would be rendered in Github however.

2. I'd like to preserve the history so that git log --follow would show old changes. The way to do this would be as follows:

• First, make a commit, renaming README.md to Readme.org, but not changing any contents.
• Then, make a second commit, where the markdown formatting is changed to org formatting.

This way, git log --follow would show the full history of the readme, and hopefully git blame would also work nicely.

[edgar-vincent]

Hi @jackkamm,

Thank you for your reply.

1. The reason why I added a custom TOC is that Github does not render Org TOC's (#+options toc:t). I used the following package to generate it automatically: https://github.com/snosov1/toc-org/

I think a TOC is necessary, because the README file is long and rather dense (too much so IMHO. I think it should be simplified, but that could perhaps be done in another PR). I find it difficult to navigate within it and find the information I am looking for easily in its current state. This is also caused by the fact that the wording of the top-level headings is unclear, an issue which I tried to address in this PR.

Sorry about the dead links. Would you like me to fix them and keep the TOC or should I remove it?

2. You are absolutely right about git history. Sorry about that, I'm not very good with git. Should I revert my commits and do as you say or create another branch/PR? Thank you for your detailed explanation.

[jackkamm]

the README file is long and rather dense (too much so IMHO. I think it should be simplified, but that could perhaps be done in another PR). I find it difficult to navigate within it and find the information I am looking for easily in its current state. This is also caused by the fact that the wording of the top-level headings is unclear, an issue which I tried to address in this PR.

I agree the documentation should be reorganized, and is too hard to navigate right now, both on Github and within Emacs.

I think it's fine to expand the scope of this PR to include refactoring of the docs, but only if you want to.

The reason why I added a custom TOC is that Github does not render Org TOC's (#+options toc:t). I used the following package to generate it automatically: https://github.com/snosov1/toc-org/

Sorry about the dead links. Would you like me to fix them and keep the TOC or should I remove it?

Thanks for this info, it's really too bad Org TOC doesn't work on Github.

I checked a couple Org-related packages on Github with large Readmes (emacs-jupyter, org-rifle). It seems they both use toc-org, and also suffer from dead links within Emacs.

So, despite some misgivings, I'm willing to follow their lead and accept the TOC, even with the dead links (it seems too much hassle to make the links work in both Emacs and Github).

Should I revert my commits and do as you say or create another branch/PR? Thank you for your detailed explanation.

If you are interested to do a deeper refactor of the Readme, then I wouldn't worry about this yet, as much of the history will be lost in the refactor anyways. We can decide when looking at the final diff if it's worth reorganizing the commits to try and preserve some of the history.

But if you don't want to refactor the docs, and just want to submit the current change as is, then yes, please reorganize the commits as I described, and then I'll accept the contribution. For the 2nd commit, it would be good if you could also remove changes that are just due to whitespace/newline, to keep the diff smaller.

As to whether to open a new PR, or to force-push into this existing PR -- either way is fine with me.

[edgar-vincent]

Thank you for your very helpful reply. I'd be glad to refactor the docs, but it will take a while.

I am not extremely comfortable with git, but I'll do my best. For now, I'm keeping this PR and will try to rebase the branch in order to implement the changes that you have requested.

The TOC links seem to work, both in Emacs and on Github. However, in Emacs, toc-org-mode needs to be enabled, which doesn't sound very adequate, as I presume most users won't have it enabled or even installed. Github doesn't seem to support custom properties, (see also https://github.com/alphapapa/org-make-toc#known-issues) so I'm not sure what we can do.

[edgar-vincent]

Perhaps we could have both an org and a Mardown file? It would not be the most elegant solution, but I tend to think that non-working links are worse. Markdown would integrate easily on Github, and org in Emacs.

[edgar-vincent]

I think I've found a better solution. If the TOC's heading ("* Contents") has an :ARCHIVED: tag, it is always folded and its visibility isn't toggled by the Tab key. If we add to that #+STARTUP: content, then all the headlines will be folded by default, which provides a form of TOC for Org users. They just have to toggle the visibility of the section they want to read (or the visibility of all sections - since Contents is archived, it won't be unfolded anyway).

Of course, they can also use something like imenu or consult-org to navigate.

If, on top of that, we add the :noexport: tag to the * Contents heading, then it won't be exported to Github, thus providing a better TOC.

[jackkamm]

Closing this PR, as I've merged in your commits separately, after making some modifications and squashing.

Most notably, I removed the TOC for now. I will create a new issue to improve the documentation, and we can consider it there.

Thank you for your work on this!