From bed8857b779b9896f6a3b54336feddb41c0a5b5a Mon Sep 17 00:00:00 2001 From: Daniel Friesel Date: Tue, 7 Jul 2009 13:10:07 +0200 Subject: pkg: Recommend to postfix manuals in man/ with .pod --- man/7/pkg | 239 ---------------------------------------------------- man/7/pkg-setup | 23 ----- man/7/pkg-setup.pod | 17 ++++ man/7/pkg.pod | 236 +++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 253 insertions(+), 262 deletions(-) delete mode 100644 man/7/pkg delete mode 100644 man/7/pkg-setup create mode 100644 man/7/pkg-setup.pod create mode 100644 man/7/pkg.pod (limited to 'man/7') diff --git a/man/7/pkg b/man/7/pkg deleted file mode 100644 index a6d41b2..0000000 --- a/man/7/pkg +++ /dev/null @@ -1,239 +0,0 @@ -=pod - -=head1 NAME - -pkg - distributed dotfile and script manager, package format - -=head1 INTRO - -(if you prefer technical infos over historical blah-blah, skip this section) - -Actually, pkg is just a pimped dotfile manager, which just happens to support -a sort of packages, version control, automatic sym- and hardlinking, and which -can also handle scripts and binaries. Oh, and it can cause serious brain damage. - -It evolved from two hg repos for ~/bin and ~/etc and some management scripts, -and now it can handle as many git repos as you want, which may contain -basically anything you can think of - you can even store movies in them. -(Of course that would be completely braindead, but hey - -you could, if you wanted to) - -=head1 THE BASICS - -pkg requires two directories in you home directory. B<~/bin> contains -symlinks to the executables shipped with your packages, and $PKG_DIR -(B<~/packages> by default) contains the -packages themselves. B<~/bin> may also contain normal executables; pkg will -not overwrite existing files. - -=head1 THE PACKAGE DIRECTORY - -$PKG_DIR is the core of all this stuff. Its main use is storing the packages. -There is one directory for each installed package, as created by B. -$PKG_DIR holds two special files: B<.list> and B<.list-remote>. For -an explanation about these files, see L below. -It also contains a special directory, F<.collected> - see L. - -=head2 NOTE - -All directories in $PKG_DIR must be valid git repositories which are not in the -state of 'initial commit'. Dotfiles (directories starting with a .) are exempt -from this, they will be ignored by pkg. - -=head1 THE PACKAGE ROOT - -The packages_root, in pkg referred to as $PKG_ROOT, is structured just like -the packages directory $PKG_DIR, except that it neither contains .list nor -.list-remote. The packages root is the central point where pkg fetches -packages from and pushes packages to. - -The package root should contain the pkglist script shipped in include/. -If it doesn't, PKGLIST_PATH in .pkg.conf must be set to the appropiate -location on the package root host. - -=head1 THE PACKAGE LIST - -Thi package list lives in the files B<.list> and B<.list-remote> mentioned -above. It's used to decide whether a package needs to be pulled / pushed. -Also, the 'pkg add' completion relies on .list-remote, and back in the days when -pkg supported more than one DVCS, it was used to determine which DVCS to use -for which package. - -It consists of one line per package, each line containing three items separated -by a single whitespace. The first item is the package name, the second one the -repository type (DVCS), the third the current revision. Example: - - pkg git 82d716d01dee0329af7df5e67b55558fe3ff1466 - -=head1 WHAT IS A PACKAGE? - -Anything tracked with git can be used as package. However, as the purpose of pkg -is not to do your version control, you probably want to have at least one of the -files and directories described below in it. - -=head1 PACKAGE STRUCTURE - -Special (as in, mostly handled by pkg) directories and files in a package. - -Unless marked with [*], all files and directories are optional - -=over - -=item bin/ - -The place for executables to be in the user's PATH. -pkg will automatically create symlinks in F<~/bin> pointing to the files -in the package's F - -=item etc/ - -Configuration files, not threated specially though - -=item hooks/ - -Package hooks, see L - -=item include/ - -Scripts used by the package that don't belong into B. Not threated specially - -=item man/ - -Manual files in POD format, separated by section (like man/7/pkg) - -=item provides/ - -Files for inclusion into other packages - -=item description - -Package description for B - -=item links - -Sym- and hardlink descriptions. See checklinks(1) - -=item Makefile - -If a Makefile is available, C will be executed - -=item prereqs - -The package's prerequisites, mainly dependencies. See L - -=item priority - -Package priority as an integer between 1 and 6. -Packages with a priority above 3 require user confirmation to be removed - -=back - -=head1 PREREQUISITES - -The prerequisites are stored in a package in the file F. -It as an ordinary shell script which is sourced by pkg's global post-update -hook; so it will be sourced after pulling, pushing or refreshing a package. - -Note that the file will be sourced in function scope. It is recommended to -introduce parameters and options local to the prereqs script with -C<< typeset >> and C<< setopt localoptions >>, respectively. - -It's main use is to check for dependencies. To help with this, the following -functions are available: - -=over - -=item B I - -Returns true if I is installed, otherwise false - -=item B I - -Returns true if I can be used by perl, otherwise false - -=item B I - -Returns true if I was found in the users PATH, otherwise false - -=item B I - -Mark I for installation - -=item B I | B I - -Execute expression and automatically warn if it fails. -In case of B, automatically mark B for installation -if it isn't installed. -If a B fails, pkg will inform the user about it and wait for confirmation - -=item B I<...>, B I<...> - -Take the same arguments as B, but are of lower priority. -recommend only causes "info" messages, and suggest does not interrupt pkg -to make sure it's read by the user - -=back - -Additionally, the string parameters B and B can be used to store -messages. - -After executing the prereqs script, pkg will print the content of -these parameters; in case of B, it will also wait for confirmation. -It will also offer to install packages marked by B or -B. - -=head1 HOOKS - -Hooks are little zsh-snippets residing in $PKG_DIR/hooks -which are sourced from within pkg whenever needed. - -Currently, the following hooks exist: - -=over - -=item post-add - -Sourced after a package was installed (e.g. with pkg add/pkg install) - -=item post-update - -Sourced after a package was updated (pkg upgrade/pkg pull). -It is also sourced when adding a package (after post-add) and -when calling pkg refresh. - -=item pre-remove - -Sourced before a package is removed (pkg remove/pkg delete) - -=back - -=head1 COLLECTED PACKAGE FILES - -These files reside in F<$PKG_DIR/.collected> (subject to change). - -The directory is somewhat similar to F<~/bin> - it is automatically populated -by pkg. However, this one does not contain symlinks. - -Currently, it only contains the directory F, which holds the "compiled" -manual pages from the packages (both extracted from F and F). -This way, yuo can put F<.../.collected/man> into you MANPATH to access manuals -provided by packages. - -=head1 GIT - -B uses git(1) as backend for storing and syncing package information. -It is not recommended to use branches other than "master". -While they should work if GIT_USE_ORIGIN is set to 1 (the default), they will -most likely confuse pkg update. - -=head1 AUTHOR - -Daniel Friesel Ederf@derf.homelinux.orgE - -=head1 SEE ALSO - -checklinks(1), pkg(1) - -=cut - -vim:ft=pod diff --git a/man/7/pkg-setup b/man/7/pkg-setup deleted file mode 100644 index a6438a1..0000000 --- a/man/7/pkg-setup +++ /dev/null @@ -1,23 +0,0 @@ -=pod - -=head1 NAME - -pkg - Package root setup - -=head1 PACKAGE ROOT - -First, you'll need to create a root directory (from now on PKG_ROOT) on the -server which shall from now on host all your packages. -Then you need to put the pkg git repository into F - it's recommended -to do this via git clone --bare. - -Copy the pkglist script (include/pkglist) to F. - -Now you can add your own packages as git repos in PKG_ROOT. - -To use pkg with your packages on a machine, download and execute -the bootstrap script (include/bootstrap). - -=cut - -vim:ft=pod diff --git a/man/7/pkg-setup.pod b/man/7/pkg-setup.pod new file mode 100644 index 0000000..1c0d7bf --- /dev/null +++ b/man/7/pkg-setup.pod @@ -0,0 +1,17 @@ +=head1 NAME + +pkg - Package root setup + +=head1 PACKAGE ROOT + +First, you'll need to create a root directory (from now on PKG_ROOT) on the +server which shall from now on host all your packages. +Then you need to put the pkg git repository into F - it's recommended +to do this via git clone --bare. + +Copy the pkglist script (include/pkglist) to F. + +Now you can add your own packages as git repos in PKG_ROOT. + +To use pkg with your packages on a machine, download and execute +the bootstrap script (include/bootstrap). diff --git a/man/7/pkg.pod b/man/7/pkg.pod new file mode 100644 index 0000000..c9163d7 --- /dev/null +++ b/man/7/pkg.pod @@ -0,0 +1,236 @@ +=head1 NAME + +pkg - distributed dotfile and script manager, package format + +=head1 INTRO + +(if you prefer technical infos over historical blah-blah, skip this section) + +Actually, pkg is just a pimped dotfile manager, which just happens to support +a sort of packages, version control, automatic sym- and hardlinking, and which +can also handle scripts and binaries. Oh, and it can cause serious brain damage. + +It evolved from two hg repos for ~/bin and ~/etc and some management scripts, +and now it can handle as many git repos as you want, which may contain +basically anything you can think of - you can even store movies in them. +(Of course that would be completely braindead, but hey - +you could, if you wanted to) + +=head1 THE BASICS + +pkg requires two directories in you home directory. B<~/bin> contains +symlinks to the executables shipped with your packages, and $PKG_DIR +(B<~/packages> by default) contains the +packages themselves. B<~/bin> may also contain normal executables; pkg will +not overwrite existing files. + +=head1 THE PACKAGE DIRECTORY + +$PKG_DIR is the core of all this stuff. Its main use is storing the packages. +There is one directory for each installed package, as created by B. +$PKG_DIR holds two special files: B<.list> and B<.list-remote>. For +an explanation about these files, see L below. +It also contains a special directory, F<.collected> - see L. + +=head2 NOTE + +All directories in $PKG_DIR must be valid git repositories which are not in the +state of 'initial commit'. Dotfiles (directories starting with a .) are exempt +from this, they will be ignored by pkg. + +=head1 THE PACKAGE ROOT + +The packages_root, in pkg referred to as $PKG_ROOT, is structured just like +the packages directory $PKG_DIR, except that it neither contains .list nor +.list-remote. The packages root is the central point where pkg fetches +packages from and pushes packages to. + +The package root should contain the pkglist script shipped in include/. +If it doesn't, PKGLIST_PATH in .pkg.conf must be set to the appropiate +location on the package root host. + +=head1 THE PACKAGE LIST + +Thi package list lives in the files B<.list> and B<.list-remote> mentioned +above. It's used to decide whether a package needs to be pulled / pushed. +Also, the 'pkg add' completion relies on .list-remote, and back in the days when +pkg supported more than one DVCS, it was used to determine which DVCS to use +for which package. + +It consists of one line per package, each line containing three items separated +by a single whitespace. The first item is the package name, the second one the +repository type (DVCS), the third the current revision. Example: + + pkg git 82d716d01dee0329af7df5e67b55558fe3ff1466 + +=head1 WHAT IS A PACKAGE? + +Anything tracked with git can be used as package. However, as the purpose of pkg +is not to do your version control, you probably want to have at least one of the +files and directories described below in it. + +=head1 PACKAGE STRUCTURE + +Special (as in, mostly handled by pkg) directories and files in a package. + +Unless marked with [*], all files and directories are optional + +=over + +=item bin/ + +The place for executables to be in the user's PATH. +pkg will automatically create symlinks in F<~/bin> pointing to the files +in the package's F. Also, if a file in F contains valid POD, +a manual will be generated out of it (see L) + +=item etc/ + +Configuration files, not threated specially though + +=item hooks/ + +Package hooks, see L + +=item include/ + +Scripts used by the package that don't belong into B. Not threated specially + +=item man/ + +Manual files in POD format, separated by section (like man/7/pkg.pod). +To be prepared for possible future support of other manual formats, it is +recommended to postfix each file with .pod + +=item provides/ + +Files for inclusion into other packages + +=item description + +Package description for B + +=item links + +Sym- and hardlink descriptions. See checklinks(1) + +=item Makefile + +If a Makefile is available, C will be executed + +=item prereqs + +The package's prerequisites, mainly dependencies. See L + +=item priority + +Package priority as an integer between 1 and 6. +Packages with a priority above 3 require user confirmation to be removed + +=back + +=head1 PREREQUISITES + +The prerequisites are stored in a package in the file F. +It as an ordinary shell script which is sourced by pkg's global post-update +hook; so it will be sourced after pulling, pushing or refreshing a package. + +Note that the file will be sourced in function scope. It is recommended to +introduce parameters and options local to the prereqs script with +C<< typeset >> and C<< setopt localoptions >>, respectively. + +It's main use is to check for dependencies. To help with this, the following +functions are available: + +=over + +=item B I + +Returns true if I is installed, otherwise false + +=item B I + +Returns true if I can be used by perl, otherwise false + +=item B I + +Returns true if I was found in the users PATH, otherwise false + +=item B I + +Mark I for installation + +=item B I | B I + +Execute expression and automatically warn if it fails. +In case of B, automatically mark B for installation +if it isn't installed. +If a B fails, pkg will inform the user about it and wait for confirmation + +=item B I<...>, B I<...> + +Take the same arguments as B, but are of lower priority. +recommend only causes "info" messages, and suggest does not interrupt pkg +to make sure it's read by the user + +=back + +Additionally, the string parameters B and B can be used to store +messages. + +After executing the prereqs script, pkg will print the content of +these parameters; in case of B, it will also wait for confirmation. +It will also offer to install packages marked by B or +B. + +=head1 HOOKS + +Hooks are little zsh-snippets residing in $PKG_DIR/hooks +which are sourced from within pkg whenever needed. + +Currently, the following hooks exist: + +=over + +=item post-add + +Sourced after a package was installed (e.g. with pkg add/pkg install) + +=item post-update + +Sourced after a package was updated (pkg upgrade/pkg pull). +It is also sourced when adding a package (after post-add) and +when calling pkg refresh. + +=item pre-remove + +Sourced before a package is removed (pkg remove/pkg delete) + +=back + +=head1 COLLECTED PACKAGE FILES + +These files reside in F<$PKG_DIR/.collected> (subject to change). + +The directory is somewhat similar to F<~/bin> - it is automatically populated +by pkg. However, this one does not contain symlinks. + +Currently, it only contains the directory F, which holds the "compiled" +manual pages from the packages (extracted from F and F). +This way, yuo can put F<.../.collected/man> into you MANPATH to access manuals +provided by packages. + +=head1 GIT + +B uses git(1) as backend for storing and syncing package information. +It is not recommended to use branches other than "master". +While they should work if GIT_USE_ORIGIN is set to 1 (the default), they will +most likely confuse pkg update. + +=head1 AUTHOR + +Daniel Friesel Ederf@derf.homelinux.orgE + +=head1 SEE ALSO + +checklinks(1), pkg(1) -- cgit v1.2.3