Improve documentation, and decide on TOC

[jackkamm]

Followup to #262.

That PR, which converted the Readme markdown to org-mode, also contained some other improvements to the documentation, such as a Table of Contents (TOC) section in the Github export; however I have postponed those changes for further consideration here.

One problem was that while the TOC section helps the readability on Github a lot, the TOC links are broken when viewed in Emacs.

However, the bigger issue is that the Readme is long and hard to navigate, and should be reorganized to improve the readability.

Back to the TOC, here are some possible options on that issue:

1. Keep the TOC section, and accept the broken links within Emacs. Other packages do this also. It might not be so bad, if the rest of the document is well organized: when reading in org-mode, we don't need to use the TOC because of the outline-folding views. @edgar-vincent also suggests adding :ARCHIVED: tag to prevent unfolding, but this feels a bit awkward to me.

2. Split the Readme into multiple documents. External links work correctly in Github's Org-mode rendering, so the links should work in both Emacs and Github. However, a downside of this approach is that it loses some advantages of Org -- it is nice being able to navigate within a single document using Org's outline folding. For example, see org-manual.org.

3. Move the documentation into Github wiki format. I think it can actually use Org-mode. However this suffers some of the same disadvantage as (2), and also another downside is that the docs are no longer linked to the code's version-control.

4. Use Org-mode to export the documentation to html and host it somewhere. Then link to it in the Readme. We can also export to Info format, thereby solving #220. This seems like the nicest way to me (again, following org-manual's example), but also adds some complexity. Where will we host it? Do we use some CI to keep it automatically updated, or do we manually do it (and have to remember)?

Currently, I lean towards either options 1 or 4 -- 1 is not perfect but is simple and probably good enough. While 4 is the nicest way but takes more work.

However, I think these web formatting details are less important for now. More important is to improve the readability and organization of the content. After we do this, and make the documentation easier to read within Emacs, we can decide how to format for the web.

[edgar-vincent]

I agree with you about solutions 1 and 4. As you suggest, we could choose 1 for the moment, rewrite the README then decide about other formats. I don't think it's a big deal to have dead links within Emacs for the moment. I've started rewriting it and will add a PR with my changes so you can review them.

An info manual would be great, as it is the standard way of accessing documentation in Emacs. Publishing the info manual and/or the README should be trivial. I do it on my Sourcehut page with a script that invokes org-publish. It could be hosted on Github pages.

I'll focus on making the README shorter and clearer for now, as org-caldav is a sensitive package and requires careful and easy instructions.

[elken]

You can actually have the best of both worlds with https://github.com/zxhoper/emacs-org-toc-org, Doom uses it to have "good enough" links for github and Emacs (full config)

As for the issue that linked me here, the instructions on org-gcal work with the added necessity for also enabling the CalDAV API

[edgar-vincent]

@elken This is the package I used in the original PR, but, unfortunately, it requires the package to be installed in order for links to work inside Emacs. I'm not sure we should require that users pull an extra package only for the docs' TOC. It makes sense in the context of Doom Emacs (which I use), since it is required for the built-in docs.

The priority is still rewriting the docs, though. I'm still working on it, but very slowly, as I'm currently drowning in different Emacs projects.

[jackkamm]

There hasn't been progress on this for awhile so I started a PR here:
#294
Feedback is welcome. Also, if you did do any work on writing docs, now would be a good time to share any work-in-progress, to see if it could be incorporated.

[jackkamm]

Closing this (and other documentation-related issues) in favor of #296