From 292052ecf7f34cd7a2294cb52535de54655585e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20M=C3=BCller?= Date: Fri, 26 Mar 2021 14:11:37 +0100 Subject: [PATCH] Improve manpage format * Use title case for headlines (automatically transformed to uppercase in manpage transform) * Uniformly use bold text for code highlights (backticks do not work) --- docs/shard.yml.adoc | 112 ++++++++++++++++----------------- docs/shards.adoc | 146 ++++++++++++++++++++++---------------------- man/shard.yml.5 | 10 +-- man/shards.1 | 128 ++++++++++++++++++-------------------- 4 files changed, 195 insertions(+), 201 deletions(-) diff --git a/docs/shard.yml.adoc b/docs/shard.yml.adoc index 62e80540..e464c91c 100644 --- a/docs/shard.yml.adoc +++ b/docs/shard.yml.adoc @@ -4,28 +4,28 @@ :man manual: File Formats :man source: shards {shards_version} -== NAME -shard.yml - metadata for projects managed by shards(1) +== Name +shard.yml - metadata for projects managed by *shards*(1) -== DESCRIPTION +== Description -The file _shard.yml_ is a YAML file with metadata about a project managed by shards, known as a *shard*. It must contain at least _name_ and _version_ attributes plus optional additional attributes. +The file *shard.yml* is a YAML file with metadata about a project managed by shards, known as a *shard*. It must contain at least _name_ and _version_ attributes plus optional additional attributes. -Both libraries and applications will benefit from `shard.yml`. +Both libraries and applications will benefit from *shard.yml*. The metadata for libraries are expected to have more information (e.g., list of authors, description, license) than applications that may only have a name, version and dependencies. -== FORMAT +== Format -The file must be named _shard.yml_ and be a valid YAML file with UTF-8 encoding. +The file must be named *shard.yml* and be a valid YAML file with UTF-8 encoding. It must not contain duplicate attributes in any mapping. It should use an indent of 2 spaces. It should not use advanced YAML features, only simple mappings, sequences and strings (Failsafe Schema). -== REQUIRED ATTRIBUTES +== Required Attributes *name*:: The name of the project (string, required). + @@ -33,7 +33,7 @@ strings (Failsafe Schema). - It must be unique. - It must be 50 characters or less. - It should be lowercase (a-z). -- It should not contain _crystal_. +- It should not contain *crystal*. - It may contain digits (0-9) but not start with one. - It may contain underscores or dashes but not start/end with one. - It must not have consecutive underscores or dashes. @@ -56,13 +56,13 @@ While Shards doesn't enforce it, following a rational versioning scheme like http://semver.org/[Semantic Versioning] or http://calver.org/[Calendar Versioning] is highly recommended. -== OPTIONAL ATTRIBUTES +== Optional Attributes *authors*:: A list of authors, along with their contact email (optional) (sequence of string). + -- - Each author must have a name. -- Each author may have an email address, within angle bracket (_<_ and _>_) +- Each author may have an email address, within angle bracket (*<* and *>*) chars. -- + @@ -80,22 +80,22 @@ A restriction to indicate which are the supported crystal versions. This will usually express a lower and upper-bound constraints (string, recommended) + When resolving dependencies, only the versions that comply with the current -crystal will be candidates. You can pass _--ignore-crystal-version_ to disregard this +crystal will be candidates. You can pass *--ignore-crystal-version* to disregard this behavior. + -The valid values are the same as for _dependencies.version_: +The valid values are the same as for *dependencies.version*: + -- * It may be a version number. -* It may be _"*"_ if any version will do. -* The version number may be prefixed by an operator: _<_, _<=_, _>_, _>=_ or _~>_. +* It may be *"*"* if any version will do. +* The version number may be prefixed by an operator: *<*, *<=*, *>*, *>=* or *~>*. * Multiple requirements can be separated by commas. -- + When just a version number is used it has a different semantic compared to dependencies: -_x.y.z_ will be interpreted as _~> x.y, >= x.y.z_ (ie: _>= x.y.z, < (x+1).0.0_) honoring semver. +*x.y.z* will be interpreted as *~> x.y, >= x.y.z* (ie: *>= x.y.z, < (x+1).0.0*) honoring semver. + -NOTE: If this property is not included it is treated as _< 1.0.0_. +NOTE: If this property is not included it is treated as *< 1.0.0*. + *Example:* + @@ -150,11 +150,11 @@ The URL to a website providing the project's documentation for online browsing ( A list of executables to be installed (sequence). + The executables can be of any type or language (e.g., shell, binary, ruby), must -exist in the _bin_ folder of the Shard, and have the executable bit set (on +exist in the *bin/* folder of the Shard, and have the executable bit set (on POSIX platforms). When installed as a dependency for another project the -executables will be copied to the _bin_ folder of that project. +executables will be copied to the *bin/* folder of that project. + -Executables are always installed last, after the _postinstall_ script is run, so +Executables are always installed last, after the *postinstall* script is run, so libraries can build the executables when they are installed by Shards. + *Example:* @@ -180,15 +180,15 @@ libraries that are only referenced by dependencies. It must include all librarie it directly links to, regardless of a dependency doing it too. + It should map from the soname without any extension, path or version, -for example _libsqlite3_ for _/usr/lib/libsqlite3.so.0.8.6_, to a version +for example *libsqlite3* for */usr/lib/libsqlite3.so.0.8.6*, to a version constraint. + The version constraint has the following format: + -- - It may be a version number. -- It may be _"*"_ if any version will do. -- The version number may be prefixed by an operator: _<_, _<=_, _>_, _>=_ or _~>_. +- It may be *"*"* if any version will do. +- The version number may be prefixed by an operator: *<*, *<=*, *>*, *>=* or *~>*. -- + [source,yaml] @@ -207,7 +207,7 @@ libraries: The URL of the project's canonical repository (string, recommended). + The URL should be compatible with typical VCS tools without modifications. -_http_/_https_ is preferred over VCS schemes like _git_. +*http*/*https* is preferred over VCS schemes like *git*. It is recommended that this URL is publicly available. + Copies of a shard (such as mirrors, development forks etc.) should point to the same @@ -221,18 +221,18 @@ repository: "https://github.com/crystal-lang/shards" ---- *scripts*:: - Script hooks to run. Only _postinstall_ is supported. + Script hooks to run. Only *postinstall* is supported. + Shards may run scripts automatically after certain actions. The scripts themselves are mere shell commands. *postinstall*::: -The _postinstall_ hook of a dependency will be run whenever that dependency is +The *postinstall* hook of a dependency will be run whenever that dependency is installed or upgraded in a project that requires it. This may be used to compile a C library, to build tools to help working on the project, or anything else. + The script will be run from the dependency's installation directory, for example -_lib/foo_ for a Shard named _foo_. +*lib/foo* for a Shard named *foo*. + *Example:* + @@ -247,7 +247,7 @@ A list of targets to build (mapping). + Each target begins with the name of the target as a key (string), then a list of attributes (mapping). The target name is the built binary name, created in the -_bin_ folder of the project. +*bin/* folder of the project. + *Example:* + @@ -260,22 +260,22 @@ targets: main: src/worker.cr ---- + -The above example will build _bin/server_ from _src/server/cli.cr_ and -_bin/worker_ from _src/worker.cr_. +The above example will build *bin/server* from *src/server/cli.cr* and +*bin/worker* from *src/worker.cr*. *main*::: A path to the source file to compile (string). -== DEPENDENCY ATTRIBUTES +== Dependency Attributes Each dependency needs at least one attribute that defines the resolver for this -dependency. Those can be _path_, _git_, _github_, _gitlab_, _bitbucket_. +dependency. Those can be *path*, *git*, *github*, *gitlab*, *bitbucket*. *path*:: A local path (string). + The library will be installed as a symlink to the local path. -The _version_ attribute isn't required but will be used if present to validate +The *version* attribute isn't required but will be used if present to validate the dependency. *git*:: @@ -285,56 +285,56 @@ The URL may be [any protocol](https://git-scm.com/docs/git-clone#_git_urls) supported by Git, which includes SSH, GIT and HTTPS. + The Git repository will be cloned, the list of versions (and associated -_shard.yml_) will be extracted from Git tags (e.g., _v1.2.3_). +*shard.yml*) will be extracted from Git tags (e.g., _v1.2.3_). + -One of the other attributes (_version_, _tag_, _branch_ or _commit_) is +One of the other attributes (*version*, *tag*, *branch* or *commit*) is required. When missing, Shards will install the HEAD refs. + -*Example:* _git: git://git.example.org/crystal-library.git_ +Example: *git: git://git.example.org/crystal-library.git* *github*:: -GitHub repository URL as _user/repo_ (string) +GitHub repository URL as *user/repo* (string) + -Extends the _git_ resolver, and acts exactly like it. +Extends the *git* resolver, and acts exactly like it. + -*Example:* _github: ysbaddaden/minitest.cr_ +Example: *github: ysbaddaden/minitest.cr* *gitlab*:: -GitLab repository URL as _user/repo_ (string). +GitLab repository URL as *user/repo* (string). + -Extends the _git_ resolver, and acts exactly like it. +Extends the *git* resolver, and acts exactly like it. + -Only matches dependencies hosted on _gitlab.com_. For personal GitLab -installations, you must use the generic _git_ resolver. +Only matches dependencies hosted on *gitlab.com*. For personal GitLab +installations, you must use the generic *git* resolver. + -*Example:* _gitlab: thelonlyghost/minitest.cr_ +Example: *gitlab: thelonlyghost/minitest.cr* *bitbucket*:: -Bitbucket repository URL as _user/repo_ (string). +Bitbucket repository URL as *user/repo* (string). + -Extends the _git_ resolver, and acts exactly like it. +Extends the *git* resolver, and acts exactly like it. + -*Example:* _bitbucket: tom/library_ +*Example:* *bitbucket: tom/library* *version*:: A version requirement (string). + -- - It may be an explicit version number. -- It may be _"*"_ wildcard if any version will do (this is the default). +- It may be *"*"* wildcard if any version will do (this is the default). Shards will then install the latest tagged version (or HEAD if no tagged version available). -- The version number may be prefixed by an operator: _<_, _<=_, _>_, _>=_ or _~>_. +- The version number may be prefixed by an operator: *<*, *<=*, *>*, *>=* or *~>*. - Multiple requirements can be separated by commas. -- + Examples: _1.2.3_, _>= 1.0.0_, _>= 1.0.0, < 2.0_ or _~> 2.0_. + -Most of the version operators, like _>= 1.0.0_, are self-explanatory, but -the _~>_ operator has a special meaning, best shown by example: +Most of the version operators, like *>= 1.0.0*, are self-explanatory, but +the *~>* operator has a special meaning, best shown by example: -- -- _~> 2.0.3_ is identical to _>= 2.0.3 and < 2.1_; -- _~> 2.1_ is identical to _>= 2.1 and < 3.0_. +- *~> 2.0.3* is identical to *>= 2.0.3 and < 2.1*; +- *~> 2.1* is identical to *>= 2.1 and < 3.0*. -- *branch*:: @@ -348,7 +348,7 @@ the _~>_ operator has a special meaning, best shown by example: == Example: -Here is an example _shard.yml_ for a library named _shards_ at version _1.2.3_ +Here is an example *shard.yml* for a library named *shards* at version *1.2.3* with some dependencies: [source,yaml] @@ -385,8 +385,8 @@ targets: main: src/shards.cr ---- -== AUTHOR +== Author Written by Julien Portalier and the Crystal project. -== SEE ALSO +== See Also *shards*(1) diff --git a/docs/shards.adoc b/docs/shards.adoc index c283a95f..cb8aee3a 100644 --- a/docs/shards.adoc +++ b/docs/shards.adoc @@ -4,26 +4,26 @@ :man manual: Shards Manual :man source: shards {shards_version} -== NAME +== Name shards - dependency manager for the Crystal Language -== SYNOPSIS -*shards* [__...] [__] [__...] +== Synopsis +*shards [...] [] [...]* -== DESCRIPTION +== Description Manages dependencies for Crystal projects and libraries with reproducible installs across computers and systems. -== USAGE -_shards_ requires the presence of a _shard.yml_ file in the project +== Usage +_shards_ requires the presence of a *shard.yml* file in the project folder (working directory). This file describes the project and lists dependencies that are required to build it. See *shard.yml*(5) for more -information on its format. A default file can be created by running _shards init_. +information on its format. A default file can be created by running *shards init*. -Running _shards install_ resolves and installs the +Running *shards install* resolves and installs the specified dependencies. The installed versions are written into a *shard.lock* file for using the exact same dependency versions when -running _shards install_ again. +running *shards install* again. If your shard builds an application, both *shard.yml* and *shard.lock* should be checked into version control to provide reproducible @@ -32,154 +32,154 @@ If it is only a library for other shards to depend on, *shard.lock* should _not_ be checked in, only *shard.yml*. It’s good advice to add it to *.gitignore*. -== COMMANDS +== Commands If no _command_ is given, *install* command will be run by default. -To see the available options for a particular command, use _--help_ after the command. +To see the available options for a particular command, use *--help* after the command. -*build* [__] [__...]:: -Builds the specified __ in *bin* path. If no targets are specified, +*build [] [...]*:: +Builds the specified *targets* in *bin/* path. If no targets are specified, all are built. This command ensures all dependencies are installed, so it is not necessary to run *shards install* before. + -All __ following the command are delegated to *crystal build*. +All *build_options* following the command are delegated to *crystal build*. *check*:: Verifies that all dependencies are installed and requirements are satisfied. + Exit status: + -[horizontal] -*0*::: Dependencies are satisfied. -*1*::: Dependencies are not satisfied. +*0*: Dependencies are satisfied. ++ +*1*: Dependencies are not satisfied. *init*:: -Initializes a default _shard.yml_ in the current folder. +Initializes a default *shard.yml* in the current folder. -*install* [--frozen] [--without-development] [--production] [--skip-postinstall]:: -Resolves and installs dependencies into the _lib_ folder. If not already -present, generates a _shard.lock_ file from resolved dependencies, locking +*install [--frozen] [--without-development] [--production] [--skip-postinstall]*:: +Resolves and installs dependencies into the *lib/* folder. If not already +present, generates a *shard.lock* file from resolved dependencies, locking version numbers or Git commits. + -Reads and enforces locked versions and commits if a _shard.lock_ file is +Reads and enforces locked versions and commits if a *shard.lock* file is present. The *install* command may fail if a locked version doesn't match a requirement, but may succeed if a new dependency was added, as long as it -doesn't generate a conflict, thus generating a new _shard.lock_ file. +doesn't generate a conflict, thus generating a new *shard.lock* file. + -- ---frozen:: Strictly installs locked versions from _shard.lock_. Fails if _shard.lock_ is missing. ---without-development:: Does not install development dependencies. ---production:: same as _--frozen_ and _--without-development_ ---skip-postinstall:: Does not run postinstall of dependencies. +*--frozen*:: Strictly installs locked versions from *shard.lock*. Fails if *shard.lock* is missing. +*--without-development*:: Does not install development dependencies. +*--production*:: same as _--frozen_ and _--without-development_ +*--skip-postinstall*:: Does not run postinstall of dependencies. -- -*list* [--tree]:: +*list [--tree]*:: Lists the installed dependencies and their versions. + -Specifying _--tree_ arranges nested dependencies in a tree, instead of a flattened list. +Specifying *--tree* arranges nested dependencies in a tree, instead of a flattened list. -*lock* [--update [...]]:: -Resolves dependencies and creates or updates the _shard.lock_ file as per +*lock [--update [...]]*:: +Resolves dependencies and creates or updates the *shard.lock* file as per the *install* command, but never installs the dependencies. + -Specifying _--update_ follows the same semantics as the *update* +Specifying *--update* follows the same semantics as the *update* command. -*outdated* [--pre]:: +*outdated [--pre]*:: Lists dependencies that are outdated. + -When _--pre_ is specified, pre-release versions are also considered. +When *--pre* is specified, pre-release versions are also considered. *prune*:: -Removes unused dependencies from _lib_ folder. +Removes unused dependencies from *lib/* folder. -*update* [...]:: -Resolves and updates all dependencies into the _lib_ folder, -whatever the locked versions in the _shard.lock_ file. -Eventually generates a new _shard.lock_ file. +*update [...]*:: +Resolves and updates all dependencies into the *lib/* folder, +whatever the locked versions in the *shard.lock* file. +Eventually generates a new *shard.lock* file. + Specifying _shards_ will update these dependencies only, trying to be as conservative as possible with other dependencies, respecting the locked versions -in the _shard.lock_ file. +in the *shard.lock* file. -*version* [__]:: -Prints the current version of the shard located at _path_ (defaults to current +*version []*:: +Prints the current version of the shard located at *path* (defaults to current directory). To see the available options for a particular command, use *--help* after a command. -== GENERAL OPTIONS +== General Options ---version:: +*--version*:: Prints the version of _shards_. --h, --help:: +*-h*, *--help*:: Prints usage synopsis. ---no-color:: +*--no-color*:: Disables colored output. ---local:: +*--local*:: Don't update remote repositories, use the local cache only. ---ignore-crystal-version:: +*--ignore-crystal-version*:: Do not enforce crystal version restrictions on shards. --q, --quiet:: +*-q*, *--quiet*:: Decreases the log verbosity, printing only warnings and errors. --v, --verbose:: +*-v*, *--verbose*:: Increases the log verbosity, printing all debug statements. -== INSTALLATION +== Installation Shards is usually distributed with Crystal itself. Alternatively, a separate _shards_ package may be available for your system. To install from source, download or clone https://github.com/crystal-lang/shards[the repository] and run -*make CRFLAGS=--release*. The compiled binary is in _bin/shards_ and +*make CRFLAGS=--release*. The compiled binary is in *bin/shards* and should be added to *PATH*. -== Environment variables +== Environment Variables -SHARDS_OPTS:: +*SHARDS_OPTS*:: Allows general options to be passed in as environment variable. -*Example*: _SHARDS_OPTS="--ignore-crystal-version" shards update_ +*Example*: *SHARDS_OPTS="--ignore-crystal-version" shards update* -SHARDS_CACHE_PATH:: +*SHARDS_CACHE_PATH*:: Defines the cache location. In this folder, shards stores local copies of remote repositories. -Defaults to _.cache/shards_ in the home directory (_$XDG_CACHE_HOME_ or _$HOME_) +Defaults to *.cache/shards* in the home directory (*$XDG_CACHE_HOME* or *$HOME*) or the current directory. -SHARDS_INSTALL_PATH:: +*SHARDS_INSTALL_PATH*:: Defines the location where dependecies are installed. -Defaults to _lib_. +Defaults to *lib/*. -SHARDS_BIN_PATH:: +*SHARDS_BIN_PATH*:: Defines the location where executables are installed. -Defaults to _bin_. +Defaults to *bin/*. -CRYSTAL_VERSION:: +*CRYSTAL_VERSION*:: Defines the crystal version that dependencies should be resolved against. -Defaults to the output of _crystal env CRYSTAL_VERSION_. +Defaults to the output of *crystal env CRYSTAL_VERSION*. -SHARDS_OVERRIDE:: -Defines the location of _shard.override.yml_. +*SHARDS_OVERRIDE*:: +Defines the location of *shard.override.yml*. == Files -shard.yml:: +*shard.yml*:: Describes a shard project including its dependencies. See *shard.yml*(5) for documentation. -shard.override.yml:: -Local overrides to _shard.yml_. +*shard.override.yml*:: +Local overrides to *shard.yml*. -shard.lock:: +*shard.lock*:: Lockfile that stores information about the installed versions. + If your shard builds an application, *shard.lock* should be checked into version @@ -188,12 +188,12 @@ control to provide reproducible dependency installs. If it is only a library for other shards to depend on, *shard.lock* should _not_ be checked in, only *shard.yml*. It’s good advice to add it to *.gitignore*. -== REPORTING BUGS +== Reporting Bugs Report shards bugs to Crystal Language home page: -== COPYRIGHT +== Copyright Copyright © {localyear} Julien Portalier. http://www.apache.org/licenses/LICENSE-2.0[License Apache 2.0] @@ -201,8 +201,8 @@ http://www.apache.org/licenses/LICENSE-2.0[License Apache 2.0] This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. -== AUTHORS +== Authors Written by Julien Portalier and the Crystal project. -== SEE ALSO +== See Also *shard.yml*(5) diff --git a/man/shard.yml.5 b/man/shard.yml.5 index b3555f09..4b54a755 100644 --- a/man/shard.yml.5 +++ b/man/shard.yml.5 @@ -28,10 +28,10 @@ . LINKSTYLE blue R < > .\} .SH "NAME" -shard.yml \- metadata for projects managed by shards(1) +shard.yml \- metadata for projects managed by *shards*(1) .SH "DESCRIPTION" .sp -The file \fIshard.yml\fP is a YAML file with metadata about a project managed by shards, known as a \fBshard\fP. It must contain at least \fIname\fP and \fIversion\fP attributes plus optional additional attributes. +The file \fBshard.yml\fP is a YAML file with metadata about a project managed by shards, known as a \fBshard\fP. It must contain at least \fIname\fP and \fIversion\fP attributes plus optional additional attributes. .sp Both libraries and applications will benefit from \f(CRshard.yml\fP. .sp @@ -40,7 +40,7 @@ authors, description, license) than applications that may only have a name, vers dependencies. .SH "FORMAT" .sp -The file must be named \fIshard.yml\fP and be a valid YAML file with UTF\-8 encoding. +The file must be named \fBshard.yml\fP and be a valid YAML file with UTF\-8 encoding. It must not contain duplicate attributes in any mapping. It should use an indent of 2 spaces. It should not use advanced YAML features, only simple mappings, sequences and @@ -561,7 +561,7 @@ The URL may be [any protocol](\c supported by Git, which includes SSH, GIT and HTTPS. .sp The Git repository will be cloned, the list of versions (and associated -\fIshard.yml\fP) will be extracted from Git tags (e.g., \fIv1.2.3\fP). +\fBshard.yml\fP) will be extracted from Git tags (e.g., \fIv1.2.3\fP). .sp One of the other attributes (\fIversion\fP, \fItag\fP, \fIbranch\fP or \fIcommit\fP) is required. When missing, Shards will install the HEAD refs. @@ -693,7 +693,7 @@ Install the specified tag of a git dependency (string). .RE .SH "EXAMPLE:" .sp -Here is an example \fIshard.yml\fP for a library named \fIshards\fP at version \fI1.2.3\fP +Here is an example \fBshard.yml\fP for a library named \fIshards\fP at version \fI1.2.3\fP with some dependencies: .sp .if n .RS 4 diff --git a/man/shards.1 b/man/shards.1 index d0392a0f..d986650d 100644 --- a/man/shards.1 +++ b/man/shards.1 @@ -31,22 +31,22 @@ shards \- dependency manager for the Crystal Language .SH "SYNOPSIS" .sp -\fBshards\fP [\fI\fP...] [\fI\fP] [\fI\fP...] +\fBshards [...] [] [...]\fP .SH "DESCRIPTION" .sp Manages dependencies for Crystal projects and libraries with reproducible installs across computers and systems. .SH "USAGE" .sp -\fIshards\fP requires the presence of a \fIshard.yml\fP file in the project +\fIshards\fP requires the presence of a \fBshard.yml\fP file in the project folder (working directory). This file describes the project and lists dependencies that are required to build it. See \fBshard.yml\fP(5) for more -information on its format. A default file can be created by running \fIshards init\fP. +information on its format. A default file can be created by running \fBshards init\fP. .sp -Running \fIshards install\fP resolves and installs the +Running \fBshards install\fP resolves and installs the specified dependencies. The installed versions are written into a \fBshard.lock\fP file for using the exact same dependency versions when -running \fIshards install\fP again. +running \fBshards install\fP again. .sp If your shard builds an application, both \fBshard.yml\fP and \fBshard.lock\fP should be checked into version control to provide reproducible @@ -58,16 +58,16 @@ advice to add it to \fB.gitignore\fP. .sp If no \fIcommand\fP is given, \fBinstall\fP command will be run by default. .sp -To see the available options for a particular command, use \fI\-\-help\fP after the command. +To see the available options for a particular command, use \fB\-\-help\fP after the command. .sp -\fBbuild\fP [\fI\fP] [\fI\fP...] +\fBbuild [] [...]\fP .RS 4 -Builds the specified \fI\fP in \fBbin\fP path. If no targets are specified, +Builds the specified \fBtargets\fP in \fBbin/\fP path. If no targets are specified, all are built. This command ensures all dependencies are installed, so it is not necessary to run \fBshards install\fP before. .sp -All \fI\fP following the command are delegated to \fBcrystal build\fP. +All \fBbuild_options\fP following the command are delegated to \fBcrystal build\fP. .RE .sp \fBcheck\fP @@ -76,96 +76,90 @@ Verifies that all dependencies are installed and requirements are satisfied. .sp Exit status: .sp -\fB0\fP -.RS 4 -Dependencies are satisfied. -.RE +\fB0\fP: Dependencies are satisfied. .sp -\fB1\fP -.RS 4 -Dependencies are not satisfied. -.RE +\fB1\fP: Dependencies are not satisfied. .RE .sp \fBinit\fP .RS 4 -Initializes a default \fIshard.yml\fP in the current folder. +Initializes a default \fBshard.yml\fP in the current folder. .RE .sp -\fBinstall\fP [\-\-frozen] [\-\-without\-development] [\-\-production] [\-\-skip\-postinstall] +\fBinstall [\-\-frozen] [\-\-without\-development] [\-\-production] [\-\-skip\-postinstall]\fP .RS 4 -Resolves and installs dependencies into the \fIlib\fP folder. If not already -present, generates a \fIshard.lock\fP file from resolved dependencies, locking +Resolves and installs dependencies into the \fBlib/\fP folder. If not already +present, generates a \fBshard.lock\fP file from resolved dependencies, locking version numbers or Git commits. .sp -Reads and enforces locked versions and commits if a \fIshard.lock\fP file is +Reads and enforces locked versions and commits if a \fBshard.lock\fP file is present. The \fBinstall\fP command may fail if a locked version doesn\(cqt match a requirement, but may succeed if a new dependency was added, as long as it -doesn\(cqt generate a conflict, thus generating a new \fIshard.lock\fP file. +doesn\(cqt generate a conflict, thus generating a new \fBshard.lock\fP file. .sp -\-\-frozen +\fB\-\-frozen\fP .RS 4 -Strictly installs locked versions from \fIshard.lock\fP. Fails if \fIshard.lock\fP is missing. +Strictly installs locked versions from \fBshard.lock\fP. Fails if \fBshard.lock\fP is missing. .RE .sp -\-\-without\-development +\fB\-\-without\-development\fP .RS 4 Does not install development dependencies. .RE .sp -\-\-production +\fB\-\-production\fP .RS 4 same as \fI\-\-frozen\fP and \fI\-\-without\-development\fP .RE .sp -\-\-skip\-postinstall +\fB\-\-skip\-postinstall\fP .RS 4 Does not run postinstall of dependencies. .RE .RE .sp -\fBlist\fP [\-\-tree] +\fBlist [\-\-tree]\fP .RS 4 Lists the installed dependencies and their versions. .sp -Specifying \fI\-\-tree\fP arranges nested dependencies in a tree, instead of a flattened list. +Specifying \fB\-\-tree\fP arranges nested dependencies in a tree, instead of a flattened list. .RE .sp -\fBlock\fP [\-\-update [...]] +\fBlock [\-\-update [...]]\fP .RS 4 -Resolves dependencies and creates or updates the \fIshard.lock\fP file as per +Resolves dependencies and creates or updates the \fBshard.lock\fP file as per the \fBinstall\fP command, but never installs the dependencies. .sp -Specifying \fI\-\-update\fP follows the same semantics as the \fBupdate\fP +Specifying \fB\-\-update\fP follows the same semantics as the \fBupdate\fP command. .RE .sp -\fBoutdated\fP [\-\-pre] +\fBoutdated [\-\-pre]\fP .RS 4 Lists dependencies that are outdated. .sp -When \fI\-\-pre\fP is specified, pre\-release versions are also considered. +When \fB\-\-pre\fP is specified, pre\-release versions are also considered. .RE .sp \fBprune\fP .RS 4 -Removes unused dependencies from \fIlib\fP folder. +Removes unused dependencies from \fBlib/\fP folder. .RE .sp -\fBupdate\fP [...] +\fBupdate [...]\fP .RS 4 -Resolves and updates all dependencies into the \fIlib\fP folder, -whatever the locked versions in the \fIshard.lock\fP file. -Eventually generates a new \fIshard.lock\fP file. +Resolves and updates all dependencies into the \fBlib/\fP folder, +whatever the locked versions in the \fBshard.lock\fP file. +Eventually generates a new \fBshard.lock\fP file. .sp Specifying \fIshards\fP will update these dependencies only, trying to be as conservative as possible with other dependencies, respecting the locked versions -in the \fIshard.lock\fP file. +in the \fBshard.lock\fP file. .RE .sp -\fBversion\fP [\fI\fP] +\fBversion []\fP .RS 4 -Prints the current version of the shard located at \fIpath\fP (defaults to current +Prints the current version of the shard located at \fBpath\fP (defaults to current directory). .RE .sp @@ -173,37 +167,37 @@ To see the available options for a particular command, use \fB\-\-help\fP after a command. .SH "GENERAL OPTIONS" .sp -\-\-version +\fB\-\-version\fP .RS 4 Prints the version of \fIshards\fP. .RE .sp -\-h, \-\-help +\fB\-h\fP, \fB\-\-help\fP .RS 4 Prints usage synopsis. .RE .sp -\-\-no\-color +\fB\-\-no\-color\fP .RS 4 Disables colored output. .RE .sp -\-\-local +\fB\-\-local\fP .RS 4 Don\(cqt update remote repositories, use the local cache only. .RE .sp -\-\-ignore\-crystal\-version +\fB\-\-ignore\-crystal\-version\fP .RS 4 Do not enforce crystal version restrictions on shards. .RE .sp -\-q, \-\-quiet +\fB\-q\fP, \fB\-\-quiet\fP .RS 4 Decreases the log verbosity, printing only warnings and errors. .RE .sp -\-v, \-\-verbose +\fB\-v\fP, \fB\-\-verbose\fP .RS 4 Increases the log verbosity, printing all debug statements. .RE @@ -215,60 +209,60 @@ separate \fIshards\fP package may be available for your system. To install from source, download or clone .URL "https://github.com/crystal\-lang/shards" "the repository" " " and run -\fBmake CRFLAGS=\-\-release\fP. The compiled binary is in \fIbin/shards\fP and +\fBmake CRFLAGS=\-\-release\fP. The compiled binary is in \fBbin/shards\fP and should be added to \fBPATH\fP. .SH "ENVIRONMENT VARIABLES" .sp -SHARDS_OPTS +\fBSHARDS_OPTS\fP .RS 4 Allows general options to be passed in as environment variable. -\fBExample\fP: \fISHARDS_OPTS="\-\-ignore\-crystal\-version" shards update\fP +\fBExample\fP: \fBSHARDS_OPTS="\-\-ignore\-crystal\-version" shards update\fP .RE .sp -SHARDS_CACHE_PATH +\fBSHARDS_CACHE_PATH\fP .RS 4 Defines the cache location. In this folder, shards stores local copies of remote repositories. -Defaults to \fI.cache/shards\fP in the home directory (\fI$XDG_CACHE_HOME\fP or \fI$HOME\fP) +Defaults to \fB.cache/shards\fP in the home directory (\fB$XDG_CACHE_HOME\fP or \fB$HOME\fP) or the current directory. .RE .sp -SHARDS_INSTALL_PATH +\fBSHARDS_INSTALL_PATH\fP .RS 4 Defines the location where dependecies are installed. -Defaults to \fIlib\fP. +Defaults to \fBlib/\fP. .RE .sp -SHARDS_BIN_PATH +\fBSHARDS_BIN_PATH\fP .RS 4 Defines the location where executables are installed. -Defaults to \fIbin\fP. +Defaults to \fBbin/\fP. .RE .sp -CRYSTAL_VERSION +\fBCRYSTAL_VERSION\fP .RS 4 Defines the crystal version that dependencies should be resolved against. -Defaults to the output of \fIcrystal env CRYSTAL_VERSION\fP. +Defaults to the output of \fBcrystal env CRYSTAL_VERSION\fP. .RE .sp -SHARDS_OVERRIDE +\fBSHARDS_OVERRIDE\fP .RS 4 -Defines the location of \fIshard.override.yml\fP. +Defines the location of \fBshard.override.yml\fP. .RE .SH "FILES" .sp -shard.yml +\fBshard.yml\fP .RS 4 Describes a shard project including its dependencies. See \fBshard.yml\fP(5) for documentation. .RE .sp -shard.override.yml +\fBshard.override.yml\fP .RS 4 -Local overrides to \fIshard.yml\fP. +Local overrides to \fBshard.yml\fP. .RE .sp -shard.lock +\fBshard.lock\fP .RS 4 Lockfile that stores information about the installed versions. .sp