[craftedv2beta] Improve Getting Started Guide

[jvdydev]

New issue based on #297

• early-init.el setup for crafted-emacs is missing from docs in Starting from an existing configuration
• maybe add: Explanation on how crafted-emacs works (package management setup / module system)

An idea would be to split out the prerequisites (one for new-to-emacs, one for with-config), then have a unified section for "bootstrapping" crafted-emacs (and potentially a section or sub-section explaining how/why the package management is organized as it is).

Just some thoughts for now, open to ideas, suggestions and discussion. I'm also open to implementing these as a PR.

UPDATE (11.07.2023)

• [x] Rewrite Getting Started Guide
  • [x] Introduction stage (git clone, reference Emacs docs)
  • [x] Unified Bootstrap (early-init.el, init.el)
  • [x] Package management in crafted-emacs
  • [x] Module system
• [x] Remove duplicate entries (added 18.07.2023)

Current layout plan (see below for discussion):

• clone the repo, explain locations for project and config
  • reference info "Emacs > Customization > Init File"
  • maybe reference "Emacs > Microsoft Windows > Windows HOME" for config-path on Windows
• Bootstrap configuration (early-init.el and init.el)
• package management in crafted-emacs (explain how/why selecting packages)
  • reference help for package-install-selected-packages and package-selected-packages
• The module system (how/where modules are organized/documented)
• "Where to go from here"
  • link to further resources like Modules, Managing packages, Example Configuration

[jvdydev]

Clarification on the proposed layout, something like:

• "What users without existing config need to know before starting"
  • ...
• "What users with existing config need to know before starting"
  • ...
• "How to set up crafted-emacs"
  • Clone the repo, explain project and config locations
  • Bootstrap configuration (early-init.el, init.el)
  • package management in crafted-emacs (explain how/why selecting packages)
  • The module system (how/where modules are organized)
  • "Where to go from here" (link to further resources like Modules, Managing packages, Example Configuration)

Currently, Starting from Scratch -> Emacs Initialization also has half a module configuration for crafted-defaults in it. If this would be the base of the crafted-defaults module doc, the whole bootstrapping could probably be a single section (as put above).

The part on File paths in Windows/Linux/etc. would probably reside in the first sub-section (alongside cloning).

[jeffbowman]

early-init.el setup for crafted-emacs is missing from docs in Starting from an existing configuration

That is because I assume (perhaps incorrectly) that since they have their own configuration already, they probably also already have an early-init.el file and don't need further explanation about it. We can certainly add something there, perhaps a back link to the Getting started from scratch section.

[jvdydev]

ye, I'm not sure we should assume that if someone has some configuration file that they are already familiar with all the common systems of Emacs configuration (and/or which parts are needed to get a crafted-* module to work, unless it's documented).

I think separating it out (like proposed) and explaining all the things that the crafted-emacs-early-init and crafted-emacs-init modules do would give the users the option to decide whether to add missing parts to their early-init.el or to scrap it in favour of crafted-emacs-early-init. This would give new users a full guide on the modules while also giving experienced users the information to decide for themselves.

I personally don't really see the need to split out too much information between "new users" and "users with a config", but I'm open to be proven wrong of course :smile:.

[jeffbowman]

Good points. I separated them out because I thought the new person needed more hand-holding and more explanation than someone who already had a config that was working for them and now they are switching. Notable exceptions might be those coming from other starter kits (doom, space, prelude, etc) as they would be aware (to some degree) of how to configure Emacs in the context of those kits, but here we are describing how they would configure Emacs... oh, and by the way, here is some code to get you started (ala Crafted Emacs modules etc).

So maybe we conflate the concepts and just provide a single set of docs. My only concern there is how much of the standard Emacs documentation are we duplicating in that sense? Maybe we provide a bit of an explanation and then have pointers into the standard documentation for more depth? Thinking in terms of the book Mastering Emacs, we could occupy a similar space but focused solely on the configuration aspects rather than the general usage of Emacs.

Going down that particular road might imply slight changes to the structure you suggest, but might also reduce some of the effort needed for completion. What do you think?

[jvdydev]

Ye, I've looked a bit through the info section for Emacs. I feel like a lot can be trimmed and just referenced (as you pointed out).

Thinking about it more, I actually found there is nothing that can't be explained using links to Emacs info in any user-group-specific sections.

Cutting those and adding references would maybe be something like:

• clone the repo, explain locations for project and config
  • reference info "Emacs > Customization > Init File"
  • maybe reference "Emacs > Microsoft Windows > Windows HOME" for config-path on Windows
• Bootstrap configuration (early-init.el and init.el)
• package management in crafted-emacs (explain how/why selecting packages)
  • reference help for package-install-selected-packages and package-selected-packages
• The module system (how/where modules are organized/documented)
• "Where to go from here"
  • link to further resources like Modules, Managing packages, Example Configuration

I wonder if the "package management" section could just be a prelude to the "module system" section, but I feel like that's something to just try out how it looks/feels.

[jeffbowman]

In this section:

• clone the repo, explain locations for project and config
  • reference info "Emacs > Customization > Init File"
  • maybe reference "Emacs > Microsoft Windows > Windows HOME" for config-path on Windows

We may want to include:

• Crafted Emacs specific structure / organization of the init.el file,

... or are you thinking that goes in the bootstrap section?

Otherwise, I think your outline looks good. (may need to update the tasks above though ;-) )

[jvdydev]

I'd put that into the bootstrap since it would have to be explained there anyway.

Also allows the first part to "only" be generic stuff (git clone, Emacs info references) and then have the bootstrap to only focus on the early-init.el/init.el layout.

I'll update the original and add the layout suggestion

[jvdydev]

I'm making some progress on this, however I found that some of what we decided should be in the Getting Started Guide is already partially present across the documentation (outside the Getting Started Guide):

• crafted-package.org/Configuring a package manager is basically the early-init setup
• crafted-package.org/Installing packages could fit in the packages module section
• crafted-emacs.org/Customization/Example configuration probably should be the final part of the Getting Started Guide (basically ending on what the guide explained up to that point)

Should I move those over and integrate them into the layout (or link to it)?

[jeffbowman]

Whichever you think is more clear, go with that option. I'm good with moving things around into the layout suggested, and if we are going down that road, it probably makes more sense to move things around to fit that layout and hopefully make things more accessible/discoverable/etc.