Revamping the home README

[arifer612]

Revamping the home README

I have two suggestions that I would like to raise in this issue. I would like to get some feedback and comments on whether the community feels these are good changes to make.

1. The translation of README.md to README.org.
2. A thorough cleanup of the contents in the README.

Translation to README.org

I have successfully managed to do so without much difference in this branch of my fork. The only difference I have found is that keybindings cannot be differentiated in Org files as nicely as the <kbd> </kbd> tag in Markdown files:

README.org with keybindings surrounded by =

README.md with keybindings surrounded by <kbd>

Cleanup of the README

There are several areas that are either very repetitive or out of place.

• Instructions to install Spacemacs in Prerequisites do not belong there. The next section is meant for that!
• Instructions to install fonts in Prerequisites do not belong there either! The fonts are not prerequisites. These instructions are repeated again in the next section anyways.
• Installation of ripgrep are repeated on multiple occasions for the different OSes, but that can be moved to a new subsection for post-install goodies, just along with fonts etc.
• There are at least 2 instances in the README that warns users against the usage of emacs --insecure.
• Instructions on updating the master branch, manually and automatically, are no longer relevant and should be removed.
• There may be many more oddities, please feel free to add on to the list!

[smile13241324]

Sounds cool, I think the reason we were using a Readme.md in the first place was that github did not support org natively. With this being gone I see no reason not to convert this file to org.

As to the the various documentation changes this sounds good to me.

PRs are welcome :)

[arifer612]

Awesome! The README.org is already done, so I'll work on the reorganisation of contents over the weekend.

[bryce-carson]

spacemacs/insert-keybinding-org

We can use the interactive command, spacemacs/insert-keybinding-org, called with , i K to produce the tags that we need for the rendered README on GitHub. We don't need to export to HTML, GitHub renders for us. :)

The README doesn't need to be very complex, so more complex Spacemacs documentation and involved setup information should be in DOCUMENTATION.ORG, or a more specific file (such as CONTRIBUTING.org). We must ensure that any Org mode features we'd like to use in the README are supported by the GitHub rendering engine.

The interactive command only works to produce HTML <kbd> opening and closing tags when the HTML exporter–backend is used; whether GitHub renders these, or any HTML embedded in Org files, is implemented in their secure–rendering pipeline. I don't know the repository for that.

I made a test repository, and it appears we could simply use the in-line quotation syntax, described in the Org manual §13.9.5 Quoting HTML tags.

[lebensterben]

@arifer612

I haven't seen this issue before but I have already rewritten the README.

Please verify whether it meets your expectations.

[arifer612]

Hi all! Sorry for not being able to respond to this for so long. I'll have a look at the changes you both have made and get back to you all.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Please let us know if this issue is still valid!