oracc / nammu

Oracc GUI

oracc sources

Sources for Oracc.

Setup

Please refer this setup guide for setting it locally and this setup guide for setting it up on a server.

nammu's Issues

Error validation messages

Niek said it'd be very useful to display validation errors accompanied by line/column number in text file. Update mockups to reflect this. Action: option to show/hide line/column numbers in text editor – Raquel to update mockups. Nice to have: Error highlighting in both object model and text editor.

Add functionality for users to change from local keyboard to Unicode and viceversa

Users are used to change keyboards from local to a custom keyboard created by Steve to ease Unicode transliteration. Having a button in the tool to change keyboards would come in handy. Action: Raquel to update mockups to reflect this. Need to check how Java handles this kind of thing, as users with different operating systems and local keyboard configurations (users with German keyboards in particular?) have trouble with this sometimes.

Steve suggests keyboard mode defaults to local when adding a translation, and defaults to Unicode when adding text lines, but always offer the option to change keyboard configuration to the user.

Mockup screens to discuss GUI design with project owner

This tool looks nice: http://www.mockflow.com

Default text area to UTF-8

Console/Popup to display error/success messages

Steve suggests syntax validation messages appear in the console, and lemmatization messages appear in a pop up. Update mockups.

Test connection to server for lemmatization

Remind Steve to send Raquel an email with the connection details and/or permissions on the server code in Github when made public (“oman” project?)
It was clarified that the query to the server requires the whole ATF file as input, which is then processed in the server (lemmata are added, and if they already had been, then checks for “x” chars and re-lemmatize) and returns the resultant ATF file to the client..
Write a short piece of code to try out connection once Steve sends the details to confirm everything works as expected.

Consider open more than one file at a time

At the moment only one file can be edited/displayed. It'd be good to be able to open several files in separated tabs or windows so that it's possible to compare.

Icons not being displayed in toolbar buttons

Maybe need an absolute path or URL? Icons are in the resources folder and relative paths are not working for some reason. No error messages given, the icons are just not appearing. By now since it's only a mockup, I'll leave the toolbar buttons displaying text instead.

Create Nammu GUI mockup in Jython with basic file edition functionality

Create a GUI in Jython using Maven and PyOracc following the layout in the mockups agreed in the last meeting that follows a MVC architecture.
It should have a menu, a toolbar, a text area and a console for log display.
The menu and toolbar should display these options for the user to choose:

File
 ├── New
 ├── Open
 ├── Save
 ├── Close
 └── Quit

Edit
 ├── Undo
 ├── Redo
 ├── Copy
 ├── Cut
 └── Paste

ATF
 ├── Validate
 └── Lemmatise

Window
 ├── Model View
 ├── Unicode Keyboard
 ├── Hide/Show Console
 ├── Hide/Show Toolbar
 └── Preferences

Help
 ├── Help
 └── About

Make Maven download the necessary python libraries that pyoracc uses

These plugin is working and easy_installing all the necessary python modules (although it gave some trouble with mako and jinja and I had to downgrade mako from v1.1 to v0.9.1), but they are not being properly imported by the jython code, can't figure out why.

            <plugin>
                <groupId>net.sf.mavenjython</groupId>
                <artifactId>jython-compile-maven-plugin</artifactId>
                <version>1.1</version>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>jython</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <libraries>
                        <param>nose</param>
                        <param>ply</param>
                        <param>https://pypi.python.org/packages/source/M/Mako/Mako-0.9.1.tar.gz</param>
                    </libraries>
                </configuration>
            </plugin>

Logging system

Nammu needs a logging system that'll be displayed in the console. Any useful libraries for this in python or just use log4j?

Decide what functionality from Emacs' plugin to inherit - Low priority

Emacs presents options that might be needed to be included in Nammu, eg:

• Generate template
• Harvest
• Count lemmata

There are two types of users: people who creates/edits texts and project managers. Managers use “Count lemmata” to check the number of lemmata in a text and track progress of work. We need to add this option to Nammu in a later stage of development. Same with the “Harvest” option?
The “Generate template” option is not used very often, so don’t implement it in Nammu.
Add these options to the mockups.

Decide where to display model view

Should it be a separate window, should be an alternative to text view (AtfEditArea would have two contexts, one being model and another being text), should just be another panel in the main GUI shown in parallel?
Initially, since it's the easiest for developing an initial mockup, it'll just be displayed in a separate window.
The other options would imply refactoring.

JFileChooser needs polishing

• It doesn't allow going back to the previously selected folder.
• It'd be nice it doesn't open at $HOME but current folder.
• Add a top panel if possible to give an explanation like "Choose somewhere to save your ATF file", etc

New functionality: access to corpus from Nammu

Steve mentioned he'd upload the whole corpus to Github, Nammu could link to it.

Menu and Toolbar views: avoid duplication

Both views need some refactoring to simplify the code. Maybe an abstract factory would do.

Create installable for Nammu - low priority

Nammu gets packaged in a jar file that is executable in any platform running a JRE, but it'd be nice to have an installable that is cross-platform.

I've been doing some research and found out IzPack that seems to be able to do the job. Have a look at some instructions here.

It requires quite a lot of Maven configuration work. The clean way is setting up a multi-module Maven build, using one module for building or just assembling the application, making a ZIP artifact of plain files and extracting them in a second module containing the IzPack build which just includes them as in install.xml. This way the dependency management is not messed up, exactly dependencies used for compiling/running the app and those for running the installer.

The installable would also need to be wrapped with Launch4J or JSmooth, which look for the system's JRE and downloads/install/update it if needed.

Also check out DCPSetupMarker and PackJacket GUI front ends to make installables.

Syntax highlight in text area

Make syntax highlight based on the pyoracc parser.

Maybe use this Pygments library?

Fix toolbar layout

• Make separations in between buttons
• Change button design to something more uniform
• General prettifying - checkout some LAFs

Test jar in different VMs

Check that Nammu's jar is executable cross-platform.

Bracket-checking functionality

Bracket checking functionality including (), [], {}.

Manipulate ATF locally - text mode

This includes:

• Create ATF locally
• Edit ATF locally
• Save ATF locally

Avoid code duplication in MenuController and ToolbarController

Both controllers have similar functionality that is delegated to the main controller. Create a parent class for these too to inherit from to simplify code.

Send Niek a draft version of Nammu when it's ready

Keep Niek in the loop as he’s the one from the team writing ATFs the most and willing to test the tool. He also works a lot with new users, which are the ones that will use the model view the most.

Mockup model view for Belsunu

When user chooses to display model view, pop up a new window with the model view for an ATF like Belsunu.

Create own updated version of net.sf.mavenjython's jython-compile-maven-plugin

Check out plugin's code here.

It's not been updated since 2011 and it'd be a good idea to change it to at least stop using
setuptools-0.6c11-py2.5.egg and use a more recent version like setuptools-0.6c11-py2.7.egg instead. Or make configurable which version of setuptools to use. Or maybe use pip.
Otherwise I can only use outdated versions of Mako (0.9.1 instead of 1.0.2) and Ply (3.4 instead of 3.5), which work but are not ideal.

Once updated, it'd be nice to put it in my own maven repo, or create RSDT's maven repo, if there isn't one yet.

Send Raquel Steve's initial documents about expected functionality and project timings

Steve mentioned in last meeting that he created some documents at the beginning of the project with information on what functionality is expected and when. He asked us to review them when planning next months of work. Where are they?

Check ATF files in the ORACC server

• Validate ATF files (this will be done with the parser eventually)
• Lemmatise
• Ask Steve/Eleanor what other actions they want to do in the server.

License Nammu's code

It has no license at the moment. I need to:

• Get permission from Eleanor to license the code.
• Choose which license to use (most likely BSD or GPL).
• Create a License.md in the repo/s.
• Add to headers a couple lines with Copyright info and link to License file.

Document Model-View-Controller architecture

Make some nice diagram to show to Eleanor/Steve/James.

Write up requirements

Update repo's issues with these requirements from Eleanor and send document to @jamespjh :

Dear Raquel,

I’ve just returned from a very useful few days in Philadelphia, at the annual Oracc steering group meeting with Niek and Steve, whom you’ve met, and new recruit Jamie. One of the topics we discussed was your work on Nammu: the very pleasing progress that you’ve made so far, and what we think should be the priorities for the next phase of development.

Here are some notes, and I’d be happy to discuss them further with you if that would be helpful.

TIMING: 
We want to be able to present Nammu — and train colleagues how to use it — at a major conference that will be held in Philadelphia on 11-15 July 2016. So realistically our deadline for completing the first phase of development should be a few weeks prior to that. By ‘Phase 1’ we mean — as previously agreed — creating, editing, and saving ATF files locally, and checking ATF on the Oracc server (more details below).

COMPATIBILITY:
Steve and I had no problems opening and running Nammu on up-to-date MacBook Air. But our colleague Niek, who runs a Windows machine, could open files in Nammu but not in the model view, and Jamie says he could not open it at all on a MacBook (I have asked them for further information). This ATF file (attached) would not open at all.

FEATURES:
There’s no need to prioritise @composite or @score type files, as the vast majority of the Oracc corpus is @tablet.

Our previous list said:

• default to utf-8
• syntax colourisation
• bracket-checking
• built-in oracc keyboard with toggle
• show multiple views of text with independent scrolling

Some comments/amendments to those desiderata:

1. As I suggested when we last met, we don’t want users to be able to toggle to ASCII
2. Rather than building in the Oracc keyboard, it would be better to have a character picker for the main transliteration characters (I’ve made a list of these below).

There are also a few desirable features which we didn’t articulate explicitly before Nammu existed, but which now become easier to articulate. From within the Model view ee’d like users to be able to:

* create a new ATF-text
* choose protocols, languages etc
* view & edit structure @-lines

I hope that all makes sense; do let me know if you’d like us to discuss any of it in more detail.

Most gratefully, as always,

Make JFileChooser allow only text files to be opened in Nammu

I've added a filter to prevent the user from clicking on files that are not "*.atf", but it is not working properly. Having these filter applied highlights the .atf files, but doesn't hide the non-atf files, which remain clickable and thus "openable".

        fileChooser = JFileChooser()
        filter = FileNameExtensionFilter("ATF files", ["atf"])
        fileChooser.setFileFilter(filter)
        status = fileChooser.showDialog(self.view, "Choose file")

Move PyOracc's test folder to proper Maven standard test folder

Update mockups to reflect different types of translations

Translations complicate the model view: line-by-line/interlinear ones are easy to represent, but labeled and unitary are not linked to specific text lines. Steve suggests that the model view represents only the interlinear ones in a first stage, and consider later to present the other kinds of translations as another element in the stackpile for an object.

Console panel: scroll doesn't focus on last added line

Need to find a way to make the JScrollPane to scroll all the way down to the end when a new line is added.

See some help here, although seems a bit outdated.

Model View: Show non-composite sides in a stackpile

Composite ATFs have no structure, they are just a sequence of lines, they have no @-lines. Non-composites do. This makes things easier to represent in Nammu's model view, since composites can have a tab per &-line, and non-composites can have a stack panel per object side, as suggested by Eleanor. What can bring some extra complexity is handling columns and tables in non-composite files - would a column on a side be treated as another form of side? Discuss when ready to develop it.

Unicode characters not being properly displayed in JTextArea

When reading an ATF file and printing it out in the terminal, I get the correct content of my text file Belsunu.atf, e.g.:

#lem: šatti[year]N; n; Ṭebetu[1]MN; mūša[at night]AV; ūm[day]N; n

But when printing the same text in a JTextArea, I get this instead:

#lem: šatti[year]N; n; Ṭebetu[1]MN; mūša[at night]AV; ūm[day]N; n

This is the code dealing with opening ATF files and displaying them in the text area:

MainController.py

    def openFile(self):
        fileChooser = JFileChooser()
        filter = FileNameExtensionFilter("ATF files", ["atf"])
        fileChooser.setFileFilter(filter)
        status = fileChooser.showDialog(self.view, "Choose file")

        if status == JFileChooser.APPROVE_OPTION:
            atfFile = fileChooser.getSelectedFile()
            atfText = self.readTextFile(atfFile)
            self.atfAreaController.setAtfAreaText(atfText)
            print atfText

    def readTextFile(self, file):
        filename = file.getCanonicalPath()
        f = open(filename, "r")
        text = f.read()
        return text
        #TODO: Check if selected file is ATF or at least text file!

AtfAreaController.py

    def setAtfAreaText(self, text):
        self.view.editArea.setText(text)

Do some BDD to test the GUI

I'm trying Cucumber at the moment. There doesn't seem to be any non-web BDD solutions for Java Swing that I can find. Perhaps Cucumber will do?

Show multiple views of text with independent scrolling

From last time we talked, I think Eleanor referred to a split view with independent scrolling.

Plan UCLDH seminar with Eleanor

Dear Raquel and Eleanor,

I’ve been asked by Melissa Terras, Director of UCLDH, to invite you to give a talk on the ORACC project as part of our 2015-16 seminar series.  Our seminars run from 5:30-6:30pm, with drinks and a chance for discussion to follow.  The dates for next year’s series are as follows:

Term 1
Weds 7 Oct
Weds 28 Oct
Weds 25 Nov 

Term 2
Weds 20 Jan
Weds 3 Feb
Weds 24 Feb 

Term 3
Weds 27 April
Weds 11 May
Weds 25 May

Please let me know if you would be interested tin taking part and if any of these dates are convenient. If not, we can be flexible, so do feel free to suggest some alternatives. 

The programme for 2014-15 can be found on our events pages: http://www.ucl.ac.uk/dh/events/UCLDHseminar 

Kind regards,
Sarah

It'd be nice to present Nammu before the conference on July 2016 in Term 3 and get some feedback from UCLDH.

Have a look at ORACC's proposal doc from the beginning of the project

Some functionality not discussed yet might be hiding there. Use this and the latest meeting's notes to build a list of use cases.
Docs are here and notes are here.

Create tests for Nammu's GUI

I'll need help from @jamespjh probably :)

maven-assembly-plugin is executing twice consecutively

For some reason when running mvn install maven-assembly-plugin is executing twice. I've looked in the effective-pom and I can't see why this would happen. Needs investigating.

Nammu doesn't fully work on Niek's Windows Vista 32-bit computer and Jamie's Mac laptop.

Eleanor visited the US for the annual ORACC steering group meeting and discussed Nammu with her colleagues Steve Tinney, Niek and Jamie. Steve and Eleanor can run Nammu with no problems, but Eleanor reported:

Steve and I had no problems opening and running Nammu on up-to-date 
MacBook Air. But our colleague Niek, who runs a Windows machine, could 
open files in Nammu but not in the model view, and Jamie says he could 
not open it at all on a MacBook. 

And:

Neither Niek or Jamie could run the java commands. Niek says he is using
"an old Windows Vista laptop with the latest Windows 32-bits Java” and
Jamie says, Mac OS X Yosemite version 10.10.3 (14D136) with JDK 8 (update
45). 

They have also sent this ATF file which can't be opened in Nammu at all.

I'm waiting to see what exactly they meant but not being able to run the java commands. I asked them to run

java -version

and

java - jar </path/to/nammu.jar>

I'll investigate further when I have that information.

Compatibility issues reported by Eleanor

Eleanor reported her colleagues Niek and Jamie had trouble opening one file in Nammu and running the jar file, respectively.

Extend functionality when creating new ATF

When creating a new ATF with Nammu, present user with form to insert object ID and metadata (language, project, etc). Nice to have: Request ID to CDLI from Nammu (specially useful for PXXXXX ids), optionally see list of catalogue entries? To discuss later with Steve/Eleanor.
Update mockups with this functionality.

PyORACC doesn't work with latest version of Ply

Ply is in version 3.8 now and when PyORACC was developed it was still 3.4. It doesn't seem to work, with latest version, need to investigate.

Resolve pull request

Look at suggested changes and learn pythony stuff.

Quest to find the best way of making a GUI for pyORACC

Options considered:

• Swing from Jython -> works but Swing is a bit outdated and not so developer-friendly for MVC architectures. Most likely option, though.
• JavaFX from Jython -> JavaFX is the best, really good for MVC, quick to develop, shiny looking, easy to deploy, works on mobile platforms, can be easily embedded in HTML, ... BUT jython is not ready to fully work with it. Ex: won't work with FXML properly, some controls can't be properly imported (useful things like labels and buttons...). This will probably be fixed in future versions, but I need it to work now :(
• Python from JavaFX -> Converting pyORACC to Jython so that it can be used from JavaFX would take a considerable time. All these steps are involved for each pyORACC class (see here):
  1. Build a java interface with the methods I want to use from the JavaFX code
  2. Make pyORACC classes look more like java beans (add setter and getters, etc)
  3. Since the pyORACC's classes work as they are, don't touch them and build decorators for them to accomplish 2.
  4. Make those python decorators implement the correspondent java interface and inherit from the original python class.
  5. Make an object factory for each class in the java code.
• Python GUI frameworks -> It'd be nice to have a software tool built in a single language, wouldn't it? Need to research some more on these options.
• Just JavaFX -> This involves translating pyoracc to Java. Not worth it when we already have pyORACC working properly. Making a big effort on changing the Python core of the software just to be able to present it on a nice small GUI doesn't seem right.
• GWT -> nice because it works as a website and as a standalone. Also claims to be mobile friendly, but not tested yet. However it's focused on web development and after a few tests, I've seen things don't work so smoothly when trying to build a standalone tool. Note that we are aiming in the first place for a standalone tool (web version is just a nice-to-have), so option discarded.

Next steps: Have a look at the Python GUI frameworks again, and if they don't seem OK, just use Jython + Swing.

Manipulate ATF locally - model view mode

• Open ATF in model view
• Edit
• Save