From 1f4ae3cbf528fbd044587ef8eb1159d7861a9a31 Mon Sep 17 00:00:00 2001 From: Thomas Leonard Date: Sat, 7 Jan 2012 10:12:04 +0000 Subject: [PATCH] Updated man-pages Marked many 0launch options as deprecated (replaced by "0install" sub-commands). --- 0install.1 | 12 +- 0launch.1 | 415 +++++++++++++++++++++++-------------------------------------- 2 files changed, 162 insertions(+), 265 deletions(-) rewrite 0launch.1 (68%) diff --git a/0install.1 b/0install.1 index 29fa1ae..5d736ee 100644 --- a/0install.1 +++ b/0install.1 @@ -57,7 +57,7 @@ default). If $DISPLAY is set, 0install will display a window where you can confirm (or change) the selected versions. -It will then download the corresponding archives for those version and store +It will then download the corresponding archives for those versions and store them in the cache too. Each package unpacks to its own directory. Finally, 0install will launch the program, setting environment variables to @@ -72,7 +72,7 @@ However, there are some options that apply to all operations. These are: .TP \fB\-c\fP, \fB\-\-console\fP -Never use the GUI. Normally, 0launch switches to graphical mode if it needs to +Never use the GUI. Normally, 0install switches to graphical mode if it needs to download anything from the network (unless DISPLAY is not set). .TP @@ -100,7 +100,7 @@ of DIR contains the contents of one version of a program or library. .PP Select a version of the program identified by URI, and compatible versions of -all of its dependencies. The information about available version is +all of its dependencies. The information about available versions is downloaded if it's not yet in the cache. .PP @@ -113,7 +113,7 @@ known and trusted, you will be prompted to accept it first. Local feed files are not signed (any signature will be ignored). .PP -You can also specificy a local selections document, as created previously using +You can also specify a local selections document, as created previously using the \fB\-\-xml\fP option, rather than a feed. In that case, 0install simply uses those versions without running the solver. @@ -374,7 +374,7 @@ See the 0store(1) man page for more information. .SH LICENSE .PP -Copyright (C) 2010 Thomas Leonard. +Copyright (C) 2011 Thomas Leonard. .PP You may redistribute copies of this program under the terms of the GNU Lesser General Public License. @@ -386,7 +386,7 @@ http://0install.net/support.html .SH AUTHOR .PP -The Zero Install Injector was created by Thomas Leonard. +Zero Install was created by Thomas Leonard, with help from many others. See the Git log for details. .SH SEE ALSO 0alias(1), 0store(1), 0launch(1) diff --git a/0launch.1 b/0launch.1 dissimilarity index 68% index 82ca210..ca062d7 100644 --- a/0launch.1 +++ b/0launch.1 @@ -1,259 +1,156 @@ -.TH 0LAUNCH 1 "2010" "Thomas Leonard" "" -.SH NAME -0launch \(em download and run programs by URL - -.SH SYNOPSIS - -.B 0launch -[\fBOPTION\fP]... \fBINTERFACE\fP [\fBARG\fP]... - -.B 0launch -\-\-list [\fBSEARCH\-TERM\fP] - -.B 0launch -\-\-import [\fBFEED\-FILES\fP] - -.SH DESCRIPTION -.PP -0launch runs a program, identified by an `INTERFACE'. If the program is not -already on your computer, it downloads information about which versions are -available, and lets you choose one to download. It will also (automatically) -do the same for libraries the program needs. - -.PP -0launch will also check for updates if it has been a long time since the last -check (configurable). - -.PP -Normally, INTERFACE is taken as a FEED, which can be either a URL in the form -`http://site/program' or a local path name like `/path/to/program.xml'. For -HTTP URLs, the remote file is a GPG-signed XML document. Local feed files -are not signed. The default one-to-one mapping from interface URIs to feed -URLs can be changed using the \-\-feed option. - -.SH EXAMPLES - -.PP -When a program is available using 0launch, it will have an associated URL. To -run the program, simply invoke 0launch with this as an argument: - -.B 0launch http://rox.sourceforge.net/2005/interfaces/Edit - -.PP -The first time you do this, details about the program are downloaded and -cached, and you will be prompted to confirm the versions to use. In future, -the program will run directly from the cache without confirmation. - -.PP -To check for new versions: - -.B 0launch \-\-refresh http://rox.sourceforge.net/2005/interfaces/Edit - -.PP -To search the list of cached URLs: - -.B 0launch \-\-list Edit - -.PP -To avoid having to keep typing the full URI, use the 0alias(1) command -to create shortcuts to run your programs. - -.SH COMMAND-LINE OPTIONS - -.TP -\fB\-\-before=VERSION\fP -Chosen implementation's version number must be earlier than VERSION. i.e., force -the use of an old version the program. - -.TP -\fB\-c\fP, \fB\-\-console\fP -Never use the GUI. Normally, 0launch switches to graphical mode if it needs to -download anything from the network (unless DISPLAY is not set). - -.TP -\fB\-d\fP, \fB\-\-download\-only\fP -Download any needed files, but stop before actually running the program. - -.TP -\fB\-D\fP, \fB\-\-dry\-run\fP -Just print what actions would be taken. - -.TP -\fB\-f\fP, \fB\-\-feed\fP -Register (or unregister) an additional source of implementations. When you check out -a developer version of a project, it may contain an XML feed file. To add this -version to the list of available versions, use \-\-feed on this XML file. The -file is not copied, so you don't need to re-add the file each time it is -updated. - -Note that if you just want to run the program, you can invoke 0launch on the -feed file directly (without using \-\-feed). This will force the injector to -use that version, but won't affect what happens when you run it using the URI -as normal. Use \-\-feed when you want to use the developer version even when -using the URI, or if the program is a library (and thus referenced by URI by -other programs). - -.TP -\fB\-\-get\-selections\fP -Instead of running the program, just print the set of chosen implementations as -an XML document to stdout. This can be used later with \fB\-\-set\-selections\fP. -Use \fB\-\-select\-only\fP if you don't even want to download the packages. - -.TP -\fB\-g\fP, \fB\-\-gui\fP -Show the graphical policy editor. This allows you to select which version of -a program or library to use. - -.TP -\fB\-h\fP, \fB\-\-help\fP -Show the built-in help text. - -.TP -\fB\-i\fP, \fB\-\-import\fP -Import from files, not from the network. This is useful when testing a -feed file, to avoid uploading it to a remote server in order to download -it again. It might also be useful when installing from a CD or similar. -The file must have a trusted GPG digital signature, as when fetching from -the network. For unsigned interfaces, see \-\-feed. - -.TP -\fB\-l\fP, \fB\-\-list\fP -List all known interface (program) URIs. If a search term is given, only -URIs containing that string are shown (case insensitive). - -.TP -\fB\-m\fP, \fB\-\-main=MAIN\fP -Run the specified executable instead of the default. If MAIN starts with '/' -then the path is relative to the implementation's top-level directory, -whereas otherwise it is relative to the directory containing the default -MAIN program. For example, if the default MAIN is \fBbin/svn\fP then -using \fB\-\-main=svnadmin\fP will run \fB.../bin/svnadmin\fP instead. - -.TP -\fB\-\-not\-before=VERSION\fP -Chosen implementation's version number must not be earlier than VERSION. -E.g., if you want to run version 2.0 or later, use \fB\-\-not\-before=2.0\fP. - -.TP -\fB\-o\fP, \fB\-\-offline\fP -Run in off-line mode, overriding the default setting. In off-line mode, no -interfaces are refreshed even if they are out-of-date, and newer versions of -programs won't be downloaded even if the injector already knows about them -(e.g. from a previous refresh). - -.TP -\fB\-r\fP, \fB\-\-refresh\fP -Fetch a fresh copy of all used interfaces. This will normally switch to GUI -mode, unless \-\-console is also given. - -.TP -\fB\-\-select\-only\fP -Download any required feeds and choose a set of implementations, but don't -actually download them. If there are stale feeds, check for updates first -(if we're not off-line). - -.TP -\fB\-\-set\-selections=FILE\fP -Instead of choosing suitable implementations using the policy, run exactly -the versions given in FILE. A suitable file can be created using the -\fB\-\-get\-selections\fP option described above. - -.TP -\fB\-\-show\fP -Print the selected versions in a human-readable format to stdout. The display -is similar to the GUI; it shows the program being run and its dependencies. -For each selected component, the version number is displayed and its location -on the file-system. Implies \-\-download-only. - -.TP -\fB\-s\fP, \fB\-\-source\fP -The implementation of the main (root) interface must have an architecture -of the form '*\-src' (normally a literal "*", but could be a compatible OS). -Dependencies are normal implementations, not source ones. See 0compile for -details. - -.TP -\fB\-v\fP, \fB\-\-verbose\fP -More verbose output. Use twice for even more verbose output. - -.TP -\fB\-V\fP, \fB\-\-version\fP -Display version information. - -.TP -\fB\-w\fP, \fB\-\-wrapper=COMMAND\fP -Instead of executing the chosen program directly, run \fBCOMMAND PROGRAM ARGS\fP. -This is useful for running debuggers and tracing tools on the program (rather -than on 0launch!). Note that the wrapper is executed in the environment selected -by the program; hence, this mechanism cannot be used for sandboxing. See the -DEBUGGING section below. - -.TP -\fB\-\-with\-store=DIR\fP -Append a directory to the list of implementation caches. - -.SH DEBUGGING TIPS - -.PP -To debug 0launch itself, use the \-\-verbose and \-\-console options. For example: - -.B $ 0launch \-vvc http://myprog - -.PP -To trace or debug programs run by 0launch, use the \-\-wrapper option. -For example, to run \fBmyprog \-\-help\fP, displaying all calls to open(2): - -.B $ 0launch \-\-wrapper="strace \-e open" http://myprog \-\-help - -If your program is interpreted (e.g. a Python program), and you wish to debug -the interpreter running it, you can do it like this: - -.B $ 0launch \-\-wrapper="gdb \-\-args python" http://myprog \-\-help - -.SH FILES - -Configuration files (see freedesktop.org basedir spec): - -.IP "~/.config/0install.net/injector/global" -Global configuration settings. - -.IP "~/.config/0install.net/injector/trustdb.xml" -List of trusted keys. - -.IP "~/.config/0install.net/injector/interfaces" -Per-interface settings, and extra feeds. - -.PP -Cached data (can be re-downloaded if lost): - -.IP "~/.cache/0install.net/interfaces" -Downloaded cached feed files. - -.IP "~/.cache/0install.net/implementations" -Downloaded cached implementations, indexed by manifest digest. - -.PP -See the 0store(1) man page for more information. - -.SH LICENSE -.PP -Copyright (C) 2010 Thomas Leonard. - -.PP -You may redistribute copies of this program under the terms of the GNU Lesser General Public License. -.SH BUGS -.PP -Please report bugs to the developer mailing list: - -http://0install.net/support.html - -.SH AUTHOR -.PP -The Zero Install Injector was created by Thomas Leonard. - -.SH SEE ALSO -0install(1), 0alias(1), 0store(1) -.PP -The Zero Install web-site: - -.B http://0install.net +.TH 0LAUNCH 1 "2011" "Thomas Leonard" "" +.SH NAME +0launch \(em download and run programs by URL + +.SH SYNOPSIS + +.B 0launch +[\fBOPTION\fP]... \fBPROGRAM\fP [\fBARG\fP]... + +.SH DESCRIPTION +.PP +0launch runs the given program. PROGRAM is either a URL in the form +`http://site/program.xml' or a local path name like `/path/to/program.xml'. + +.PP +If the program is not already on your computer, 0launch downloads information about +which versions are available, and lets you choose one to download. It will also +(automatically) do the same for any libraries the program needs. + +.PP +Note that much of the functionality that was originally in 0launch has now moved to +0install(1). + +.B 0launch PROGRAM ARGS + +.PP +is roughly equivalent to + +.B 0install run PROGRAM ARGS + +See the 0install(1) man-page for more information. + +.SH EXAMPLES + +.PP +When a program is available using 0launch, it will have an associated URL. To +run the program, simply invoke 0launch with this as an argument: + +.B 0launch http://rox.sourceforge.net/2005/interfaces/Edit + +.PP +The first time you do this, details about the program are downloaded and +cached, and you will be prompted to confirm the versions to use. In future, +the program will run directly from the cache without confirmation. + +.PP +To check for new versions: + +.B 0launch \-\-refresh http://rox.sourceforge.net/2005/interfaces/Edit + +.PP +To avoid having to keep typing the full URI, use the 0alias(1) command +to create shortcuts to run your programs. + +.SH COMMAND-LINE OPTIONS + +.TP +0launch takes many of the same options as "0install run". This page just lists the differences: + +.TP +\fB\-d\fP, \fB\-\-download\-only\fP +Deprecated. Use "0install download" instead. + +.TP +\fB\-f\fP, \fB\-\-feed\fP +Deprecated. Use "0install add-feed" or "0install remove-feed" instead. + +.TP +\fB\-\-get\-selections\fP +Deprecated. Use "0install select" instead. + +.TP +\fB\-i\fP, \fB\-\-import\fP +Deprecated. Use "0install import" instead. + +.TP +\fB\-l\fP, \fB\-\-list\fP +Deprecated. Use "0install list" instead. + +.TP +\fB\-\-select\-only\fP +Deprecated. Use "0install select" instead. + +.TP +\fB\-\-set\-selections=FILE\fP +Deprecated. Just give FILE as the PROGRAM. + +.TP +\fB\-\-show\fP +Deprecated. Use "0install select" instead. + +.SH DEBUGGING TIPS + +.PP +To debug 0launch itself, use the \-\-verbose and \-\-console options. For example: + +.B $ 0launch \-vvc http://myprog + +.PP +To trace or debug programs run by 0launch, use the \-\-wrapper option. +For example, to run \fBmyprog \-\-help\fP, displaying all calls to open(2): + +.B $ 0launch \-\-wrapper="strace \-e open" http://myprog \-\-help + +If your program is interpreted (e.g. a Python program), and you wish to debug +the interpreter running it, you can do it like this: + +.B $ 0launch \-\-wrapper="gdb \-\-args python" http://myprog \-\-help + +.SH FILES + +Configuration files (see freedesktop.org basedir spec): + +.IP "~/.config/0install.net/injector/global" +Global configuration settings. + +.IP "~/.config/0install.net/injector/trustdb.xml" +List of trusted keys. + +.IP "~/.config/0install.net/injector/interfaces" +Per-interface settings, and extra feeds. + +.PP +Cached data (can be re-downloaded if lost): + +.IP "~/.cache/0install.net/interfaces" +Downloaded cached feed files. + +.IP "~/.cache/0install.net/implementations" +Downloaded cached implementations, indexed by manifest digest. + +.PP +See the 0store(1) man page for more information. + +.SH LICENSE +.PP +Copyright (C) 2011 Thomas Leonard. + +.PP +You may redistribute copies of this program under the terms of the GNU Lesser General Public License. +.SH BUGS +.PP +Please report bugs to the developer mailing list: + +http://0install.net/support.html + +.SH AUTHOR +.PP +Zero Install was created by Thomas Leonard. + +.SH SEE ALSO +0install(1), 0alias(1), 0store(1) +.PP +The Zero Install web-site: + +.B http://0install.net -- 2.11.4.GIT