lite-xl/README_Amiga.md

# Lite XL v2 for AmigaOS 4.1 FE & MorphOS 3

Lite XL is a lightweight text editor written in Lua and SDL2.

The port is not perfect and it might have issues here and there. It might
crash from time to time, if there is a path problem, but overall it works
pretty well. This is my daily editor for any kind of development.
If it crashes on your system, try to delete to `.config` folder.

## Installation
You can extract the Lite XL archive wherever you want and run the *lite*
editor.

## Configuration folder
This editor creates a `.config` folder where the configuration is saved, as
well as plugins, themes etc.. By default this version uses the installation
folder, but if you want to override it, you can create an ENV variable
named `HOME` and set there your prefferable path.

You can check if there is one already set by executing the following command
in a shell
```
GetEnv HOME
```
If there is one set, then you will see the path at the output.

Otherwise, you can set your home path be executing the following command.
Change the path to the one of your preference.
```
SetEnv SAVE HOME "Sys:home/"
```

## Addons
### Colors
Colors are lua files that set the color scheme of the editor. There are
light and dark themes for you to choose.

To install and use them you have to copy the ones you would like from
`addons/colors/light` or `addons/colors/dark` into the folder
`.config/lite-xl/colors/`. Don't add light or dark folders. Just copy the
.lua files in there.

Then you have to start Lite XL and open your configuration by clicking
at the cog icon at the toolbar (bottom left sixth icon). Go at the line
that looks like below
```
-- core.reload_module("colors.summer")
```
and change the `summer` with the name of your color theme. Also, remove
the two dashes `--` at the start of the line and save the file. If you
did everything right, the color schema should change instantly.

The themes can also be found at
https://github.com/lite-xl/lite-xl-colors

### Plugins
LiteXL is able to use plugins to extend its features. Those can be found
at https://github.com/lite-xl/lite-xl-plugins and other websites. Not all
of them will work fine on AmigaOS 4 or MorphOS, because of missing
dependencies or filesystem issues.

To make it easier for you, I gathered some of the plugins that are working
well, and I included them under `addons/plugins`. For you to install the
ones you would like to use, you have to copy the `.lua` files into the
folder `.config/lite-xl/plugins/` and restart the editor.

Please, choose wisely, because adding all the plugins might make the editor
slower on your system. I would recommend you add only those that you really
need.

The included plugins are the following:

**autoinsert**
Automatically inserts closing brackets and quotes. Also allows selected
text to be wrapped with brackets or quotes.

**autosaveonfocuslost**
Automatically saves files that were changed when the main window loses
focus by switching to another application

**autowrap**
Automatically hardwraps lines when typing

**bigclock**
Shows the current time and date in a view with large text

**bracketmatch**
Underlines matching pair for bracket under the caret

**codesets**
This plugin uses the codesets.library on AmigaOS 4 and the
charsets.library on MorphOS to translate ISO encoded files to unicode
and vice-versa. When this is enabled new menu items are added to
load/save the code with a different encoding. Also there is a new
section at the status bar that show the file encoding.
This plugin is **EXPERIMENTAL** and heavily inspired from the encoding
plugin at https://github.com/jgmdev/lite-xl-encoding

**colorpreview**
Underlays color values (eg. `#ff00ff` or `rgb(255, 0, 255)`) with their
resultant color.

**custom_caret**
Customize the caret in the editor setting it to *underline*, *block* or
*line* at the init.lua file in your config folder.
For example add:
`config.plugins.custom_caret.shape = "block"`

**EditorConfig**
EditorConfig (https://editorconfig.org/) implementation for Lite XL

**ephemeral_tabs**
Preview tabs. Opening a doc will replace the contents of the preview tab.
Marks tabs as non-preview on any change or tab double clicking.

**ghmarkdown**
Opens a preview of the current markdown file in a browser window.
On AmigaOS 4 it uses *urlopen* and on MorphOS it uses *openurl* to load
the generated html in the browser. It requires a GitHub application token
because it uses its Rest API. Add it at the init.lua file in your config
folder like below:
`config.plugins.ghmarkdown.github_token = "<token here>"`

**indentguide**
Adds indent guides

**language_guide**
Syntax for the AmigaGuide scripting language

**language_hws**
Syntax for the Hollywood language

**language_make**
Syntax for the Make build system language

**language_sh**
Syntax for shell scripting language

**lfautoinsert**
Automatically inserts indentation and closing bracket/text after newline

**markers**
Add markers to docs and jump between them quickly

**minimap**
Shows a minimap on the right-hand side of the docview. Please note that
this plugin will make the editor slower on file loading and scrolling.

**navigate**
Allows moving back and forward between document positions, reducing the
amount of scrolling

**nonicons**
File icons set for TreeView. Download TTF font to your config/fonts
folder from https://github.com/yamatsum/nonicons/tree/master/dist

**opacity**
Change the opaqueness/transparency of lite-xl using LAmiga+mousewheel
or a command.

**openfilelocation**
Opens the parent directory of the current file in the file manager

**rainbowparen**
Show nesting of parentheses with rainbow colours

**restoretabs**
Keep a list of recently closed tabs, and restore the tab in order on
cntrl+shift+t.

**select_colorscheme**
Select a color theme, like VScode, Sublime Text.
(plugin saves changes)

**selectionhighlight**
Highlights regions of code that match the current selection

**smallclock**
It adds a small clock at the bottom right corner.

**tetris**
Play Tetris inside Lite XL.

## Tips and tricks
### Transitions

If you want to disable the transitions and make the editor faster,
open your configuration file by clicking at the cog icon at the toolbar
(bottom left, 6th icon) and add the following line at the end of the file,
and then save it. You might need to restart your editor.

```
config.transitions = false
```

### Hide files from the file list

If you would like to hide files or whole folder from the left side bar list,
open your configuration by clicking at the cog icon at the toolbar
(bottom left sixth icon) and add the followline at the end of the file and
save it. This hides all the files that start with a dot, and all the `.info`
files. You might need to restart your editor.

```
config.ignore_files = {"^%.", "%.info$"}
```

You can add as many rules as you want in there, to hide files or
folders, as you like.

## I would like to thank

- IconDesigner for the proper glow icons that are included in the release
- Capehill for his tireless work on SDL port for AmigaOS 4.1 FE
- Michael Trebilcock for his port on liblua
- Bruno "BeWorld" Peloille for his great work on porting SDL to MorphOS
  and for his valuable help
- Lite XL original team for being helpful and providing info

Without all the above Lite XL would not be possible

## Support
If you enjoy what I am doing and would like to keep me up during the night,
please consider to buy me a coffee at:
https://ko-fi.com/walkero

## Known issues
You can find the known issues at
https://git.walkero.gr/walkero/lite-xl/issues

# Changelog
## [2.1.6r1] - 2024-12-3
### Changed
- Compiled with latest SDL v2.30.9 for the AmigaOS 4

### Updated
- Updated the code to the upstream 2.1.6 release

## [2.1.4r1] - 2024-05-23
### Added
- Added the ability to open files and folders by drag 'n drop them on the
  LiteXL icon when this is on the AmiDock (AmigaOS4) / Panel (MorphOS)

### Updated
- Updated the code to the upstream 2.1.4 release

### Fixed
- Fix opening files from the root of a device

## [2.1.3r1] - 2024-03-09
### Added
- Added AmiUpdate support
- Added the Tetris plugin

### Updated
- Updated the code to the upstream 2.1.3 release
- Compiled with SDL 2.30.0 that supports editing with ISO encodings, other
  than English. Now the editor should be able to support any language
  and in conjuction with the codesets plugin be able to make text
  encodings conversions
- Now the codesets plugin supports MorphOS 3.18 and above

### Changed
- Changed the way the "Open in system" option executes the WBRun command
  in AmigaOS 4, with a more secure way
- Did a lot of code cleanup in sync with the upstream, and parts of code
  that were left over
- Compiled with pcre2 10.42 (MorphOS version only)

### Fixed
- I did a lot of changes on path manipulation and usage, fixing scanning
  the root of a partition or an assign path
- Fixed an error with the codesets plugin, where an empty file could
  not be opened
- Improved the folder suggestions when opening projects or changing paths.
  Now even the root folders of a partition are presented
- Fixed ghmarkdown plugin, but now requires a GitHub token to be provided

## [2.1.2r1] - 2023-12-19
### Added
- Added the new experimental codesets plugin (AmigaOS4 version only).
  MorphOS version is in WIP

### Changed
- Synced with the latest upstream v2.1.2 code
- Compiled with gcc 11.3.0
- Compiled with SDL 2.28.4
- Compiled with libfreetype 2.13.x
- Compiled with lua 5.4.6
- Compiled with linpng 1.6.40 (AmigaOS4 version only)
- Compiled with libz 1.2.13 (AmigaOS4 version only)

## [2.1.1r2] - 2022-05-14
### Changed
- Compiled with latest SDL v2.26.5-rc2

## [2.1.1r1] - 2022-01-29
### Changed
- Binary name changed to lite-xl
- Updated the colour themes and the plugins that are included in the release
- Compiled with latest SDL 2.26
- Compiled with gcc 11
- Synced the code with the upstream master branch at 8th January 2023

### Fixed
- Set the default locale on AmigaOS 4, so as to fix some issues with decimal
  numbers

## [2.1.0r1] - 2022-10-10
### Added
- This version of LiteXL recognises changes that are done outside the editor
  in files and folders, and updates the items when it gets focus again.

### Changed
- Synced the code with the latest upstream master branch, which means that
  this version is based on the latest available source
- Now the plugins need to be version 3. The older versions will not work.
  All the included plugins are updated to the latest available version.
- Compiled with SDL 2.24
- Compiled with Lua 5.4

### Fixed
- Fixed regex issues with some plugins
- Fixed "Open in System" on AmigaOS 4 and MorphOS. When you right click
  at a file or a folder at the treeview at the left side, then depending
  the type of the item opens on Workbench. A folder opens in a list view
  and a file opens with its default tool
- Fixed markdown preview on MorphOS. Now, it calls openurl with the html
  file (#20)
- Fixed locale issues on MorphOS (again), since the previous fix didn't
  actually fixed the problem

## [2.0.3r3] - 2022-09-26
### Added
- Added plugin for AmigaGuide files
- Added plugin for Hollywood files

### Fixed
- Fixed non existing path crashes on OS4 and MorphOS
- Fixed editor refresh whenever init.lua is changed, no matter the working
  folder
- Fixed an issue when the user added a directory in the project that
  already existed
- Fixed locale issue on start for MorphOS. Now it should start just fine
  no matter what locale the user has on his system.
- Fixed "Find" on MorphOS that was not working (shortcut CTRL+F)
- If the user selects to change the project folder and inserts Sys: or any
  partition name, the included folders will be listed as suggestions

### Changed
- Removed linking with unix on OS4 build
- Makefiles updated

## [2.0.3r2] - 2022-06-18
### Added
- First public MorphOS version released

### Changed
- Merged source code for both AmigaOS 4 and MorphOS
- Moved the declaration of the $VER and $STACK for the AmigaOS 4 version,
  so to happen only once (reported by capehill)

### Fixed
- Fixed the usage of NumPad (reported by root)

## [2.0.3r1] - 2022-03-30
### Changed
- Applied all the necessary changes to make it run under AmigaOS 4.1 FE
- Fixes and changes

# Disclaimer
YOU MAY USE IT AT YOUR OWN RISK!
I will not be held responsible for any data loss or problems you might get
by using this software.