From f7ab3621bc44714aee11b938d5d8d46714476cac Mon Sep 17 00:00:00 2001 From: Ioannis Tsagkatakis Date: Fri, 21 Jun 2024 02:23:30 +0300 Subject: [PATCH] Generate manual with pandoc --- Justfile | 15 ++++- support/manpage/places.md | 135 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 147 insertions(+), 3 deletions(-) create mode 100644 support/manpage/places.md diff --git a/Justfile b/Justfile index 943beac..db8d517 100644 --- a/Justfile +++ b/Justfile @@ -13,9 +13,6 @@ lint: cargo fmt --all --check cargo fmt --all -# Publish to gitea -gitea: - git push gitea # Load version from Cargo.toml version := `sed -En 's/version[[:space:]]*=[[:space:]]*"([^"]+)"/\1/p' Cargo.toml | head -1` @@ -31,3 +28,15 @@ tag-version: # crate tag push it to origin and then publish to crates.io tag-and-publish: tag-version cargo publish + +# Create man page +gen-man: + cp support/manpage/places.md support/manpage/places.md.bk + sed -i.bk "s|footer: places |footer: lsd {{ version }}|" support/manpage/places.md + sed -i.bk "s|date: |date: $(date '+%Y-%m-%d')|" support/manpage/places.md + pandoc --standalone --to man support/manpage/places.md -o support/manpage/places.1 + cp support/manpage/places.md.bk support/manpage/places.md + rm support/manpage/places.md.bk + +man: gen-man + man support/manpage/places.1 \ No newline at end of file diff --git a/support/manpage/places.md b/support/manpage/places.md new file mode 100644 index 0000000..47cceda --- /dev/null +++ b/support/manpage/places.md @@ -0,0 +1,135 @@ +--- +title: places +section: 1 +header: User Manual +footer: lsd 0.1.0 +date: +--- + +# NAME + +places - Get paths for common places + +# SYNOPSIS + +**places** \[**OPTIONS**] <**location**> \[**pathel**]... + +# DESCRIPTION +A handy tool for your scripts to always get correct path names for known locations. +Sometimes the location is changed by either ENVIRONMENT variables, or by user localization. +Using this tool you always get the correct path. + +## MOTIVATION +Let's say you want to find the desktop and the download directory. +Without this tool you have to do something like: + +```shell +test -f ${XDG_CONFIG_HOME:-~/.config}/user-dirs.dirs && \ + source ${XDG_CONFIG_HOME:-~/.config}/user-dirs.dirs +echo ${XDG_DESKTOP_DIR:-$HOME/Desktop} +echo ${XDG_DOWNLOAD_DIR:-$HOME} +``` + +with _places_ it becomes: + +```shell +places desktop +places downloads +``` + +Ah, much better + +## EXAMPLES + +But you can do much more with it + +### * Get a path like: _/home/alice/.config/gizmo/theme/colors.txt_ + **\$** places -a gizmo config theme colors.txt \ + **\$** places config gizmo theme colors.txt + +### * List all config files for the _'gizmo'_ program + + **\$** lsd $(places --app=gizmo data) \ + **\$** places --app=gizmo data | xargs lsd + +### * Copy a config file + **\$** cp gizmo_config.toml $(places -a gizmo config) + + +### * Get a folder inside `'Downloads dir'`, even if it is localized. + **\$** places downloads Software + + This returns something like _/home/alice/Descargas/Software_ + + +# ARGUMENTS + `` +: The location. See table bellow for a list of known locations. + + +`[pathel]...` +: Optional list of path elements to append + +# OPTIONS + +`-a`, `--app` +: Optional program to get paths + +`-h`, `--help` +: Print help (see a summary with `-h`) + +`-V`, `-version` +: Print version + +# LOCATION TABLE +The following is the list of known locations + +### **XDG** locations + +| name | environment var | example | +|---------------|----------------------|-------------------------| +| **home** | $HOME | _/home/alice_ | +| **desktop** | $XDG_DESKTOP_DIR | _/home/alice/Desktop_ | +| **downloads** | $XDG_DOWNLOAD_DIR | _/home/alice/Downloads_ | +| **templates** | $XDG_TEMPLATES_DIR | _/home/alice/Templates_ | +| **documents** | $XDG_DOCUMENTS_DIR | _/home/alice/Documents_ | +| **pictures** | $XDG_PICTURES_DIR | _/home/alice/Pictures_ | +| **videos** | $XDG_VIDEOS_DIR | _/home/alice/Videos_ | +| **music** | $XDG_MUSIC_DIR | _/home/alice/Music_ | +| **public** | $XDG_PUBLICSHARE_DIR | _/home/alice/Public_ | + +### Common locations + + +| name | environment var | example | +|------------|------------------|----------------------------| +| **config** | $XDG_CONFIG_HOME | _/home/alice/.config_ | +| **bin** | $XDG_BIN_HOME | _/home/alice/.local/bin_ | +| **cache** | $XDG_CACHE_HOME | _/home/alice/.cache_ | +| **state** | $XDG_STATE_HOME | _/home/alice/.state_ | +| **data** | $XDG_DATA_HOME | _/home/alice/.local/share_ | + +### Other locations +Note the tool always return a full path, not paths starting with _'~/'_. + +| name | example | +|-----------------|-------------------------------| +| **autostart** | _~/.config/autostart_ | +| **fonts** | _~/.local/share/fonts_ | +| **menus** | _~/.local/share/applications_ | +| **backgrounds** | _~/.local/share/backgrounds_ | + + +# ENVIRONMENT +The list of environment variables that affect the operation is listed on the tables above. + +The **XDG** localized names is defined in the file _/etc/xdg/user-dirs.defaults_ and for each user +in the file _$(XDG_CONFIG_HOME)/user-dirs.dirs_. + + +# BUGS + +See GitHub Issues: _https://github.com/jtsagata/places-cli/issues_ + +# SEE ALSO +**xdg-user-dir(1)**, **user-dirs.dirs(5)**