From 9a09adb63cc005f0f89fa2468d8eea859131ccb7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89rico=20Nogueira?= Date: Wed, 31 Mar 2021 00:19:13 -0300 Subject: [PATCH] Manual: add 80 column line break suggestion. Also: - rework most of the language in the Introduction - move note about special characters in pkgname or version - note restrictions to version field are caused partly by xbps-checkvers - fix indentation of 'maintainer' item --- Manual.md | 34 ++++++++++++++++++++-------------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/Manual.md b/Manual.md index 4439865e1d73..8c2afbaca71d 100644 --- a/Manual.md +++ b/Manual.md @@ -76,17 +76,19 @@ packages for XBPS, the `Void Linux` native packaging system. ## Introduction -The `void-packages` repository contains all `source` packages that are the -recipes to download, compile and build binary packages for `Void`. -Those `source` package files are called `templates`. +The `void-packages` repository contains all the +recipes to download, compile and build binary packages for Void Linux. +These `source` package files are called `templates`. -The `template files` are `GNU bash` shell scripts that must define some required/optional -`variables` and `functions` that are processed by `xbps-src` (the package builder) -to generate the resulting binary packages. +The `template` files are shell scripts that define `variables` and `functions` +to be processed by `xbps-src`, the package builder, to generate binary packages. +The shell used by `xbps-src` is GNU bash; `xbps-src` doesn't aim to be +compatible with POSIX `sh`. -By convention, all templates start with a comment briefly explaining what they -are. In addition, pkgname and version can't have any characters in them that -would require them to be quoted, so they are not quoted. +By convention, all templates start with a comment saying that it is a +`template file` for a certain package. Most of the lines should be kept under 80 +columns; variables that list many values can be split into new lines, with the +continuation in the next line indented by one space. A simple `template` example is as follows: @@ -447,10 +449,9 @@ Multiple licenses should be separated by commas, Example: `GPL-3.0-or-later, cus Note: `MIT`, `BSD`, `ISC` and custom licenses require the license file to be supplied with the binary package. -- `maintainer` A string in the form of `name `. The - email for this field must be a valid email that you can be reached - at. Packages using `users.noreply.github.com` emails will not be - accepted. +- `maintainer` A string in the form of `name `. The email for this field +must be a valid email that you can be reached at. Packages using +`users.noreply.github.com` emails will not be accepted. - `pkgname` A string with the package name, matching `srcpkgs/`. @@ -461,7 +462,12 @@ the generated `binary packages` have been modified. - `short_desc` A string with a brief description for this package. Max 72 chars. - `version` A string with the package version. Must not contain dashes or underscore -and at least one digit is required. Shell's variable substition usage is not allowed. +and at least one digit is required. Using bash's pattern substitution and prefix and +suffix matching isn't supported, since this field needs to be parsed by +`xbps-checkvers(1)`. Using variables in this field should be avoided. + +Neither `pkgname` or `version` should contain special characters which make it +necessary to quote them, so they shouldn't be quoted in the template. #### Optional variables