From 4d4c3cd04f00acb73b3c695784de63452e113ba7 Mon Sep 17 00:00:00 2001 From: yannickmoy Date: Thu, 14 May 2020 19:16:40 +0200 Subject: [PATCH] docs: minor fixes and adding links (#409) --- doc/catalog-format-spec.md | 33 ++++++++++++++++++--------------- doc/getting-started.md | 12 ++++++------ doc/policies.md | 8 ++++---- doc/publishing.md | 4 ++-- 4 files changed, 30 insertions(+), 27 deletions(-) diff --git a/doc/catalog-format-spec.md b/doc/catalog-format-spec.md index 91e38d89..e0044461 100644 --- a/doc/catalog-format-spec.md +++ b/doc/catalog-format-spec.md @@ -58,8 +58,8 @@ libbar = "^2.0 & /=2.1.3" # Excluding a known bad version In some contexts, information can be dynamic: special encodings can be used to make data vary depending on the environment (OS, architecture, ...). The environment is represented as a set of specific variables which can have a -specific set of values: see the Parameters section below for a comprehensive -list. +specific set of values: see the [Parameters](#parameters) section below for a +comprehensive list. To create atomic values in an environment-dependent way, use the following construct (here to create a boolean): @@ -105,6 +105,9 @@ libwinbar = "^3.0" ['case(os)'.'...'] ``` +The `case(os)` part selects dependencies depending on the value of the `os` +environment variable. + If the `os` environment variable contains `linux`, this will create the following dependencies: @@ -113,8 +116,8 @@ libfoo = "^1.2" libbar = "^2.0" ``` -The `case(os)` part selects dependencies depending on the value of the `os` -environment variable. +If the `os` environment variable contains `windows`, this will create the +following dependencies: ```toml libfoo = "^1.2" @@ -204,7 +207,7 @@ entries: ``` - `tags`: optional array of strings. Flat list of topics covered by the crate. - Tags will help users find crates reletaed to their interests: + Tags will help users find crates related to their interests: ```toml tags = ["spark", "security"] @@ -344,7 +347,7 @@ entries: # An explicit empty case alternative, which is not mandatory ``` -## Release-specific Information +## Release-specific information Each release is materialized as an entry in the top-level object. The key is a string for the version number for the release, while the value is an object to @@ -363,7 +366,7 @@ following entries: ``` If the package only maps a package from the system package manager, - (for instance `make`), run: + (for instance `make`), use: ```toml origin = "native:make" @@ -380,7 +383,7 @@ following entries: - `origin-hashes`: mandatory string array for git origins and source archives. An array of "kind:digest" fields that specify a hash kind and its value. - Kinds accepted are: sha512. + Kinds accepted are: `sha512`. - `archive-name`: optional string. If `origin` points to a source archive, this can specifiy the name of the file to download, which is needed in order @@ -392,7 +395,7 @@ following entries: archive-hash = "sha512:bf6082573dc537836ea8506a2c9a75dc7837440c35c5b02a52add52e38293640d99e90a9706690591f8899b8b4935824b195f230b3aa1c4da10911e3caf954c04ac" ``` - - `available`: optional dynamic boolean expression. It is used the + - `available`: optional dynamic boolean expression. It is used in the following way: 1. If it evaluates to `false`, the package is not available for the current @@ -405,7 +408,7 @@ following entries: release. For instance: ```json - "notes": "Experimental version" + notes = "Experimental version" ``` It can also contain the following entries: `depends-on`, `project-files`, @@ -414,7 +417,7 @@ optional. For atomic values, these override the ones from `general`, and for lists/mappings, they are interpreted as additions. In the latter case, conflicting entries are considered as errors. -## External Releases +## External releases The above information applies to regular releases distributed from sources (that is, the Ada projects whose distribution is the main Alire goal). Some @@ -441,9 +444,9 @@ All external kinds can define these regular properties: environment conditions. - `hint`: explanation for the user on how to make the external available. This - explanation is show on request with `alr show --external`, or after `alr - get`, for any external dependency that could not be detected. This property - accepts dynamic expressions. + explanation is shown on request with `alr show --external`, or after + `alr get`, for any external dependency that could not be detected. This + property accepts dynamic expressions. ### External kinds: hints @@ -481,7 +484,7 @@ version-regexp = "^GNAT ([\\d\\.]+).*|^GNAT Community ([\\d]{4}).*" Systems that have their own package manager (e.g. Linux) can readily provide many complex dependencies still unpackaged as source code in Alire. Alire can use these on supported platforms (at this time, Debian & Ubuntu. Do not -hesitate to contact us if you would like to maintain other ones distributions) +hesitate to contact us if you would like to maintain other distributions) during resolution. A system external gives a list of platform package names that supply the diff --git a/doc/getting-started.md b/doc/getting-started.md index 6090ce9f..3784b3af 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -26,7 +26,7 @@ The executable will be found in `bin/alr`. You can add it to your PATH: * Linux/MacOS: `export PATH=$PATH:$PWD/bin` * Windows PowerShell: `$env:path += ";$pwd/bin"` -## `Alr` on Windows +## `alr` on Windows On Windows, the first time you run `alr` the program will ask if you want to install [msys2](https://www.msys2.org/). This is recommended as `alr` will use @@ -69,7 +69,7 @@ program in one step. Alire allows you to initialize an empty GNAT binary or library project with ease: -1. Issue `alr init --bin myproj` (you can use --lib for a library project). +1. Issue `alr init --bin myproj` (you can use `--lib` for a library project) 1. Enter the folder: `cd myproj` 1. Check that it builds: `alr build` 1. Run it: `alr run` @@ -77,7 +77,7 @@ ease: ## Dependencies and upgrading Alire keeps track of a project dependencies in the file -`./alire/project_name.toml` file of your project. You may check the one just +`./alire/project_name.toml` of your project. You may check the one just created in the previous example. This file can be managed through `alr`: @@ -100,12 +100,12 @@ and then issue: ## Finding available projects -For quick listing of projects and its description you can use the `list` +For quick listing of projects and their descriptions you can use the `list` command: * `alr list [substring]` -There's also a search command which provides more details: +There's also a `search` command which provides more details: * `alr search ` will look for `substring` in project names. * `alr search --list` will list the whole catalog. @@ -128,7 +128,7 @@ website: To create a build environment, `alr` sets environment variables such as `GPR_PROJECT_PATH` before running `gprbuild`. If you want to run `gprbuild` -yourself or inside an editor (GNATstudio), you can use the `setenv` command to +yourself or inside an editor (GNAT Studio), you can use the `setenv` command to print the build environment: * `alr setenv` diff --git a/doc/policies.md b/doc/policies.md index ad4b0217..48d75a42 100644 --- a/doc/policies.md +++ b/doc/policies.md @@ -1,9 +1,9 @@ -# policies +# Policies ## Crate ownership Because Alire comes late in the history of the Ada and SPARK languages we will -not apply a strict first come, first served policy on crates name. At least for +not apply a strict "first come, first served" policy on crates name. At least for the first months or years, we allow ourselves a form of moderation on the projects/crates published in the index with the following goals: @@ -15,7 +15,7 @@ projects/crates published in the index with the following goals: regards to the project they contain. For instance, do not try to impersonate existing crates or projects. -To that extent we will potentially reject a create or transfer the ownership of +To that extent we will potentially reject a crate or transfer the ownership of a crate. We count on the goodwill of the contributors to help us conduct this moderation @@ -23,7 +23,7 @@ in a kind and courteous way. Do not submit a crate to the Alire index if you are not willing to comply with this policy. As the Alire project matures, we expect to do less moderation and potentially -remove this policy in favor of a first come, first served policy. +remove this policy in favor of a "first come, first served" policy. ## Release immutability diff --git a/doc/publishing.md b/doc/publishing.md index abd335d1..690a48c0 100644 --- a/doc/publishing.md +++ b/doc/publishing.md @@ -95,8 +95,8 @@ be edited instead of created). through the GitHub web interface (or the [`hub`](https://github.com/github/hub) tool). 1. The base branch you select for the pull request will determine where - your changes will become available; see the section on index - branches for details. + your changes will become available; see the section on [index + branches](#index-branches) for details. Once the pull request is verified and merged, the new crate or release will become available for normal use. The open source Ada ecosystem needs all the -- 2.39.5