diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile | 9 | ||||
| -rw-r--r-- | docs/g-sorcery.8 | 159 | ||||
| -rw-r--r-- | docs/g-sorcery.8.rst | 130 | ||||
| -rw-r--r-- | docs/gs-ctan.8 | 174 | ||||
| -rw-r--r-- | docs/gs-ctan.8.rst | 145 | ||||
| -rw-r--r-- | docs/gs-elpa.8 | 186 | ||||
| -rw-r--r-- | docs/gs-elpa.8.rst | 159 |
7 files changed, 962 insertions, 0 deletions
diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..c42c78d --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,9 @@ +SOURCES=g-sorcery gs-elpa gs-ctan +MANS=$(SOURCES:=.8) + +RST2MAN=rst2man.py + +all: ${MANS} + +%.8: %.8.rst + $(RST2MAN) $< $@ diff --git a/docs/g-sorcery.8 b/docs/g-sorcery.8 new file mode 100644 index 0000000..7e0c614 --- /dev/null +++ b/docs/g-sorcery.8 @@ -0,0 +1,159 @@ +.\" Man page generated from reStructuredText. +. +.TH G-SORCERY 8 "2013-08-04" "0.1" "g-sorcery" +.SH NAME +g-sorcery \- manage overlays for 3rd party software providers +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +\fBg\-sorcery\fP \fIBACKEND\fP \fB\-o\fP \fIOVERLAY\fP [\fB\-r\fP \fIREPO\fP] \fBsync\fP +.sp +\fBg\-sorcery\fP \fIBACKEND\fP \fB\-o\fP \fIOVERLAY\fP [\fB\-r\fP \fIREPO\fP] \fBlist\fP +.sp +\fBg\-sorcery\fP \fIBACKEND\fP \fB\-o\fP \fIOVERLAY\fP [\fB\-r\fP \fIREPO\fP] \fBgenerate\fP \fIPACKAGE\fP +.sp +\fBg\-sorcery\fP \fIBACKEND\fP \fB\-o\fP \fIOVERLAY\fP [\fB\-r\fP \fIREPO\fP] \fBinstall\fP \fIPACKAGE\fP +.sp +\fBg\-sorcery\fP \fIBACKEND\fP \fB\-o\fP \fIOVERLAY\fP [\fB\-r\fP \fIREPO\fP] \fBgenerate\-tree\fP [\fB\-d\fP] +.SH DESCRIPTION +.sp +\fBg\-sorcery\fP is aimed to provide you with easy way of integration of 3rd party software +providers with Gentoo. +.sp +3rd party software provider is a software distribution like CTAN, CPAN or ELPA. +Usualy there is a lot of software available in such a distribution and very few or no ebuilds +for it. +.sp +\fBg\-sorcery\fP is a project aimed to implement a framework for ebuild generators (backends) +for 3rd party software providers. The CLI tool g\-sorcery is designed to be called rather +by appropriate backends then by user. If you are not a backend developer and just want to +manage your overlay see documentation for a backend you want to use. +.sp +There are two ways of using \fBg\-sorcery\fP: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +use it with \fBlayman\fP +.sp +In this case all you need to do is install \fBlayman\-9999\fP, \fBg\-sorcery\fP +and appropriate backend. Then you should just run \fIlayman \-L\fP as +root and find an overlay you want. Type of overlay will be +displayed as \fIg\-sorcery\fP. Then you add this overlay as +usual. It\(aqs all you need to do and it\(aqs the recommended way of +using \fBg\-sorcery\fP and backends. +.IP \(bu 2 +use it as stand\-alone tool +.sp +In this case you should create an overlay (see \fBportage\fP documentation), sync it and populate +it with one or more ebuilds. Then ebuilds could be installed by emerge or by \fBg\-sorcery\fP tool +or backend. +.UNINDENT +.UNINDENT +.UNINDENT +.SH OPTIONS +.INDENT 0.0 +.TP +.B \fIBACKEND\fP +Backend to be used. +.TP +.B \fB\-\-overlay\fP \fIOVERLAY\fP, \fB\-o\fP \fIOVERLAY\fP +Overlay directory. This option is mandatory if there is no +\fBdefault_overlay\fP entry in a backend config. +.TP +.B \fB\-\-repository\fP \fIREPO\fP, \fB\-r\fP \fIREPO\fP +Repository name. If there is more than one repository available +for a given backend must be specified. +.UNINDENT +.SH COMMANDS +.INDENT 0.0 +.TP +.B \fBsync\fP +Synchronize a repository database. +.TP +.B \fBlist\fP +List packages available in a repository. +.TP +.B \fBgenerate\fP +Generate a given ebuild and all its dependencies. +.TP +.B \fBinstall\fP +Generate and install an ebuild using your package mangler. +.TP +.B \fBgenerate\-tree\fP +Generate entire overlay structure. Without option \fB\-d\fP after +this command sources are not fetched during generation and there +are no entries for them in Manifest files. +.UNINDENT +.SH FILES +.INDENT 0.0 +.TP +.B \fB/etc/g\-sorcery/g\-sorcery.cfg\fP +Main g\-sorcery config. +.TP +.B \fB/etc/g\-sorcery/*.json\fP +Backend configs. +.UNINDENT +.SH NOTES +.sp +1. At the moment upstream layman does not support g\-sorcery overlay type. +You should patch it with \fIhttps://raw.github.com/jauhien/g\-sorcery/master/layman\-git\-g\-sorcery.patch\fP. +.sp +To do it download above mentioned patch, place it in +\fB/etc/portage/patches/app\-portage/layman\-9999/\fP directory and +create a file \fB/etc/portage/bashrc\fP that looks like +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +post_src_prepare() { + epatch_user +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Then you can emerge \fBapp\-portage/layman\-9999\fP. +.INDENT 0.0 +.IP 2. 3 +At the moment the only package mangler \fBg\-sorcery\fP supports is \fBportage\fP. +.UNINDENT +.SH SEE ALSO +.sp +\fBgs\-elpa\fP(8), \fBgs\-ctan\fP(8), \fBportage\fP(5), \fBemerge\fP(1), \fBlayman\fP(8) +.SH AUTHOR +Written by Jauhien Piatlicki <piatlicki@gmail.com>. GSoC idea +and mentorship by Rafael Martins. Lots of help and improvements +by Brian Dolbec. Integration with layman based on work of Auke Booij. +.SH COPYRIGHT +Copyright (c) 2013 Jauhien Piatlicki, License: GPL-2 +.\" Generated by docutils manpage writer. +. diff --git a/docs/g-sorcery.8.rst b/docs/g-sorcery.8.rst new file mode 100644 index 0000000..416c358 --- /dev/null +++ b/docs/g-sorcery.8.rst @@ -0,0 +1,130 @@ +========= +g-sorcery +========= + +------------------------------------------------ +manage overlays for 3rd party software providers +------------------------------------------------ + +:Author: Written by Jauhien Piatlicki <piatlicki@gmail.com>. GSoC idea + and mentorship by Rafael Martins. Lots of help and improvements + by Brian Dolbec. Integration with layman based on work of Auke Booij. +:Date: 2013-08-04 +:Copyright: Copyright (c) 2013 Jauhien Piatlicki, License: GPL-2 +:Version: 0.1 +:Manual section: 8 +:Manual group: g-sorcery + + +SYNOPSIS +======== + +**g-sorcery** *BACKEND* **-o** *OVERLAY* [**-r** *REPO*] **sync** + +**g-sorcery** *BACKEND* **-o** *OVERLAY* [**-r** *REPO*] **list** + +**g-sorcery** *BACKEND* **-o** *OVERLAY* [**-r** *REPO*] **generate** *PACKAGE* + +**g-sorcery** *BACKEND* **-o** *OVERLAY* [**-r** *REPO*] **install** *PACKAGE* + +**g-sorcery** *BACKEND* **-o** *OVERLAY* [**-r** *REPO*] **generate-tree** [**-d**] + +DESCRIPTION +=========== + +**g-sorcery** is aimed to provide you with easy way of integration of 3rd party software +providers with Gentoo. + +3rd party software provider is a software distribution like CTAN, CPAN or ELPA. +Usualy there is a lot of software available in such a distribution and very few or no ebuilds +for it. + +**g-sorcery** is a project aimed to implement a framework for ebuild generators (backends) +for 3rd party software providers. The CLI tool g-sorcery is designed to be called rather +by appropriate backends then by user. If you are not a backend developer and just want to +manage your overlay see documentation for a backend you want to use. + +There are two ways of using **g-sorcery**: + + * use it with **layman** + + In this case all you need to do is install **layman-9999**, **g-sorcery** + and appropriate backend. Then you should just run `layman -L` as + root and find an overlay you want. Type of overlay will be + displayed as *g-sorcery*. Then you add this overlay as + usual. It's all you need to do and it's the recommended way of + using **g-sorcery** and backends. + + * use it as stand-alone tool + + In this case you should create an overlay (see **portage** documentation), sync it and populate + it with one or more ebuilds. Then ebuilds could be installed by emerge or by **g-sorcery** tool + or backend. + +OPTIONS +======= + +*BACKEND* + Backend to be used. + +**--overlay** *OVERLAY*, **-o** *OVERLAY* + Overlay directory. This option is mandatory if there is no + **default_overlay** entry in a backend config. + +**--repository** *REPO*, **-r** *REPO* + Repository name. If there is more than one repository available + for a given backend must be specified. + +COMMANDS +======== + +**sync** + Synchronize a repository database. + +**list** + List packages available in a repository. + +**generate** + Generate a given ebuild and all its dependencies. + +**install** + Generate and install an ebuild using your package mangler. + +**generate-tree** + Generate entire overlay structure. Without option **-d** after + this command sources are not fetched during generation and there + are no entries for them in Manifest files. + +FILES +===== + +**/etc/g-sorcery/g-sorcery.cfg** + Main g-sorcery config. + +**/etc/g-sorcery/\*.json** + Backend configs. + +NOTES +===== + +1. At the moment upstream layman does not support g-sorcery overlay type. +You should patch it with `https://raw.github.com/jauhien/g-sorcery/master/layman-git-g-sorcery.patch`. + +To do it download above mentioned patch, place it in +**/etc/portage/patches/app-portage/layman-9999/** directory and +create a file **/etc/portage/bashrc** that looks like + +.. code-block:: + + post_src_prepare() { + epatch_user + } + +Then you can emerge **app-portage/layman-9999**. + +2. At the moment the only package mangler **g-sorcery** supports is **portage**. + +SEE ALSO +======== + +**gs-elpa**\(8), **gs-ctan**\(8), **portage**\(5), **emerge**\(1), **layman**\(8) diff --git a/docs/gs-ctan.8 b/docs/gs-ctan.8 new file mode 100644 index 0000000..e7606d5 --- /dev/null +++ b/docs/gs-ctan.8 @@ -0,0 +1,174 @@ +.\" Man page generated from reStructuredText. +. +.TH GS-CTAN 8 "2013-08-04" "0.1" "g-sorcery" +.SH NAME +gs-ctan \- manage overlays for ELPA repositories +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +\fBgs\-ctan\fP \fB\-o\fP \fIOVERLAY\fP [\fB\-r\fP \fIREPO\fP] \fBsync\fP +.sp +\fBgs\-ctan\fP \fB\-o\fP \fIOVERLAY\fP [\fB\-r\fP \fIREPO\fP] \fBlist\fP +.sp +\fBgs\-ctan\fP \fB\-o\fP \fIOVERLAY\fP [\fB\-r\fP \fIREPO\fP] \fBgenerate\fP \fIPACKAGE\fP +.sp +\fBgs\-ctan\fP \fB\-o\fP \fIOVERLAY\fP [\fB\-r\fP \fIREPO\fP] \fBinstall\fP \fIPACKAGE\fP +.sp +\fBgs\-ctan\fP \fB\-o\fP \fIOVERLAY\fP [\fB\-r\fP \fIREPO\fP] \fBgenerate\-tree\fP [\fB\-d\fP] +.SH DESCRIPTION +.sp +\fBgs\-ctan\fP is an ebuild generator for CTAN TEXLIVE repository. +.sp +There are two ways of using \fBgs\-ctan\fP: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +use it with \fBlayman\fP +.sp +In this case all you need to do is install \fBlayman\-9999\fP, \fBg\-sorcery\fP +and \fBgs\-ctan\fP. Then you should just run \fIlayman \-L\fP as +root and find an overlay you want. Type of overlay will be +displayed as \fIg\-sorcery\fP. Then you add this overlay as +usual. It\(aqs all you need to do and it\(aqs the recommended way of +using \fBgs\-ctan\fP. +.IP \(bu 2 +use it as stand\-alone tool +.sp +In this case you should create an overlay (see \fBportage\fP documentation), sync it and populate +it with one or more ebuilds. Then ebuilds could be installed by emerge or by \fBgs\-ctan\fP tool. +.UNINDENT +.UNINDENT +.UNINDENT +.SH OPTIONS +.INDENT 0.0 +.TP +.B \fB\-\-overlay\fP \fIOVERLAY\fP, \fB\-o\fP \fIOVERLAY\fP +Overlay directory. This option is mandatory if there is no +\fBdefault_overlay\fP entry in a backend config. +.TP +.B \fB\-\-repository\fP \fIREPO\fP, \fB\-r\fP \fIREPO\fP +Repository name. This option is not mandatory. If present should be \fBctan\fP. +.UNINDENT +.SH COMMANDS +.INDENT 0.0 +.TP +.B \fBsync\fP +Synchronize a repository database. +.TP +.B \fBlist\fP +List packages available in a repository. +.TP +.B \fBgenerate\fP +Generate a given ebuild and all its dependencies. +.TP +.B \fBinstall\fP +Generate and install an ebuild using your package mangler. +.TP +.B \fBgenerate\-tree\fP +Generate entire overlay structure. Without option \fB\-d\fP after +this command sources are not fetched during generation and there +are no entries for them in Manifest files. +.UNINDENT +.SH FILES +.INDENT 0.0 +.TP +.B \fB/etc/g\-sorcery/gs\-ctan.json\fP +Backend config. +.TP +.B \fB/etc/layman/overlays/gs\-ctan\-overlays.xml\fP +List of available repositories. +.UNINDENT +.SH EXAMPLES +.INDENT 0.0 +.TP +.B Using gs\-ctan with layman +Execute +.sp +\fBlayman \-L\fP +.sp +If you see there a \fBctan\fP overlay then anything should work. +.sp +\fBlayman \-a ctan\fP +.sp +Emerge any package from it using \fBemerge\fP. +.TP +.B Generating user ebuilds in user overlay +Create new user overlay. Run +.sp +\fBgs\-ctan \-o\fP \fIOVERLAY_DIRECTORY\fP \fB\-r ctan\fP \fBsync\fP +.sp +List packages: +.sp +\fBgs\-ctan \-o\fP \fIOVERLAY_DIRECTORY\fP \fB\-r ctan\fP \fBlist\fP +.sp +Install any package you want: +.sp +\fBgs\-ctan \-o\fP \fIOVERLAY_DIRECTORY\fP \fB\-r ctan\fP \fBinstall\fP \fIPACKAGE\fP +.sp +Note, that if you call \fBgenerate\-tree\fP command your overlay +will be wiped and overlay tree for a given repository will be generated. Be careful! +.UNINDENT +.SH NOTES +.sp +1. At the moment upstream layman does not support g\-sorcery overlay type. +You should patch it with \fIhttps://raw.github.com/jauhien/g\-sorcery/master/layman\-git\-g\-sorcery.patch\fP. +.sp +To do it download above mentioned patch, place it in +\fB/etc/portage/patches/app\-portage/layman\-9999/\fP directory and +create a file \fB/etc/portage/bashrc\fP that looks like +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +post_src_prepare() { + epatch_user +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Then you can emerge \fBapp\-portage/layman\-9999\fP. +.INDENT 0.0 +.IP 2. 3 +At the moment the only package mangler \fBgs\-ctan\fP supports is \fBportage\fP. +.UNINDENT +.SH SEE ALSO +.sp +\fBgs\-elpa\fP(8), \fBportage\fP(5), \fBemerge\fP(1), \fBlayman\fP(8) +.SH AUTHOR +Written by Jauhien Piatlicki <piatlicki@gmail.com>. GSoC idea +and mentorship by Rafael Martins. Lots of help and improvements +by Brian Dolbec. +.SH COPYRIGHT +Copyright (c) 2013 Jauhien Piatlicki, License: GPL-2 +.\" Generated by docutils manpage writer. +. diff --git a/docs/gs-ctan.8.rst b/docs/gs-ctan.8.rst new file mode 100644 index 0000000..5442cbb --- /dev/null +++ b/docs/gs-ctan.8.rst @@ -0,0 +1,145 @@ +======= +gs-ctan +======= + +------------------------------------- +manage overlays for ELPA repositories +------------------------------------- + +:Author: Written by Jauhien Piatlicki <piatlicki@gmail.com>. GSoC idea + and mentorship by Rafael Martins. Lots of help and improvements + by Brian Dolbec. +:Date: 2013-08-04 +:Copyright: Copyright (c) 2013 Jauhien Piatlicki, License: GPL-2 +:Version: 0.1 +:Manual section: 8 +:Manual group: g-sorcery + + +SYNOPSIS +======== + +**gs-ctan** **-o** *OVERLAY* [**-r** *REPO*] **sync** + +**gs-ctan** **-o** *OVERLAY* [**-r** *REPO*] **list** + +**gs-ctan** **-o** *OVERLAY* [**-r** *REPO*] **generate** *PACKAGE* + +**gs-ctan** **-o** *OVERLAY* [**-r** *REPO*] **install** *PACKAGE* + +**gs-ctan** **-o** *OVERLAY* [**-r** *REPO*] **generate-tree** [**-d**] + +DESCRIPTION +=========== + +**gs-ctan** is an ebuild generator for CTAN TEXLIVE repository. + +There are two ways of using **gs-ctan**: + + * use it with **layman** + + In this case all you need to do is install **layman-9999**, **g-sorcery** + and **gs-ctan**. Then you should just run `layman -L` as + root and find an overlay you want. Type of overlay will be + displayed as *g-sorcery*. Then you add this overlay as + usual. It's all you need to do and it's the recommended way of + using **gs-ctan**. + + * use it as stand-alone tool + + In this case you should create an overlay (see **portage** documentation), sync it and populate + it with one or more ebuilds. Then ebuilds could be installed by emerge or by **gs-ctan** tool. + + +OPTIONS +======= + +**--overlay** *OVERLAY*, **-o** *OVERLAY* + Overlay directory. This option is mandatory if there is no + **default_overlay** entry in a backend config. + +**--repository** *REPO*, **-r** *REPO* + Repository name. This option is not mandatory. If present should be **ctan**. + +COMMANDS +======== + +**sync** + Synchronize a repository database. + +**list** + List packages available in a repository. + +**generate** + Generate a given ebuild and all its dependencies. + +**install** + Generate and install an ebuild using your package mangler. + +**generate-tree** + Generate entire overlay structure. Without option **-d** after + this command sources are not fetched during generation and there + are no entries for them in Manifest files. + +FILES +===== +**/etc/g-sorcery/gs-ctan.json** + Backend config. + +**/etc/layman/overlays/gs-ctan-overlays.xml** + List of available repositories. + +EXAMPLES +======== + +Using gs-ctan with layman + Execute + + **layman -L** + + If you see there a **ctan** overlay then anything should work. + + **layman -a ctan** + + Emerge any package from it using **emerge**. + +Generating user ebuilds in user overlay + Create new user overlay. Run + + **gs-ctan -o** *OVERLAY_DIRECTORY* **-r ctan** **sync** + + List packages: + + **gs-ctan -o** *OVERLAY_DIRECTORY* **-r ctan** **list** + + Install any package you want: + + **gs-ctan -o** *OVERLAY_DIRECTORY* **-r ctan** **install** *PACKAGE* + + Note, that if you call **generate-tree** command your overlay + will be wiped and overlay tree for a given repository will be generated. Be careful! + +NOTES +===== + +1. At the moment upstream layman does not support g-sorcery overlay type. +You should patch it with `https://raw.github.com/jauhien/g-sorcery/master/layman-git-g-sorcery.patch`. + +To do it download above mentioned patch, place it in +**/etc/portage/patches/app-portage/layman-9999/** directory and +create a file **/etc/portage/bashrc** that looks like + +.. code-block:: + + post_src_prepare() { + epatch_user + } + +Then you can emerge **app-portage/layman-9999**. + +2. At the moment the only package mangler **gs-ctan** supports is **portage**. + +SEE ALSO +======== + +**gs-elpa**\(8), **portage**\(5), **emerge**\(1), **layman**\(8) diff --git a/docs/gs-elpa.8 b/docs/gs-elpa.8 new file mode 100644 index 0000000..a4fdaba --- /dev/null +++ b/docs/gs-elpa.8 @@ -0,0 +1,186 @@ +.\" Man page generated from reStructuredText. +. +.TH GS-ELPA 8 "2013-08-04" "0.1" "g-sorcery" +.SH NAME +gs-elpa \- manage overlays for ELPA repositories +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +\fBgs\-elpa\fP \fB\-o\fP \fIOVERLAY\fP [\fB\-r\fP \fIREPO\fP] \fBsync\fP +.sp +\fBgs\-elpa\fP \fB\-o\fP \fIOVERLAY\fP [\fB\-r\fP \fIREPO\fP] \fBlist\fP +.sp +\fBgs\-elpa\fP \fB\-o\fP \fIOVERLAY\fP [\fB\-r\fP \fIREPO\fP] \fBgenerate\fP \fIPACKAGE\fP +.sp +\fBgs\-elpa\fP \fB\-o\fP \fIOVERLAY\fP [\fB\-r\fP \fIREPO\fP] \fBinstall\fP \fIPACKAGE\fP +.sp +\fBgs\-elpa\fP \fB\-o\fP \fIOVERLAY\fP [\fB\-r\fP \fIREPO\fP] \fBgenerate\-tree\fP [\fB\-d\fP] +.SH DESCRIPTION +.sp +\fBgs\-elpa\fP is an ebuild generator for ELPA repositories \-\- repositories with +elisp packages for emacs. +.sp +There are two ways of using \fBgs\-elpa\fP: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +use it with \fBlayman\fP +.sp +In this case all you need to do is install \fBlayman\-9999\fP, \fBg\-sorcery\fP +and \fBgs\-elpa\fP. Then you should just run \fIlayman \-L\fP as +root and find an overlay you want. Type of overlay will be +displayed as \fIg\-sorcery\fP. Then you add this overlay as +usual. It\(aqs all you need to do and it\(aqs the recommended way of +using \fBgs\-elpa\fP. +.IP \(bu 2 +use it as stand\-alone tool +.sp +In this case you should create an overlay (see \fBportage\fP documentation), sync it and populate +it with one or more ebuilds. Then ebuilds could be installed by emerge or by \fBgs\-elpa\fP tool. +.UNINDENT +.UNINDENT +.UNINDENT +.SH OPTIONS +.INDENT 0.0 +.TP +.B \fB\-\-overlay\fP \fIOVERLAY\fP, \fB\-o\fP \fIOVERLAY\fP +Overlay directory. This option is mandatory if there is no +\fBdefault_overlay\fP entry in a backend config. +.TP +.B \fB\-\-repository\fP \fIREPO\fP, \fB\-r\fP \fIREPO\fP +Repository name. Can be one of \fBgnu\-elpa\fP, \fBmarmalade\fP, \fBmelpa\fP. +.UNINDENT +.SH COMMANDS +.INDENT 0.0 +.TP +.B \fBsync\fP +Synchronize a repository database. +.TP +.B \fBlist\fP +List packages available in a repository. +.TP +.B \fBgenerate\fP +Generate a given ebuild and all its dependencies. +.TP +.B \fBinstall\fP +Generate and install an ebuild using your package mangler. +.TP +.B \fBgenerate\-tree\fP +Generate entire overlay structure. Without option \fB\-d\fP after +this command sources are not fetched during generation and there +are no entries for them in Manifest files. +.UNINDENT +.SH FILES +.INDENT 0.0 +.TP +.B \fB/etc/g\-sorcery/gs\-elpa.json\fP +Backend config. +.TP +.B \fB/etc/layman/overlays/gs\-elpa\-overlays.xml\fP +List of available repositories. +.UNINDENT +.SH EXAMPLES +.INDENT 0.0 +.TP +.B Using gs\-elpa with layman +Execute +.sp +\fBlayman \-L\fP +.sp +Find there an overlay you need (there are +3 gs\-elpa overlays currently: gnu\-elpa, marmalade and melpa). +Add, e.g. +.sp +\fBlayman \-a gnu\-elpa \-a marmalade\fP +.sp +Emerge any package from it, e.g. +.sp +\fBemerge \-va clojure\-mode\fP +.TP +.B Generating user ebuilds in user overlay +Create new user overlay. Run +.sp +\fBgs\-elpa \-o\fP \fIOVERLAY_DIRECTORY\fP \fB\-r gnu\-elpa\fP \fBsync\fP +.sp +List packages: +.sp +\fBgs\-elpa \-o\fP \fIOVERLAY_DIRECTORY\fP \fB\-r gnu\-elpa\fP \fBlist\fP +.sp +Install any package you want: +.sp +\fBgs\-elpa \-o\fP \fIOVERLAY_DIRECTORY\fP \fB\-r gnu\-elpa\fP \fBinstall\fP \fIPACKAGE\fP +.sp +Repositories you can use are gnu\-elpa, marmalade and melpa. You can use them +all in one overlay. Note, that if you call \fBgenerate\-tree\fP command your overlay +will be wiped and overlay tree for a given repository will be generated. Be careful! +.UNINDENT +.SH NOTES +.sp +1. At the moment upstream layman does not support g\-sorcery overlay type. +You should patch it with \fIhttps://raw.github.com/jauhien/g\-sorcery/master/layman\-git\-g\-sorcery.patch\fP. +.sp +To do it download above mentioned patch, place it in +\fB/etc/portage/patches/app\-portage/layman\-9999/\fP directory and +create a file \fB/etc/portage/bashrc\fP that looks like +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +post_src_prepare() { + epatch_user +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Then you can emerge \fBapp\-portage/layman\-9999\fP. +.INDENT 0.0 +.IP 2. 3 +At the moment the only package mangler \fBgs\-elpa\fP supports is \fBportage\fP. +.UNINDENT +.SH BUGS +.sp +Some packages in \fBmarmalade\fP and \fBmelpa\fP depend on packages from gnu\-elpa. \fBinstall\fP and \fBgenerate\fP +commands will fail on them as dependencies between overlays are not supported currently. So the +recommended way of using gs\-elpa is using it with layman. Even doing so you should always add +gnu\-elpa repository: \fBlayman \-a gnu\-elpa\fP. +.SH SEE ALSO +.sp +\fBgs\-ctan\fP(8), \fBportage\fP(5), \fBemerge\fP(1), \fBlayman\fP(8) +.SH AUTHOR +Written by Jauhien Piatlicki <piatlicki@gmail.com>. GSoC idea +and mentorship by Rafael Martins. Lots of help and improvements +by Brian Dolbec. +.SH COPYRIGHT +Copyright (c) 2013 Jauhien Piatlicki, License: GPL-2 +.\" Generated by docutils manpage writer. +. diff --git a/docs/gs-elpa.8.rst b/docs/gs-elpa.8.rst new file mode 100644 index 0000000..49d125c --- /dev/null +++ b/docs/gs-elpa.8.rst @@ -0,0 +1,159 @@ +======= +gs-elpa +======= + +------------------------------------- +manage overlays for ELPA repositories +------------------------------------- + +:Author: Written by Jauhien Piatlicki <piatlicki@gmail.com>. GSoC idea + and mentorship by Rafael Martins. Lots of help and improvements + by Brian Dolbec. +:Date: 2013-08-04 +:Copyright: Copyright (c) 2013 Jauhien Piatlicki, License: GPL-2 +:Version: 0.1 +:Manual section: 8 +:Manual group: g-sorcery + + +SYNOPSIS +======== + +**gs-elpa** **-o** *OVERLAY* [**-r** *REPO*] **sync** + +**gs-elpa** **-o** *OVERLAY* [**-r** *REPO*] **list** + +**gs-elpa** **-o** *OVERLAY* [**-r** *REPO*] **generate** *PACKAGE* + +**gs-elpa** **-o** *OVERLAY* [**-r** *REPO*] **install** *PACKAGE* + +**gs-elpa** **-o** *OVERLAY* [**-r** *REPO*] **generate-tree** [**-d**] + +DESCRIPTION +=========== + +**gs-elpa** is an ebuild generator for ELPA repositories -- repositories with +elisp packages for emacs. + +There are two ways of using **gs-elpa**: + + * use it with **layman** + + In this case all you need to do is install **layman-9999**, **g-sorcery** + and **gs-elpa**. Then you should just run `layman -L` as + root and find an overlay you want. Type of overlay will be + displayed as *g-sorcery*. Then you add this overlay as + usual. It's all you need to do and it's the recommended way of + using **gs-elpa**. + + * use it as stand-alone tool + + In this case you should create an overlay (see **portage** documentation), sync it and populate + it with one or more ebuilds. Then ebuilds could be installed by emerge or by **gs-elpa** tool. + + +OPTIONS +======= + +**--overlay** *OVERLAY*, **-o** *OVERLAY* + Overlay directory. This option is mandatory if there is no + **default_overlay** entry in a backend config. + +**--repository** *REPO*, **-r** *REPO* + Repository name. Can be one of **gnu-elpa**, **marmalade**, **melpa**. + +COMMANDS +======== + +**sync** + Synchronize a repository database. + +**list** + List packages available in a repository. + +**generate** + Generate a given ebuild and all its dependencies. + +**install** + Generate and install an ebuild using your package mangler. + +**generate-tree** + Generate entire overlay structure. Without option **-d** after + this command sources are not fetched during generation and there + are no entries for them in Manifest files. + +FILES +===== +**/etc/g-sorcery/gs-elpa.json** + Backend config. + +**/etc/layman/overlays/gs-elpa-overlays.xml** + List of available repositories. + +EXAMPLES +======== + +Using gs-elpa with layman + Execute + + **layman -L** + + Find there an overlay you need (there are + 3 gs-elpa overlays currently: gnu-elpa, marmalade and melpa). + Add, e.g. + + **layman -a gnu-elpa -a marmalade** + + Emerge any package from it, e.g. + + **emerge -va clojure-mode** + +Generating user ebuilds in user overlay + Create new user overlay. Run + + **gs-elpa -o** *OVERLAY_DIRECTORY* **-r gnu-elpa** **sync** + + List packages: + + **gs-elpa -o** *OVERLAY_DIRECTORY* **-r gnu-elpa** **list** + + Install any package you want: + + **gs-elpa -o** *OVERLAY_DIRECTORY* **-r gnu-elpa** **install** *PACKAGE* + + Repositories you can use are gnu-elpa, marmalade and melpa. You can use them + all in one overlay. Note, that if you call **generate-tree** command your overlay + will be wiped and overlay tree for a given repository will be generated. Be careful! + +NOTES +===== + +1. At the moment upstream layman does not support g-sorcery overlay type. +You should patch it with `https://raw.github.com/jauhien/g-sorcery/master/layman-git-g-sorcery.patch`. + +To do it download above mentioned patch, place it in +**/etc/portage/patches/app-portage/layman-9999/** directory and +create a file **/etc/portage/bashrc** that looks like + +.. code-block:: + + post_src_prepare() { + epatch_user + } + +Then you can emerge **app-portage/layman-9999**. + +2. At the moment the only package mangler **gs-elpa** supports is **portage**. + +BUGS +==== + +Some packages in **marmalade** and **melpa** depend on packages from gnu-elpa. **install** and **generate** +commands will fail on them as dependencies between overlays are not supported currently. So the +recommended way of using gs-elpa is using it with layman. Even doing so you should always add +gnu-elpa repository: **layman -a gnu-elpa**. + +SEE ALSO +======== + +**gs-ctan**\(8), **portage**\(5), **emerge**\(1), **layman**\(8) |