edgar-vincent
commented
1 year ago 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
jackkamm
Followup to https://github.com/dengste/org-caldav/pull/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:
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.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.
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.
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.