Editing ATF with Nammu

Introducing Nammu, Oracc's new ATF editor

Nammu is Oracc's new, platform-independent editing software for creating transliterations, lemmatisations and translations of cuneiform texts. It is being written for us by Raquel Alegre and Jens Nielsen of UCL's Research Software Development Team.

• Download the current release of Nammu
• Follow these installation instructions

If you are an existing Oracc content-creator and have been editing ATF in Emacs, that's all you need to do. You'll find that Nammu is an intuitive replacement for Emacs, and that you can use all the Oracc keyboard shortcuts as usual.

New to ATF?

If you haven't edited ATF before, you may also want to download:

• our keyboard for cuneiform transliteration
• and/or one or more unicode transliteration fonts

You should also read the online help pages on learning and using Oracc ATF and on lemmatising.

Do contact any one of the Oracc Steering Group (Eleanor, Jamie, Niek, or Steve) if you would like to have your own Oracc project space (which can be public or private, as you like).

Tips and tricks

Nammu now has all its core funcationality – you can edit real texts with it unproblematically -- but it is still under development. If you like you can join the oracc/nammu group on Github to:

• watch for new releases
• see which aspects of Nammu are currently being worked on, and
• most helpfully for us, report bugs and issues.

Here are some ease-of-use features that we're currently working to enhance:

• At the moment there is no line-wrapping, so you have to scroll across for long lines.
• Nor is there any search/replace facility yet — also coming soon, we hope.
• There's no split screen option yet, either, so for the moment I suggest that you create translations in your usual word processor as you lemmatise, then paste them into Nammu for validation when you finish. It works for me!

For more details see here.

More about Nammu

Nammu has some built-in help but you can also:

• watch a video of me using Nammu to edit a tablet from Tell Khaiber
• watch the whole video, in which I introduce Oracc and Tell Khaiber
• read Raquel's slides about the programming and principles behind Nammu
• ask any one of the Oracc Steering Group (Eleanor, Jamie, Niek, or Steve) for further help!

Adding a Twitter feed to your ESP portal

for project managers

If you have a Twitter account, and your Oracc project has an ESP portal site, you can now add a Twitter timeline feed to it by following the instructions here.

You can see an example of it in use in the new Nimrud project portal (still tiny but growing fast).

In other Oracc news:

• The search functionality, which had been broken for a few days, is now up and running again.
• The GKAB portal pages have now moved closer to the CAMS/GKAB corpus; please update your bookmarks.

Knowledge and Power in the Neo-Assyrian Empire

Due to circumstances beyond our control, the original funders of the website Knowledge & Power in the Neo-Assyrian Empire no longer have access to the server on which it is hosted, which means that we cannot update it and many of the links (especially those to State Archives of Assyria online). We are currently trying to get it taken down with a redirect to the new site. Meanwhile, please update your links and bookmarks from http://knp.prs.heacademy.ac.uk/ to http://oracc.museum.upenn.edu/saao/knpp/

Installing EmacsW32 on Windows 7

The Emacs installation documentation at http://oracc.museum.upenn.edu/doc/builder/emacs/ now includes instructions for installing EmacsW32 on Windows 7 (shown in bold). Do let us know if there are any leftover problems with it.

Updated documentation

Over the past week or so I've had a jolly time checking that all the Oracc documentation is up-to-date and reflects current practice, and that all the links work. I won't list every tiny change here, but would like to draw your attention to a few points in particular:

All users: Citing Oracc URLs online and in print

Oracc 2 makes systematic use of stable URIs, so that you can be confident that print references and online links will remain valid. That means, though, that some details of the instructions on how to cite Oracc pages and resources have changed.

Mostly for editors and managers: Oracc language codes

If you have already read my overview of how the new lemmatiser works, you'll know that now you always need to specify Akkadian dialects (unless you are producing ATF for CDLI) and that glossary merges must now always specify the language. I've also worked those changes systematically through the documentation.

For editors and project managers: builder documentation

Editors and project managers will also notice that I have rearranged the list of builder documentation. It's still all there as before but now, I hope, in a more logical order.

For project managers: glossary management

I have incorporated the L2 updates into the sections on glossaries in the pages on project management with Unix and project management with Emacs (and written it into the rest of the documentation).

For project managers: The Oracc Command

This page has been reorganised and updated, so that it is easier to find help on the commands you most need for everyday project management work.

And you'll now find a Documentation full text search at the top of every documentation page.

If you notice anything wrong, broken, missing, or just plain confusing, please let me know, either in the comments or by email. The documentation is for you, the users and project creators, so please tell me if (and how) it isn't serving your needs.

ATF on Emacs

(For editors and project managers)

We still need to do a little work on updating Emacs ATF mode for Oracc 2. Until that happens, here is a list of what is and isn't working, and how to work around the latter.

ATF menu

Available when you have a .atf file open.

Check ATF

Lemmatise Buffer

Create Template

ATF Mode help

All working as usual.

Harvest Notices

Count Lemmata

Not working at the moment but neither is essential to the editing process.

Browse ATF docs

Links to a dead page. Go to the Builder Pages instead.

CBD menu

Corpus-based dictionary menu for project managers; vailable when you have a .glo file open.

Check CBD

Lemmer Update

Rebuild

Not working at the moment; you should manage glossaries through Unix instead

Project Maintenance Mode

CBD Mode help

Working as usual

Browse CBD docs

Links to a dead page. Go to the Manager Pages instead.

ORACC menu

For project managers; accessible from the Project Maintenance Mode item on the CBD menu.

Check Project

Merge Glossaries

Not working at the moment; you should manage projects through Unix instead—and note that the merge command now needs to specify the language

Harvest Glossary

Working as usual

Rebuild Project

Working but no longer recommended; use ncr or nor in Unix instead

Please do let me know if you have any problems or questions.

Adding Full Text Search to your Oracc 2 project portal

(FOR ORACC PROJECT MANAGERS)

One of Oracc 2's new functionalities is the Full Text Search across the whole of the site. There is a new documentation page about how to use it.

It is also very easy to enable users to do Full Text Search on your project alone, from one or more portal pages of your project. To do so you will need to edit them with Emacs or an XHTML editor.

• First add this line of code somewhere within the head element of the page, ideally with the other link elements:

  <link rel="stylesheet" type="/css/oraccbase.css"/>

  EDIT: This is now built into the main Oracc stylesheet.

• Then add this code wherever you want it to appear in the body of your web page, replacing [PROJECT] with the name of your project:

  <span class="find-button"><a href="/[PROJECT]/find">Full 
  Text Search</a></span>

  For instance, you might add a link to the online help:

  <p>Do a <span class="find-button"><a href="/cams/find">Full 
  Text Search</a></span> in CAMS 
  <a href="/doc/user/fulltextsearch/">[HELP]</a>.</p>

  EDITED TO ADD:

  If you are working with ESP, use <esp:link url="/[PROJECT]/find">...</esp:link> instead of <a href="/[PROJECT]/find">...</a>. The necessary CSS code is already built into ESP's stylesheet.

  This is displayed in the browser as:

  Do a Full Text Search in CAMS [HELP].

• Finally, don't forget to run oracc web to make it go live online.

Note that this does not replace the existing text, catalogue and glossary search functions, but allows users to search across the whole of your project, including portal pages. That does mean though that it is not very sensitive to the type of data it is searching, and returns rather rough and ready results. In particular, at the moment it privileges glossary entries but Steve is improving the way it returns results all the time.

As always, please let me know if you need assistance.

Analytics for Oracc 2 projects

(For Oracc project managers)

For Oracc 2, we have replaced Piwik as our user analytics software with Google Analytics (GA). There is just one Oracc account to which all project managers have access. You will still be able to see your own project's access data, but also all the other projects' and the whole of Oracc too, which we hope will be useful, for instance when writing grant applications and reports.

If you already have a Google account I have already registered you on Oracc's GA account. If you haven't (or I couldn't find it) I have already emailed you about this. If you think you should be on Oracc's GA account but can't get access and haven't had me email, then please contact me directly.

Go to Google Analytics and sign in with your Google account details to see the Oracc data, which is already being collected. You should find it quite intuitive to use but I know there's a huge amount of stuff in there.

So in particular, to find your own project's data, choose Standard Reporting from the orange bar at the top. Then in the left-hand menu go to Content, then Site Content, then Content Drilldown and look for your project abbreviation.

There's lots more to discover in GA. The inbuilt help (at the bottom of the left-hand menu) is very good and, as always, do ask me for assistance if you need it. (I've been using GA for Knowledge and Power for five years now, so know my way around quite well.)

Portal pages: preparing for Oracc 2

(For Oracc project managers)

If your Oracc project includes portal web pages that serve as introductory material to your corpus, you will need to ensure that they are valid XHTML 1.0 Strict before they can run on Oracc 2.

That sounds scary but it's not really. It just means that they are encoded so that all browsers can read and represent them correctly—and that Oracc 2's new full-text search can find and use them.

To find out more about how to check and convert your web pages, see the Oracc documentation on validating portal pages as XHTML Strict. If you use ESP to write your portal pages you don't need to do this, as ESP ensures XHTML Strict compliance as a matter of course.

As always, if you have questions or need help with any of this please just email me or a leave a comment here.

All projects are Oracc 2-ready

We have now finished migrating all projects to the new Oracc system (though they are not all visible online yet, and there is still general work to do on the online display and on Piwik).

If you are a project director and your liaison hasn't yet contacted you about what needs to happens next for your project, please feel free to email him or her, or leave me a message here.

New documentation

As the new-look Oracc comes onstream, you will find that it looks a little bit different, and that you can do a lot more with the texts than before. In particular, Steve has dramatically improved the search functionality. People making projects and corpora on Oracc will also, we hope, notice several significant improvements.

I have updated the online help pages for Oracc website users and for project creators. Please take the time to read the pages are most relevant to you, as they will help you get a great deal more out of Oracc. If you have any questions or problems, or can't find what you're looking for, please leave a comment here for me.

Links to help from the Oracc homepage will be reinstated shortly. What you see at the moment is just temporary, while the upgrade is in progress. Meanwhile they are here on the right.

For all Oracc website users

• Using the new-look Oracc 2 online corpora

You can also access this page from the Help button at the top of all Oracc corpus pages.

Note that this is a different URL to the old help pages, which I haven't yet taken down. So if you have bookmarked the old ones, please update your bookmarks. The main user help page has been updated though.

For Oracc project creators

• L2: how to use it

A one-page starting point for all editors and project managers, with links to all the relevant new documentation. You may not need all of this if you don't run a whole project single-handedly; just stop reading when it no longer seems relevant.

Not much has changed in fact, especially for text editing. You will find that lemmatisation is much improved; that you have much more control over individual languages, dialects and glossaries; and that projects rebuild much faster than they did before.

If your project has not yet been migrated it will be soon. We will email you when we are ready for your input. As the new system is much more rigorous than the old one, you will almost certainly have to spend some time error-checking and bug-fixing before you can continue routine work. Be prepared! Remember too that you will need to think of a new password.

New project passwords

If you are the manager of a project, please contact your liaison to obtain a new Oracc password. You will not be able to log into your Oracc project without it. There is no hurry to do this: please wait until you need to use your project account again.

Choosing a password

Your liaison will help you choose a strong password. It must be:

• at least eight characters long
• composed of a mix of upper and lower-case letters and/or digits and/or punctuation (i.e., at least 3 of these 4)

When you have agreed on a suitable password, your liaison will set it for you.

Logging in again

Even if you and your project editors normally access your Oracc project using Emacs or Aquamacs, the first time that each of you logs in after the password change you must use Terminal or PuTTy in order to initialise the secure connection. Instructions are on the Project Management through Emacs page.

In addition, depending on your computer's security systems, Terminal or PuTTy may tell you to delete your known_hosts file, and will tell you where to find it. To delete this file it is easiest to use Emacs: type ctrl-x ctrl-f and enter the filename (on Macs it is ~/.ssh/known_hosts). Simply delete the contents of the file, save and close it. Then go back to Terminal/PuTTy and try the log-in again.

If you have any problems or questions with the initial log-in, please contact your liaison.

Piwik

Piwik log-in isn't yet functional but will be soon. More to follow...

Documentation updates

We've added a few useful odds and ends to the Oracc documentation over the past few months, which I thought it would be useful to summarise here:

• How to report a new sign value to Niek when the ATF checker complains of an unknown value;
• How to search the Qcat (catalogue of compositions) and request new entries;
• A list of Akkadian roots;
• How to add linguistic annotations to project glossaries;
• Fuller information about discourse divisions;
• And several new options for the oracc command.

As always, just ask if you have any questions or problems - or any suggestions for correcting, improving or adding to the documentation.

NEW: portal site software

Would you like to build a portal website for your Oracc project along the lines of Knowledge and Power or Assyrian Empire Builders? Now you can!

Just this week we have finished testing and documenting ESP, an Oracc version of the electrostatic programme written by George McKerron for the Whipple Museum of the History of Science in Cambridge. In order to use it, you will need to know the basics of (X)HTML and how to use Emacs (but most of us use Emacs for Oracc text editing anyway).

Instructions for use are on the Oracc website. The range of options for Oracc portal sites (including but not only ESP) is here.

As always, if you would like any advice or help, just ask me.

CAMS is changing

Over the weekend, the structure of the Corpus of Ancient Mesopotamian Scholarship changed, in order to make way for new CAMS subprojects. This affects you if your non-CAMS project uses the CAMS glossaries as its lemmatisation base, and/or if you proxy texts from CAMS. In both cases, you will need to edit your 00lib/config.xml file.
1. To update your proxies, change <proxies>cams</proxies> to <proxies>cams/gkab</proxies>
2. To update your base glossary, change <option name="lem-system" value="cams"/> to <option name="lem-system" value="cams/gkab"/>
Have a look at the Oracc project configuration documentation for more information, and do ask for help if you need to.

Qcat overhauled

The Qcat—the catalogue of compositions—has now been radically rationalised, tidied up and documented. In particular, the naming conventions for the designations (the prose equivalents of the Q-numbers) have been standardised.

If your project uses the Qcat, you may find that you will need to revise your project's Q designations accordingly. If you use a Filemaker database or similar for your catalogue, I can send you a list of new designations to import, overwriting the old ones. Just email me.

If and when your project needs new Q-numbers, send me a list of your proposed designations and other relevant fields (as per the documentation); or ask me for a clone of the Filemaker Qcat database, to fill in and email back to me.

If you ever notice mistakes, duplicates or omissions in the Qcat, or have any questions about it, please email me about that too.

If your project page loses its styling ...

There is a problem with the redirection the Oracc server currently does that
I can't fix for the moment, but there is a straightforward solution.

The problem only affects projects whose pages contains relative links.
In such pages, you will see a different behaviour depending on whether you
ask for:

http://oracc.museum.upenn.edu/dcclt/

or

http://oracc.museum.upenn.edu/dcclt

The first version, with the trailing /, works correctly; the second fails to find
styling, images and any other relative links.

The solution is to specify the URL base explicitly in the home page (and
any other pages this problem affects). This is quite straightforward: just
add the <base> tag to the <head> part of the page; in the href
attribute, give the path with trailing slash. Here is what the header of
the DCCLT home page now looks like:

<head>
<base href="http://oracc.museum.upenn.edu/dcclt/"/>
<meta http-equiv="Content-Type" content=
"text/html; charset=us-ascii" />
<link rel="stylesheet" type="text/css" href="dcclt.css" />
<title>DCCLT - Digital Corpus of Cuneiform Lexical Texts</title>
</head>

I have already fixed this in several projects (HBTIN, SAA, DCCLT), but
I haven't checked all projects to see if they need the fix.

A note about configuration options

Looking over the posts on the blog and a few e-mails I realized that some comments about the configuration file might be helpful.

The configuration system is in flux and has grown rapidly and organically, particularly over the last nine months. Oracc software can access the configuration file, config.xml, via several interfaces, and some of the programs ignore options that don´t apply to them while others complain about misunderstood or illegal options.

In general, if you see an error message about a configuration option, just check that you haven´t mistyped an option or value name. Otherwise, leave suspicious options in the config.xml because some program or other may be secretly using them.

If you change 00lib/config.xml you need to use at least:

oracc config

To update the installed version. You may need to do:

oracc web

Or even:

oracc rebuild

Before you see the effects of your changes.

After the remaining to-do list items are dealt with, the configuration system will get a complete review. Some things that cannot be configured in config.xml will be added (like the buttons SAAo uses); others will be documented; others will be rationalized as there are a few places where multiple options do very similar things.

I am also hoping (expecting, even) to create a web interface with an easy form for managing config.xml that has the documentation built in to it and drop-downs with the valid option values etc.

So, this pain with config.xml is transient. I am expecting to have the new configuration system in place by the end of September.

Directory names have changed!

If you are struggling to do project management through emacs, it may be because you are still using the old (CDL) directory names. For instance:

• old sources/ is now 00atf/
• old lib/ is now 00lib/
• old cat/ is now 00cat/
• old websources/ is now 00web/
• old backups/ is now 00bak/
  

See Project Management through Emacs for step-by-step instructions and Project Files for a more systematic overview.

As always, do ask for help if you need it, but I may not be as speedily responsive as usual over the next few days (up to and including Wednesday), as I'll be doing tablet work in Berlin. I will have broadband access in the hotel though, so I'll be checking in at least twice a day.

Logging in into Oracc for the first time

If you're trying and failing to login to your Oracc project for the first time since the move, the problem might have one or more of the following causes:

1. All project passwords were reset to the default on the move. Try logging in with the default (if you don't know what I mean, please email me) and then change your password to something more secure, by typing passwd at the prompt and then following the instructions. Your new password should mix uppercase and lowercase letters, and use non-letter characters too.
2. If you are running Win32Emacs, you need to trash your old atf-mode files before you install the new ones: see here.
3. Before you can use Emacs for project work, you will need to initialise the secure connection by following the instructions here.

If these three solutions fail, email me. (Steve is away until August now.)