Debian Codegraph @

geniuspaste/README

raw
1 GeniusPaste Plugin
2 ==================
3
4 .. contents::
5
6 About
7 -----
8 This plugin allows the user to paste code from Geany into a configured
9 pastebin service. At the moment it ships with builtin support these pastebin
10 services, but more can be added:
11
12 * codepad.org
13 * dpaste.de
14 * fpaste.org
15 * pastebin.geany.org
16 * paste.debian.net
17 * sprunge.us
18
19 GeniusPaste detects automatically the syntax of the code and pastes it
20 with syntax highlighting enabled.
21 It can also display the pasted code opening a new browser tab.
22
23 Issues
24 ------
25 The API of the pastebin services can be updated at every moment. It
26 may happen that GeniusPaste plugin could use an outdated API that meanwhile
27 has been deprecated.
28
29 If you get a unexpected API response during the paste process (practically
30 if the plugin doesn't return a link to the pasted code), you will need to fix
31 that pastebin service configuration to use its new API. If it is a
32 configuration shipped with the plugin, please report the issue to:
33
34 <enrico(dot)trt(at)gmail(dot)com>
35
36 Requirements
37 ------------
38 * GTK+ >= 3.16
39 * libsoup 3.0
40
41 Installation
42 ------------
43 This plugin is part of the geany-plugins project.
44 See the README file of that package.
45
46 Pastebin configuration
47 ----------------------
48
49 Configuration for the pastebin services is looked up in one of data directories
50 as follows, in order: ``$GEANY_CONFIG_DIR/plugins/geniuspaste/pastebins/`` and
51 ``$PREFIX/share/geany-plugins/geniuspaste/pastebins/`` (where
52 ``$GEANY_CONFIG_DIR`` is ``$HOME/.config/geany`` on \*NIX; and ``$PREFIX`` is
53 generally either ``/usr/`` or ``/usr/local/`` under \*NIX).
54
55 If more than one configuration file declare a pastebin service of the same
56 name, only the first one found is used. This way, one can easily override the
57 configuration in a system directory with a custom one in a user directory.
58
59 Format
60 ^^^^^^
61
62 The pastebin configuration format uses an INI-style syntax.
63
64 Placeholders
65 ++++++++++++
66
67 Values from the `[format] section`_ and the *replace* key in the `[parse]
68 section`_ can contain references to placeholders with the syntax ``%name%``
69 (e.g. ``%contents%``).
70 Custom placeholders can be defined in the `[defaults] section`_.
71
72 The builtin placeholders are:
73
74 *contents*
75 The data to actually paste.
76 *language*
77 The language of the current document, as mapped through the `[languages]
78 section`_.
79 *title*
80 The base name of the current document.
81 *user*
82 The configured author name.
83
84 *[pastebin]* section
85 ++++++++++++++++++++
86
87 The *pastebin* section is required, and must contain at least the *name* and
88 *url* keys.
89
90 *name*
91 The name of the pastebin service, as displayed to the user. This key is
92 required.
93 *url*
94 The URL to which submit the data. This key is required.
95 *method*
96 The HTTP method to use to submit the data. Defaults to ``POST``.
97 *content-type*
98 The Content-Type the request body should be sent in. Currently supported
99 types include ``application/x-www-form-urlencoded`` and ``application/json``.
100 Defaults to ``application/x-www-form-urlencoded``.
101
102 *[format]* section
103 ++++++++++++++++++
104
105 The *format* section describes the fields of the form to send to the pastebin.
106 Each key in this section is a field, and each value that field's value.
107
108 *[parse]* section
109 +++++++++++++++++
110
111 If the *parse* section is declared, it defines the regular expression used to
112 parse the raw response body from the pastebin service and build the final
113 paste URL.
114
115 If this section doesn't exist, the URI of the response itself is used, after
116 any possible redirection. This is usually good for non-API pastebin services,
117 where the server redirects the user to the paste page.
118
119 **Warning:** If the *parse* section exists, it will be used, no matter whether
120 any key is actually defined. This means that a ``[parse]`` line is enough to
121 enable response body parsing, and it will use the default *search* and
122 *replace* settings.
123
124 *search*
125 A regular expression (PCRE) pattern to match against the pastebin
126 service's raw response data.
127 Defaults to ``^[[:space:]]*(.+?)[[:space:]]*$``, i.e. capture everything
128 but the leading and trailing whitespaces.
129 *replace*
130 The final URL, with regular expression capture groups from *search*
131 expanded. Group references use the numeric, one-digit syntax: ``\0``
132 refers to the whole matched text, ``\1`` to the first captured group, and
133 so on. Defaults to ``\1``, which works nicely with the default *search*
134 pattern.
135
136 *[defaults]* section
137 ++++++++++++++++++++
138
139 The *defaults* section defines default values for some builtin `placeholders`_
140 or define new placeholders.
141
142 *[languages]* section
143 +++++++++++++++++++++
144
145 The *languages* section maps Geany's filetype names (the keys) to the pastebin
146 service's own name for this language. This allows to translate the filetypes
147 Geany knows about to ones the pastebin service understands.
148
149
150 License
151 -------
152 GeniusPaste is distributed under the terms of the GNU General Public
153 License as published by the Free Software Foundation; either version 2
154 of the License, or (at your option) any later version. A copy of this
155 license can be found in the file COPYING included with the source code
156 of this program. If not, you will be able to get a copy by contacting
157 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
158 Boston, MA 02110-1301, USA.