This file is indexed.

/usr/share/doc/gnat-gps/html/Customization-files-and-plugins.html is in gnat-gps-doc 5.0-6.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
<html lang="en">
<head>
<title>Customization files and plugins - Using the GNAT Programming Studio</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Using the GNAT Programming Studio">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Customizing-through-XML-and-Python-files.html#Customizing-through-XML-and-Python-files" title="Customizing through XML and Python files">
<link rel="next" href="Defining-Actions.html#Defining-Actions" title="Defining Actions">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 2002-2010 AdaCore.

This document is free; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.

This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, see `http://www.gnu.org/licenses/'.-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
pre.smallexample {background-color:rgb(240,240,240);
                     font-family: courier new,courier,fixed;
                     font-size: 14px;
                     margin: 0px 40px 0px 40px;
                     border-width: 1px 2px 2px 1px;
                     border-top-style: dotted;
                     border-left-style: dotted;
                     border-right-style: solid;
                     border-bottom-style: solid;
                     border-color: black;}
   code             {color:black;
                     font-family: courier new,courier,fixed;
                     font-size: 14px;}
   body             {font-family: arial,helvetica,sans-serif;
                     font-size: 16px;
                     max-width: 800px;
                     text-align: justify}
   samp             {font-family: courier new,courier,fixed;
                     font-size: 14px}
                    
--></style>
</head>
<body>
<div class="node">
<a name="Customization-files-and-plugins"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Defining-Actions.html#Defining-Actions">Defining Actions</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Customizing-through-XML-and-Python-files.html#Customizing-through-XML-and-Python-files">Customizing through XML and Python files</a>
<hr>
</div>

<h4 class="subsection">16.5.1 Customization files and plugins</h4>

<!--  -->
<p class="noindent">You can customize lots of capabilities in GPS using files that are
loaded by GPS at start up.

   <p>For example, you can add items in the menu and tool bars, as well as
defining new key bindings, new languages, new tools, <small class="dots">...</small>;
Using Python as a programming language, you can also add brand new facilities
and integrate your own tools in the GPS platform.

   <p>These customization files are searched for at startup in several different
places. Depending on the location where they are found, these files will either
be automatically loaded by GPS (and thus can immediately modify things in GPS),
or will simply be made visible in the Plug-ins Editor
(see <a href="The-Plug_002dins-Editor.html#The-Plug_002dins-Editor">The Plug-ins Editor</a>).

   <p>These directories are searched for in the order given below. Any script loaded
latter can override setups done by previously loaded scripts. For instance,
they could override a key shortcut, remove a menu, redefining a GPS
action, <small class="dots">...</small>

   <p>In the directory names below, <samp><span class="file">INSTALL</span></samp> is the name of the directory in
which you have installed GPS. <samp><span class="file">HOME</span></samp> is the user's home directory, either
by default or as overriden by the <code>GPS_HOME</code> environment variable. If none
of these exist, GPS will use the <code>USERPROFILE</code> environment variable.

   <p>In all these directories, only the files with <samp><span class="file">.xml</span></samp> or <samp><span class="file">.py</span></samp>
extensions are taken into account. Other files are ignored, although for
compatibility with future versions of GPS it is recommended not to keep other
files in the same directory.

     <ul>
<li>Automatically loaded system wide modules

     <p>The <samp><span class="file">INSTALL/share/gps/plug-ins</span></samp> directory should contain the files that
GPS will automatically load by default (unless overriden by the user through
the Plug-ins Editor). These plug-ins are visible to any user on the
system that uses the same GPS installation. This directory should be reserved
for critical plug-ins that almost every one should use.

     <li>Not automatically loaded system wide modules

     <p>The <samp><span class="file">INSTALL/share/gps/library</span></samp> directory should contain the files that
GPS should show in the Plug-ins Editor, but not load automatically. 
Typically, these would be files that add optional capabilities to GPS, for
instance an emacs emulation mode, or additional editor capabilities that a lot
of users would not generally use.

     <li><code>GPS_CUSTOM_PATH</code>

     <p>This environment variable can be set before launching GPS. It should contain
a list of directories, separated by semicolons (';') on Windows systems and
colons (':') on Unix systems. All the files in these directories with the
appropriate extensions will be automatically loaded by default by GPS,
unless overriden by the user through the Plug-ins Editor.

     <p>This is a convenient way to have project-specific customization files. You can
for instance create scripts, or icons, that set the appropriate value for the
variable and then start GPS. Depending on your project, this allows you to
load specific aliases which do not make sense for other projects.

     <li>Automatically loaded user directory

     <p>The directory <samp><span class="file">HOME/.gps/plug-ins</span></samp> is searched last. Any script
found in there will be automatically loaded unless overriden in the
Plug-ins Editor.

     <p>This is a convenient way for users to create their own plug-ins, or
test them before they are made available to the whole system by
copying them to one of the other directories.

   </ul>

   <p>Any script loaded by GPS can contain customization for various aspects
of GPS, mixing aliases, new languages or menus, <small class="dots">...</small> in a single
file. This is a convenient way to distribute your plug-ins to other
users.

<h5 class="subsubsection">16.5.1.1 Python files</h5>

<p>Although the format of the python plug-ins is free (as long as it can
be executed by Python), the following organization is suggested. These
plug-ins will be visible in the Plug-ins Editor, and therefore having
a common format makes it easier for users to understand the goal of the
plug-ins:

     <ul>
<li>Comment

     <p>The first part of the script should be a general comment on the goal and
  usage of the script. This comment should use python's triple-quote
  convention, rather than start-of-line hash ('#') signs.

     <p>The first line of the comment should be a one liner explaining the goal
  of the script. It is separated by a blank line from the rest of the
  comment.

     <p>The rest of the comment is free-form.

     <li>Customization variables

     <p>If your script can be configured by the user by changing some global
  variables, they should be listed in their own section, and fully
  documented. The user can then, through the /Tools/Plug-ins editor
  change the value of these variables

     <li>Implementation

     <p>The implementation should be separated from the initial comment by a
  form-feed (control-L) character. The startup scripts editor will know
  not to display the rest of the script on the first page of the editor.

     <p>Generally speaking, scripts should avoid executing code as soon as they
  are loaded. This gives a chance to the user to change the value of global
  variables or even override functions before the script is actually launched.

     <p>The solution is to connect to the <code>"gps_started"</code> hook, as in

     <pre class="smallexample">            ^L
            ###########################################################
            ## No user customization below this line
            ###########################################################
          
            import GPS
          
            def on_gps_started (hook_name):
               ... launch the script
          
            GPS.Hook ("gps_started").add (on_gps_started)
</pre>
     </ul>

<h5 class="subsubsection">16.5.1.2 XML files</h5>

<p>XML files must be utf8-encoded by default. In addition, you can
specify any specific encoding through the standard <code>&lt;?xml
encoding="..." ?&gt;</code> declaration, as in the following example:

<pre class="smallexample">     &lt;?xml version="1.0" encoding="iso-8859-1"?&gt;
     &lt;!--  general description --&gt;
     &lt;submenu&gt;
       &lt;title&gt;encoded text&lt;/title&gt;
     &lt;/submenu&gt;
</pre>
   <p>These files must be valid XML files, i.e. must start with the
<code>&lt;?xml?&gt;</code> tag, and contain a single root XML node, the name of which is
left to your consideration. The general format is therefore

<pre class="smallexample">     &lt;?xml version="1.0" ?&gt;
     &lt;root_node&gt;
        ...
     &lt;/root_node&gt;
</pre>
   <p>It is also recommended that the first line after the <code>&lt;?xml?&gt;</code> tag
contains a general comment describing the purpose and usage of the script. 
This comment will be made visible in the Plug-ins editor.

   <p>The list of valid XML nodes that can be specified under &lt;root&gt; is
described in later sections. It includes:

     <dl>
<dt><code>&lt;action&gt;</code><dd>(see <a href="Defining-Actions.html#Defining-Actions">Defining Actions</a>)
<br><dt><code>&lt;key&gt;</code><dd>(see <a href="Binding-actions-to-keys.html#Binding-actions-to-keys">Binding actions to keys</a>)
<br><dt><code>&lt;submenu&gt;</code><dd>(see <a href="Adding-new-menus.html#Adding-new-menus">Adding new menus</a>)
<br><dt><code>&lt;pref&gt;</code><dd> (see <a href="Preferences-support-in-custom-files.html#Preferences-support-in-custom-files">Preferences support in custom files</a>)
<br><dt><code>&lt;preference&gt;</code><dd> (see <a href="Preferences-support-in-custom-files.html#Preferences-support-in-custom-files">Preferences support in custom files</a>)
<br><dt><code>&lt;alias&gt;</code><dd>(see <a href="Defining-text-aliases.html#Defining-text-aliases">Defining text aliases</a>)
<br><dt><code>&lt;language&gt;</code><dd>  (see <a href="Adding-support-for-new-languages.html#Adding-support-for-new-languages">Adding support for new languages</a>)
<br><dt><code>&lt;button&gt;</code><dd>  (see <a href="Adding-tool-bar-buttons.html#Adding-tool-bar-buttons">Adding tool bar buttons</a>)
<br><dt><code>&lt;entry&gt;</code><dd>  (see <a href="Adding-tool-bar-buttons.html#Adding-tool-bar-buttons">Adding tool bar buttons</a>)
<br><dt><code>&lt;vsearch-pattern&gt;</code><dd>  (see <a href="Defining-new-search-patterns.html#Defining-new-search-patterns">Defining new search patterns</a>)
<br><dt><code>&lt;tool&gt;</code><dd>  (see <a href="Adding-support-for-new-tools.html#Adding-support-for-new-tools">Adding support for new tools</a>)
<br><dt><code>&lt;filter&gt;</code><dd>  (see <a href="Filtering-actions.html#Filtering-actions">Filtering actions</a>)
<br><dt><code>&lt;contextual&gt;</code><dd>  (see <a href="Adding-contextual-menus.html#Adding-contextual-menus">Adding contextual menus</a>)
<br><dt><code>&lt;case_exceptions&gt;</code><dd>  (see <a href="Adding-casing-exceptions.html#Adding-casing-exceptions">Adding casing exceptions</a>)
<br><dt><code>&lt;documentation_file&gt;</code><dd>  (see <a href="Adding-documentation.html#Adding-documentation">Adding documentation</a>)
<br><dt><code>&lt;doc_path&gt;</code><dd>  (see <a href="Adding-documentation.html#Adding-documentation">Adding documentation</a>)
<br><dt><code>&lt;stock&gt;</code><dd>  (see <a href="Adding-stock-icons.html#Adding-stock-icons">Adding stock icons</a>)
<br><dt><code>&lt;project_attribute&gt;</code><dd>  (see <a href="Defining-project-attributes.html#Defining-project-attributes">Defining project attributes</a>)
<!-- @item <docgen_backend> -->
<!-- (@pxref{Defining a documentation format}) -->
<br><dt><code>&lt;remote_machine_descriptor&gt;</code><dd>  (see <a href="Defining-a-remote-server.html#Defining-a-remote-server">Defining a remote server</a>)
<br><dt><code>&lt;remote_path_config&gt;</code><dd>  (see <a href="Defining-a-remote-path-translation.html#Defining-a-remote-path-translation">Defining a remote path translation</a>)
<br><dt><code>&lt;remote_connection_config&gt;</code><dd>  (see <a href="Defining-a-remote-connection-tool.html#Defining-a-remote-connection-tool">Defining a remote connection tool</a>)
<br><dt><code>&lt;rsync_configuration&gt;</code><dd>  (see <a href="Configuring-rsync-usage.html#Configuring-rsync-usage">Configuring rsync usage</a>)
</dl>

<!--  -->
   </body></html>