Syntax of JCM Labels/Doc files (March 2004)

************
GENERAL

All files are in UTF-8 character format

Before making any translations, please email ben@chooseclimate.org to check whether I have added/rearranged items since this package was created. Otherwise we can get in a real muddle.

Please read the "Labels and Documentation" pages within JCM documentation for more explanation about how the system works.

For translating small labels, I find it more convenient to edit the big table of all languages (jcmlabdoctab.txt) in a spreadsheet (note - it's like csv, but tab-separated). To convert this back to separate files, you need to run the "main" method of labinf as a standalone java application (for java experts only). But if you send me the edited version of jcmlabdoctab.txt I will convert it.

The syntax below may be replaced by an XML/HTML markup system. This would be easier to view in a web-browser and edit with web-composing tools, but less convenient for editing as plain text. Please tell me your preference. 

************
ITEM-CODES

Each new entry starts with a hash # followed by its item-code. Don't change this!

*Each item-code should end with a space. Spaces, tab, newline etc. between items are trimmed
*The order of items within a file doesn't matter (they are sorted automatically)
*Unrecognised item-codes are ignored (can use #! for comments)
*If an requested item in the appropriate language is not found, the default (english) label will be used (untranslated documentation is shown in grey).
*If a requested item is not found in the default language files (regardless of whether it's in translated files), the item-code itself is used for the model/doc.  
*It's not essential to translate every item - some refer to obscure "expert" or "experimental" parameters. Better to start with objects that are visible on startup, or seem important to you.
*(Tip: to see how the item codes correspond to objects on the model interface, choose script/label codes from the language menu)

Each item code may be followed by:
   info : used for sorting files, maybe later for menus and printing documentation (don't translate this)

************
SHORT/POPUP/DOC forms

Each item code is then followed by:

In the lab_XX files: 
 `  short label : normally displayed on graphical interface, also used for documentation links/titles
 ~ popup/menu label : pop-up info on mouse-over, or for inclusion in menus
Both ` and  ~  forms should be translated, if present in the original.

In the  doc_category_XX files:
 documentation : which can include html tags, subsections and hyperlinks (see parsing rules below)

The doc is combined with titles and links which use the `short  and  ~popup forms, but these are stored separately for efficient loading (upon demand, depending on topic and language).  

************
PARSING

Within documentation, the parsing method (see autodoc.java) makes the following conversions:
(include these in translation but don't change the codes!)

`item_code / ~item_code / item_code : replace by   shortlabel / popupinfo / documentation  for specified item
item_code 	: replace by title followed by doc for specified item (for subsections), also add link at top of page
^info_request 	: replace by info about current item, generated by the model (see iob.java, param.java, jcmpanle.java graph.java)
!script_name 	: replace by start/stop/code buttons, to run a JCM script file jcm/script/script_name.txt
@item_code 		: replace by hyperlink to specified item (whose shortlabel will be used as link text)
..xyz.. 		: replace by <small> ..xyz.. </small>   (small italic for notes)
..xyz..	 	: replace by <hr><h3> ..xyz.. </h3> (for subsection titles)
image_name 	: replace by icon with specified name (.png file)

Note: item-code / image_name / info_request /script_name must be followed by space or recognised punctuation


