README.md: update

2026-02-27 23:10:14 -05:00
parent bca43df931
commit f19be26105
1 changed files with 263 additions and 81 deletions
--- a/README.md
+++ b/README.md
@@ -1,133 +1,315 @@
-<h1 align="center">emacs-personal</h1>
-Lightweight configuration of emacs with basic utilities plus personal configuration
+# emacs-personal
+
+> Lightweight Emacs configuration with essential utilities and personal customizations

 ![emacs-personal](https://archive.org/download/libreweb/emacs-personal-1.1.png?raw=true "emacs-personal")

-### Installation
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Emacs](https://img.shields.io/badge/Emacs-25+-7F5AB6.svg?logo=gnu-emacs&logoColor=white)](https://www.gnu.org/software/emacs/)

-First step:
+---

+## Table of Contents
+
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Requirements](#requirements)
+- [Configuration](#configuration)
+- [Key Bindings](#key-bindings)
+- [Language Support](#language-support)
+- [Troubleshooting](#troubleshooting)
+- [Project Structure](#project-structure)
+- [License](#license)
+
+---
+
+## Features
+
+- **Fast Startup** - Optimized loading with garbage collection tuning
+- **Modern Theme** - VSCode-inspired dark theme
+- **Package Management** - ELPA + MELPA integration
+- **Enhanced Navigation** - Ivy + Projectile for fuzzy finding
+- **Intelligent Completion** - Company mode with multiple backends
+- **Multi-language Support** - Python, JS/TS, PHP, Go, C/C++, and more
+- **Code Quality** - Flycheck + Linter integration
+- **File Explorer** - Neotree sidebar
+- **Dashboard** - Clean startup screen
+- **Developer Tools** - Docker, Terraform, REST client
+
+---
+
+## Quick Start
+
+```bash
+# Clone the repository
+git clone https://git.fridu.us/software/emacs-personal.git ~/.emacs.d/
+
+# Copy environment configuration
+cp ~/.emacs.d/.env.example ~/.emacs.d/.env
+
+# Initialize packages (first time only)
+emacs --batch --eval='(load-file "~/.emacs.d/init.el")'
+```
+
+---
+
+## Installation
+
+### Step 1: Refresh Package Contents
+
+Inside Emacs, run:
+
+```elisp
 M-x package-refresh-contents [RET]
+```

-#### Main mirror
+### Step 2: Clone Repository

-1. `git clone https://c.fridu.us/software/emacs-personal.git ~/.emacs.d/`
-2. `cp -v ~/.emacs.d/.env.example ~/.emacs.d/.env`
-3. `emacs --batch --eval='(load-file "~/.emacs.d/init.el")'`
+#### Primary Mirror

-#### Secundary mirror
+```bash
+git clone https://git.fridu.us/software/emacs-personal.git ~/.emacs.d/
+```

-1. `git clone https://git.sr.ht/~heckyel/emacs-personal ~/.emacs.d/`
-2. `cp -v ~/.emacs.d/.env.example ~/.emacs.d/.env`
-3. `emacs --batch --eval='(load-file "~/.emacs.d/init.el")'`
+#### Secondary Mirror

-### Requirements
+```bash
+git clone https://git.sr.ht/~heckyel/emacs-personal ~/.emacs.d/
+```

-* [x] ttf-hack
-* [x] ttf-anonymous-pro
-* [x] hyphen
-* [x] hyphen-es
-* [x] markdown
-* [x] shellcheck
-* [x] python-virtualenv
-* [x] python-pylint
+### Step 3: Configure Environment
+
+```bash
+cp -v ~/.emacs.d/.env.example ~/.emacs.d/.env
+```
+
+### Step 4: Initialize
+
+```bash
+emacs --batch --eval='(load-file "~/.emacs.d/init.el")'
+```
+
+---
+
+## Requirements
+
+### System Dependencies
+
+| Package | Description |
+|---------|-------------|
+| `ttf-hack` | Hack font family |
+| `ttf-anonymous-pro` | Anonymous Pro font |
+| `hyphen` | Hyphenation patterns |
+| `hyphen-es` | Spanish hyphenation |
+| `markdown` | Markdown processor |
+| `shellcheck` | Shell script analyzer |
+| `python-virtualenv` | Python virtual environments |
+| `python-pylint` | Python linter |
+
+### Install on Arch Linux
+
+```bash
+sudo pacman -S ttf-hack ttf-anonymous-pro hyphen hyphen-es \
+             markdown shellcheck python-virtualenv python-pylint
+```
+
+### Install on Debian/Ubuntu
+
+```bash
+sudo apt install fonts-hack fonts-anonymous-pro hyphen hyphen-es \
+                 markdown shellcheck python3-venv pylint
+```
+
+---
+
+## Configuration

 ### Fonts
-change the typography in the [init-gui.el](modules/init-gui.el#L54) file
+
+Edit [`init-gui.el`](modules/init-gui.el#L54) to customize typography:
+
+```elisp
+(if (member "Hack" (font-family-list))
+    (set-frame-font "Hack-9")
+  (set-frame-font "DejaVu Sans Mono-10"))
+```

 ### Icons

-```console
-$ emacs --batch --eval="(progn (package-initialize)(package-install 'all-the-icons))"
+Install `all-the-icons` package:
+
+```bash
+emacs --batch --eval="(progn (package-initialize) (package-install 'all-the-icons))"
 ```

-### Markdown Mode
+Then press `F8` to open Neotree (will prompt to install fonts on first run).

-Require installed markdown in distro GNU+Linux, example:
+### Environment Variables

-```console
-$ apt install markdown
+Copy and edit `.env.example`:
+
+```bash
+cp ~/.emacs.d/.env.example ~/.emacs.d/.env
 ```

-or
+---

-```console
-$ pacman -S markdown
+## Key Bindings
+
+| Key | Action |
+|-----|--------|
+| `F6` | Toggle line numbers |
+| `F8` | Open Neotree file explorer |
+| `F11` | Toggle fullscreen |
+| `F12` | Revert buffer |
+| `M-0` | Reset frame transparency |
+| `S-C-+` | Increase font size |
+| `S-C--` | Decrease font size |
+| `S-h` | Toggle highlight current line |
+| `C->` | Mark next occurrence (multi-cursor) |
+| `C-<` | Mark previous occurrence (multi-cursor) |
+| `C-c C-<` | Mark all occurrences (multi-cursor) |
+| `C-x e` | Evaluate last expression |
+
+---
+
+## Language Support
+
+### Python
+
+```bash
+# Install dependencies
+sudo pacman -S python-virtualenv python-pylint
 ```

-### Flycheck Mode
- Require installed the languages checking, example:
+| Command | Action |
+|---------|--------|
+| `M-x pyvenv-mode` | Toggle virtualenv |
+| `M-x pyvenv-create` | Create virtualenv |
+| `M-x pyvenv-activate` | Activate virtualenv |

-#### bash, sh
+### JavaScript / TypeScript

-```console
-$ pacman -S shellcheck
+- Auto-completion with Company mode
+- Syntax checking with Flycheck
+- Emmet support for HTML/CSS
+
+### Shell Scripts
+
+```bash
+sudo pacman -S shellcheck
 ```

-#### python
+### Markdown

-```console
-$ pacman -S python-pylint
+```bash
+# Arch
+sudo pacman -S markdown
+
+# Debian/Ubuntu
+sudo apt install markdown
 ```

-### Neotree
+### Other Languages

-Neotree comes by default in combination with all-the-icons.
-So pressing `[f8]` will display (you must give "yes") a one-time screen to install all-the-icons fonts.
+- C/C++/C#
+- PHP
+- Go
+- Lua
+- Ruby
+- YAML
+- Dockerfile
+- Terraform
+- reStructuredText (ox-reveal)

-### Linum
-So pressing `[f6]` will display
-
-### Mode Python
- Require installed virtualenv:
-
-        $ pacman -S python-virtualenv
-
- Enable or disable pyvenv-mode: <kdb>M-x</kdb> pyvenv-mode
-
- To create virtualenv from emacs:
-
-        $ pyvenv-create
-
- To activate virtualenv from emacs:
-
-        $ pyvenv-activate
+---

 ## Troubleshooting

-```bash
+### GPG Signature Error
+
+```
 Failed to verify signature archive-contents.sig:
-No public key for 066DAFCB81E42C40 created at 2019-10-05T04:10:02-0500 using RSA
-Command output:
-gpg: Firmado el sáb 05 oct 2019 04:10:02 -05
-gpg:                usando RSA clave C433554766D3DDC64221BFAA066DAFCB81E42C40
-gpg: Imposible comprobar la firma: No public key
+No public key for 066DAFCB81E42C40
 ```

-### Method 0
+#### Method 1: Import GPG Key

-```console
-$ gpg --homedir ~/.emacs.d/elpa/gnupg --receive-keys 066DAFCB81E42C40
+```bash
+gpg --homedir ~/.emacs.d/elpa/gnupg --receive-keys 066DAFCB81E42C40
 ```

-### Method 1
+#### Method 2: Disable Signature Check (Temporary)

-Disable temp signature key
+```bash
+# Disable signature check
+sed -i "s|(setq package-check-signature 'allow-unsigned)|(setq package-check-signature nil)|g" \
+  "$HOME/.emacs.d/init.el"

-```console
-$ sed -i "s|(setq package-check-signature 'allow-unsigned)|(setq package-check-signature nil)|g" "$HOME/.emacs.d/init.el"
-```
-
-```console
+# Inside Emacs
 M-x package-install RET gnu-elpa-keyring-update RET
+
+# Re-enable signature check
+sed -i "s|(setq package-check-signature nil)|(setq package-check-signature 'allow-unsigned)|g" \
+  "$HOME/.emacs.d/init.el"
 ```

-and enable signature key
+### Package Installation Issues

-```console
-$ sed -i "s|(setq package-check-signature nil)|(setq package-check-signature 'allow-unsigned)|g" "$HOME/.emacs.d/init.el"
+If packages fail to install, try:
+
+```elisp
+M-x package-refresh-contents
+M-x package-reinstall RET <package-name> RET
 ```

-## Evaluate in buffer
+### Font Issues

-<kbd>C-x</kbd> + <kbd>C-e</kbd>
+If fonts don't render correctly:
+
+1. Install fonts: `M-x all-the-icons-install-fonts`
+2. Restart Emacs
+3. Check available fonts: `M-x font-selector`
+
+---
+
+## Project Structure
+
+```
+~/.emacs.d/
+├── init.el              # Main configuration file
+├── custom.el            # User customizations (auto-generated)
+├── settings.el          # Personal settings
+├── .env.example         # Environment variables template
+├── modules/             # Feature modules
+│   ├── init-gui.el      # GUI settings
+│   ├── init-elpa.el     # Package management
+│   ├── init-company.el  # Auto-completion
+│   ├── init-flycheck.el # Syntax checking
+│   ├── init-python.el   # Python support
+│   └── ...
+└── elpa/                # Installed packages
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## Acknowledgments
+
+- [GNU Emacs](https://www.gnu.org/software/emacs/)
+- [MELPA](https://melpa.org/)
+- [Doom Emacs](https://github.com/hlissner/doom-emacs)
+- [Spacemacs](https://www.spacemacs.org/)
+
+---
+
+<div align="center">
+  <p>Hosted on <a href="https://git.fridu.us/software/emacs-personal.git">git.fridu.us</a></p>
+  <p>Happy hacking!</p>
+</div>