~stephen-j-boddy/terminator/bugfix-1318542-double-chars

.. image:: imgs/icon_gettinginvolved.png

   :align: right

   :alt: Saefty first when breaking out the power tools.

 

=============================

Getting involved

=============================

 

There are many ways to help out, and they don't all involve coding.

 

-----------------------------

Translations

-----------------------------

 

Sprechen Sie Deutsch?

 

Awesome! I've been getting my head around the whole translation

bit (English polyglot I'm afraid), and as a result there has been

a lot of churn in the translations. So what are you waiting for?

 

Speak some other language? Take a look at

https://translations.launchpad.net/terminator because you might

just be the <insert language here> speaker that we're looking for.

 

-----------------------------

Improve icons/artwork

-----------------------------

 

OK, so while the main icon contributed by Cory Kontros is really

good, my hacks of it are... not so good. I'm no artist, but I do

appreciate them. So if you think you could apply some polish and

a cohesive design to this manuals page header images, please, give

it a go. It may only be to take the existing icon and to make it

suck less.

 

The only thing I would ask is that you maintain the main icon as

a base like I have done.

 

-----------------------------

Terminator action shots

-----------------------------

 

This one's just for "PR" purposes. I want to see famous/awesome

people kicking ass *and* chewing bubble-gum with Terminator in the

mix.

 

If you spot it in a TV show, movie, or a news article I want to

know. Maybe you're even the famous/awesome person, in which case

drop me a note.

 

It will warm the cockles of my heart to know that Terminator made

life easier for people who do the really important stuff like

discovering new particles (CERN? Hello?), boldly going (NASA? Come

in Houston), or wrangle 2 more frames per second from Half-Life 3

(Valve? Confirmed?)

 

Here's the ones spotted and noted (I've seen quite a few others

previously, but never thought to note them)

 

- `MindMaze`_ - VR / mind-reading.

    Visible in the background of the video, and in an image lower down

    the page. (The Verge)

 

.. _MindMaze: http://www.theverge.com/2015/3/3/8136405/mind-maze-mind-leap-thought-reading-virtual-reality-headset

 

-----------------------------

Manual updates

-----------------------------

 

This manual is a new endeavour to fully document all the nooks and

crannies of Terminator. As such, there may be things that are missing,

incorrect, not explained clearly, or need expanding.

 

Suggestions, or updates are welcome.

 

I had a little exposure at work to Sphinx, so I thought I'd dig in

a bit deeper and learn  a bit about it. So far I'm happy enough, so

till further notice this manual will remain in this format.

 

If you're feeling like a loquacious polyglot you could attempt to

translate the whole manual. So far I haven't tested it, but in

principle, just do a checkout of the trunk, and do a full copy of

the ``doc/manual`` folder to ``doc/manual_XXXX`` where XXXX is the

i18n language code. This is usually just the two or three letters of

the language code, but sometimes has the region too... Or something

else entirely in a couple of cases.  A couple of examples::

 

  pt            - Portugese

  pt_BR         - Brazilian Portugese

  ca            - Catalan

  ca@valencia   - Catalan (Dialect specific to Valencia?)

  

Then just translate away, and take new screen grabs to replace the

British English ones I've done. If someone was to make a serious

effort to translate the manual, I'm sure we can get it included.

 

The Help shortcut checks the LANGUAGE environment variable, and tries

those folders in order, before falling back gracefully to the default

manual, which is British English anyway::

 

  LANGUAGE=en_GB:en

 

So this is going to try:

 

+ *html_en_GB* - the non-existent British English folder

+ *html_en* - the non-existent generic English folder

+ *html* - the default document that happens to be in British English

 

.. note:: Although the source is in a folder beginning with ``manual``,

          that gets replaced with ``html`` for installation.

 

.. note:: If there are any Americans offended by correct spelling,

          they are more than welcome to create an Americanised

          version, and I'll relegate it to the en_US folder. The

          default will remain British English.

 

In order to create the html for manual, you must have the sphinx_rtd_theme

package installed. This does not appear to be packaged for Ubuntu

14.04 LTS as far as I can tell. This means you must install it using

the pip tool. This may need installing on your system too with::

 

    sudo apt-get install python-pip

 

Once that is installed you can install the theme with::

 

    sudo pip install sphinx-rtd-theme

 

This will take care of installing the theme and it's dependencies.

 

.. warning:: On Ubuntu this also installed a newer version of *Sphinx*

             under the ``/usr/local`` folder. This caused a bit of

             confusion at one point, so be aware.

 

-----------------------------

Testing

-----------------------------

 

Just use it, explore the features, and complain when they don't work.

 

We actually have quite a lots of outstanding issues, and in many

cases I can't reproduce due to either lack of info, differences in

environment, lack of information, or because the bug is so old the

original raiser has moved on and not available for questions.

 

I'm particularly interested in cases where I can't even see that

something is an issue, such as:

 

- *Right-to-Left* - I can force Terminator to Arabic, and everything

  flips around, but I have no idea if it looks "right" to a native

  speaker. Frankly it just looks *weird!*

- *HighContrast* - Again, I can switch to it, but perhaps I'm not

  appreciating the needs of that group.

- *Accessibility* - People using only a keyboard, or only a mouse,

  on-screen keyboards, text-to-speech, speech-to-text, and so on.

 

-----------------------------

Bugs

-----------------------------

 

- **Fixing** - OK, so yeah, this is coding.

- **Reproduce and improving** - Sometimes bugs are lacking info to

  reproduce, or my system is too different. Or perhaps the original

  poster has moved on because we haven't fixed their pet peeve fast

  enough.

- **Triaging** - It's one of the less glamorous jobs, but someone's

  gotta do it. Shepherd bugs to the point where it has a priority,

  a milestone, reproduction steps, confirmation, submitted patches

  validated, and so on.

 

See https://bugs.launchpad.net/terminator

 

-----------------------------

Plugins

-----------------------------

 

Ahem... Yeah... More coding...  

 

Some :ref:`plugins` may have room for improvement, or perhaps you have

an idea for a neat plugin no-one else has done.

 

-----------------------------

Main Application Development

-----------------------------

 

Oh come on... Coding? Again!

 

I see lots of people say how Terminator is really good, and it is,

but like anything, it could be better!

 

To give an idea, as I write this manual in July 2015, there are 83

`wishlist items`_.

 

.. note:: Just because an item is marked as wishlist, it doesn't

          mean that a great deal of thought has been put into the

          appropriateness of the idea on my side. It may be impossible,

          or not a good fit, or just plain bat-sh!t crazy. If you

          want to pick up a wishlist item that looks like a lot of

          work (especially if it makes fundamental changes to the

          Terminator ethos) it's probably best to check first that

          your approach is good, and has a realistic chance of being

          merged.

 

Some of these wishlist items are also in my own text file of "Things

to do" / "Big bag of crazy", which as of August 2015, revision 1598,

looks like this::

 

    Enhancements which may, or may not, have a wishlist item

    ========================================================

    Finish the WIP window icons

 

    Add a list of the default keybindings to the Preferences -> Keybindings window?

 

    Add libunity quicklist of saved layouts

        https://wiki.ubuntu.com/Unity/LauncherAPI#Python_Example

        http://www.techques.com/question/24-64436/Refreshing-of-Dynamic-Quicklist-doesn%27t-work-after-initialization

        http://people.canonical.com/~dpm/api/devel/GIR/python/Unity-3.0.html

        Possibly use the progress bar and or counter for something too.

 

    Add an appindicator menu for launching sessions.

 

    Layout Launcher

        Could bind the shortcut as a global toggle to hide show

        Could save

            window position/size

            hidden status

            always on top

            pin to visible workspace

 

    Layout needs to save/load more settings

        Per layout?

            Group mode status (all, group, off)

            Split to this group

            Autoclean groups

        Per window

            always on top

            pin to visible workspace

        Per tab

        Per terminal

            Store the custom command and working directory when we load a layout, so making small changes and saving doesn't lose everything.

            It could be possible to detect the current command and working directory with psutil, but could be tricky. (i.e. do we ignore bash?)

 

    A per layout "save on exit" option to always remember last setup/positions etc. Probably requires above to be done first.

 

    Preferences

        Layouts

            Have changing widgets depending on what is selected in the tree

            Terminal title editable

 

    Config

        Items should be sorted for saving. Easier for comparing and spotting changes.

 

    Give plugins ability to register shortcuts

 

    Missing shortcuts:

        Context menu (in addition to Windows menu button - not always available on all keyboards)

        Group menu

        Open preferences

        Open a shortcut help overlay

        Change tab text (#1054300-patch), titlebar text, group name

        Toggle titlebar visibility

        Equalise the splitters

        Launch help (F1)

        Zoom +receiver in/out/reset

        Zoom all in/out/reset

        Last terminal (again to jump back to original) #1440049

 

    Drag and Drop

        Terminal without target opens new window

        Tab to different/new window depending on target

 

    Improve DBus interface, add coordination between sessions, i.e.:

        multiple DBus ports? register them with a master DBus session, be able to query these, etc

        be able to drive them more with command line commands, and not just from within own shell

        Remotinator improvements

 

    Abstract out the session/layout allowing multiple logical layouts in the same process to reduce resource used

        This is a big piece of work, as a lot of the Terminator class would need seperating out.

 

    Hide window should find the last focussed window and hide that. Second hit unhides and focusses it

        Add a power hide to hide all of shortcut bound instances windows

        Use the dbus if available to hide the current active window, then unhide it on second shortcut press

        If the dbus is available:

            The hide will go to the focussed instance, instead of the first to grab the shortcut

            Add a super power hide to hide all Terminator windows

            In both cases a second shortcut unhides whatever was hidden

 

    Split with command / Inherit command/workdir/groups etc

 

    Somehow make Layout Launcher, Preferences, & poss. Custom Commands singleton/borg (possibly use dbus)

 

    Custom Commands is blocking, perhaps make non-blocking

 

    Button in prefs to duplicate a layout

 

    Check widget for close_button_on_tab in prefs.

 

    When in zoomed/maximised mode

        Perhaps the menu could contain a quick switch sub menu, rather than having to Restore, right-click, maximise

        Shortcuts for next/prev,up/down/left/right, etc. How should they behave

 

    Limit broadcast group/all to current tab

 

    Broadcast off when maximised or zoomed to single term

 

    All non main windows to be changed to glade files

 

    For me the two different sets of next/prev shortcuts are a bit of a mystery.

 

    Add preselection to the profile tab

 

    Figure out how to get the tree view to jump to selected row for prefseditor

 

    Ability to insert window, titlebar, or group value into terminal(s)

 

    Let window title = terminal titlebar - perhaps other combos. Some kind of %T %G %W substitution?

 

    If we can figure out how to do arbritrary highlighting, perhaps we can get a "highlight differences" mode like used to exist in ClusTerm.

        This could also be limted to highlighting diffs between those in the same group.

 

    Add large action/status icons for when titlebar is bigger.

 

 

    Issues encountered which may, or may not, already have an LP bug

    ================================================================

 

    BUG: Issue if initial window (no tabs) has any splits, then creating new tab causes the first tab to be misnamed, gtk2 & gtk3.

         Also on GTK3 only (but cannot reproduce now): it also causes a problem if using the "Menu" key to open the context menu

         on the unamed tab; it does not dissappear by clicking out of it.

 

    BUG: Ctrl+right-click-drag does not work. Can initiate drag, but no targets work.

 

    BUG: Zoom and maximise do not work if single terminal in a tab, gtk2 & gtk3.

 

    BUG: If first tab is split the tabs label width increases and pushes others off window gtk3 (in gtk2, the label shifts right, but other tabs OK)

 

    BUG: With longer translations the buttons in the prefs sidebars can get chopped off.

 

    BUG: Groups: Create two tabs with splits. Super+G (group all), move to other tab and Super+T (group tabs), move back and type

        Output in tab group too. Also for custom groups.

        Ungrouping all also nukes changed groups. Right?

        Also with Super+T and changing one terms group, still receives input, and loses custom group when turning off tab group.

 

    BUG: Hide on lose focus broken. LP#843674

        focus-out signal callback defers (idle_add) the call to hide.

        If one of our own windows/menus pops up, an inhibit flag is set.

        When the window/menu is closed we call a deferred hide on the main window

        In the deferred function, we check if we now have focus, and do not hide

        In the deferred function, we check if inhibit is set and do not hide.

 

So as you can see, still lots of room for improvements, and plenty of

ideas if you are trying to find small starter tasks.

 

.. _wishlist items: https://bugs.launchpad.net/terminator/+bugs?field.searchtext=&orderby=-importance&search=Search&field.status%3Alist=NEW&field.status%3Alist=CONFIRMED&field.status%3Alist=TRIAGED&field.status%3Alist=INPROGRESS&field.status%3Alist=INCOMPLETE_WITH_RESPONSE&field.status%3Alist=INCOMPLETE_WITHOUT_RESPONSE&field.importance%3Alist=WISHLIST&assignee_option=any&field.assignee=&field.bug_reporter=&field.bug_commenter=&field.subscriber=&field.structural_subscriber=&field.tag=&field.tags_combinator=ANY&field.has_cve.used=&field.omit_dupes.used=&field.omit_dupes=on&field.affects_me.used=&field.has_patch.used=&field.has_branches.used=&field.has_branches=on&field.has_no_branches.used=&field.has_no_branches=on&field.has_blueprints.used=&field.has_blueprints=on&field.has_no_blueprints.used=&field.has_no_blueprints=on

 

-----------------------------

GTK3 Port

-----------------------------

 

Last coding one, I promise!

 

After some sterling work by Egmont Koblinger, one of the VTE

developers, he came up with a very large patch for rudimentary GTK3

support. A number of things were incomplete or broken, but it got it

far enough along that it was no longer an insurmountable cliff face.

 

Since then I have resolved to port fixes and features between the

two versions. As I do this I explore and find outstanding issues with

the port, and it is slowly becoming more usable.

 

Eventually the GTK2 version of Terminator will go into a

deprecated/maintenance mode. Unfortunately due to needing a relatively

new version of libvte, that switch will not be in the immediate

future. I'm running trusty (14.04 LTS) and even there I had to build

libvte 0.38 from source. This makes the GTK3 out of reach for the

"Joe Bloggs" of the world. I could try and maintain my own PPA of the

component, but that doesn't help Fedora/OpenSUSE/Arch etc. users.

Even getting "Joe Bloggs" to add a PPA can be a struggle.

 

And for a real nightmare, I tried to compile the 0.40 version and the

thing lit up with a smorgasbord of items where my installed packages

were not new enough.

 

If you are feeling brave and adventurous, there are some instructions

in `comment #15`_ of the `porting bug`_ that will help you get the

GTK3 version running. Assistance knocking off the remaining rough

edges will be very much appreciated.

 

For the record, as of August 2015, with the `gtk3 branch`_ at revision

1577, these are the outstanding items::

 

    Outstanding GTK3 tasks/items/reviews etc remaining

    ===================================================

    Outstanding trunk revisions: 

    If titlebar text wider than window, the visual bell icon does not appear

    If editing label in titlebar, the whole layout gets distorted until finished, then snaps back to mostly correct layout

    In High contrast mode the titlebar background only works over the group button

    In High contrast mode the titles are invisible for terminals with a group

    Fix/reimplment the DBUS for GTK3. GI seems incomplete with no Server. Try to get old style working again.

    Need to go through all the Gtk.STOCK_* items and remove. Deprecated.

    Homogeneous_tabbar removed? Why?

    Need to set the version requirements - how? needed?

    terminal.py:on_vte_size_allocate, check for self.vte.window missing. Consequences?

    terminal.py:understand diff in args between old fork and new spawn of bash. Consequences?

    VERIFY(8)/FIXME(8) FOR GTK3 items to be dealt with

 

    For future with vte0.40+ - reimplment/restore the word_chars stuff.

 

    Not fixable so far as I can see

    ===============================

    [Function N/A in 0.38+, will it return?] visible_bell - removed and not mentioned. Check capability not possible, or can be faked.

 

Once the GTK3 port is done there is also a long overdue port to

Python3, especially in light of some distributions trying to

eliminate Python2 from the base installs. Yes, Python2 will be with

us for a long time yet, but this should serve as a warning.

 

.. _comment #15: https://bugs.launchpad.net/terminator/+bug/1030562/comments/15

.. _porting bug: https://bugs.launchpad.net/terminator/+bug/1030562

.. _gtk3 branch: https://code.launchpad.net/~gnome-terminator/terminator/gtk3

 

--------------------------

API Docs

--------------------------

 

Strictly speaking this isn't an API as such, because it is just using

sphinx-apidoc over the Terminator code base. It's perhaps helpful to

have this as a document that can be browsed.

 

`Terminator API docs`_

 

As it stands, this is rather incomplete, or too terse with no examples

given. If you look at the terminatorlib.configobj package, you will

see fairly extensive documentation, along with walk-throughs, etc. This

particular package was written elsewhere, and brought into Terminator

to provide configuration handling.

 

There are also some aspects of the way this document builds that I'm

not too happy about. The seemingly unnecessary ``terminatorlib``

root-node in the side bar; the lack of class/method links in the

sidebar; all ``.py`` files on the same page (this can be changed, but

then even less is displayed in the sidebar.) If you can help, join

the A-Team... Or better yet, send me some changes that fix this.

 

.. _Terminator API docs: ../apidoc/index.html