RVB logo Modified: 2012.26.11
Russian Virtual Library

xMarkup GUI User's Guide

Content

1. Introduction

xMarkup is a program to perform text transformations in a set of text files (see xMarkup User's Guide). Engine of xMarkup is emplemented as console MS Windows 32bit application and written in Icon programming language. As command line mode is not very convenient way to work so afterwards the Graphical User's Interface was developed. Initially GUI was developed in Delphi 7. The fall of 2012 GUI was ported to open-source development environment Lazarus. Due this GUI have got the support of UTF-8 and convenient localization mechanism. Moreover, the possibility to develop cross-platform GUI for Windows, Linux and Mac OS appeared.

Integration with external text editor Notepad++ provides user with powerful and convenient development environment (IDE). Script of processing rules is edited with source code highlighting and using of auto-completion. Any other editor instead of Notepad++ may be used if needed. For example, jEdit or WinPad XP.

GUI is integrated with external program WinMerge, which may be used to analyze differences between source and output text files, which processed by xMarkup. Any other diff tool instead of WinMerge may be used if needed. For example, KDiff3.

GUI has options to validate defined procedural macros. This provides user with much easy and fast development of macro procedures.

Screen output of xMarkup may be copied to output file.

All preferences and parameters of user's session my be saved to file to be loaded then to repeat the processing of source data.

1.1 Credits

Development of GUI was done within ISTC project #3361р. Participation in this project became possible due to support of Vladimir Litvinov (litvinov@snezhinsk.ru), who is a technical editor of Russian Virtual Library.

GUI uses free Delphi-component TmFileScan, which was developed by Mats Asplund, MASoft. With help of this nice package the search of source files is implemented.

1.2 History of changes

Version 2.0, April 2007

Initial version of GUI released. It's numbered 2.0 in accordance with version of console engine.

Version 2.0.1, July 2007

Fixed an error when file of parameters is being rewritten each time as processing is started (autosave mode) even it was not changed.

Version 2.1.0, October 2007

Added possibility to change font and color settings for work windows.

Version 2.1.1, April 2008

Added new functionality from console engine:

Version 2.1.2, May 2008

Fixed bugs in console engine.

Version 2.1.3, September 2008

Simple alphabetical sort of source files' list changed to hierarchical sort of file paths. In the top of the list added a panel, click on which changes sorting order.

Version 2.1.4, January 2009

Fixed output mode in which output files shall beck for update named by adding "xm$" prefix to the name of source files. On the tab "Help" added link to download page of xmarkup.

Version 2.1.5, April 2010

Fixed some small bugs of GUI. Added automatic check for update on startup (see tab "Options"). Also added link to check for update on tab "Help".

Version 2.1.6, August 2010

Version 2.1.7, January 2011

Version 2.1.8, December 2011

Version 3.0, May 2012

Fixed minor bugs and added some enchancements:

Version 3.2, November 2012

Release of version 3.1 was initially planned on October but postponed due to many changes. As a result greatly revised version 3.2 was released.

2. Getting started

To process some source files with help of xMarkup GUI you shall make the following steps:

User may don't worry about original source files - the utily NEVER changes them! Output files are copied to defined output folder or created together with source files but with prefix "xm$" in a name. By default output files are not created at all.

3. Description of user interface

xMarkup GUI contains from a main window, which has a set of functional tabs. Below is description of these tabs.

4. Tabs of a main window

4.1 Source files

This page is opened first when program starts. On this page a list of source files to be processed is composed.

page Source Files

The page contains followng elements:

  1. list-box to define search mask for files, which shall be added to source list;
  2. check-box to define recursive search of files in nested sub-folders;
  3. window with list of source files to process;
  4. panel in the top of list to change sorting order;
  5. bottom console window, in which the screen output of utility is displayed (height of this window may be adjusted by user);
  6. button [Search] to search files by defined mask;
  7. button [Add Files] for manual adding of files to source list;
  8. button [Remove] to remove selected files from source list (don't worry, files are not removed from your disk);
  9. button [Open] to open selected file;
  10. button [Edit] to load selected file to external text editor;
  11. button [Load] to load a list of files from early saved file;
  12. button [Save] for storing of source list to a file;
  13. button [Clear All] to clear source list;
  14. button [Start] to start processing of source files.
  15. check-box [Debug mode] which defines processing in debug mode (see Debug processing).

Adding of files to source list can be done incrementally many times. By default source list is ordered each time when new files are added to it. When you add files with help of search this operation may be interrupted in any moment by pressing Esc button or Ctrl-C.

Navigation through source list and selection its items are performed as usual in Windows - by means of mouse or keyboard. Double click on selected file or pressing of Enter makes it to be open. Pressing of Del removes selected file(s) from source list. Pressing of right mouse button activates context pop-up menu:

Context Menu

Menu items "Compare", "Open Result", "Edit Result" are enabled only when output file was created during processing of source file.

While processing in status line the progress-bar is indicated, which shows elapsed time and percent of completed job. Console output of utility is displayed in bottom window (you may change modes of this output on the tab Results).

xMarkup Processing

Execution of processing may be interrupted in any moment by pressing of [Stop] button or Ctrl-C.

4.2 Preferences

On this page the needed parameters of user's interface are set.

page Preferences

The page contains following elements:

  1. list-box [Interface Language] to define language of GUI (at the moment Russian and English only);
  2. field [External Text Editor] to define path to external text editor (by default Notepad++ or, if it's not installed on your system, then Windows Notepad);
  3. field [External Diff Tool] to define path to a program, which can display differences between files (by default WinMerge);
  4. check-box to define auto-sorting of source list when new files are added to it;
  5. check-box to define auto-saving of configuration when you quit from program (afterwards this configuration may be loaded);
  6. buttons to define style (font and background) of working windows;
  7. buttons to define style (font and background) of console windows;
  8. field [Configuration] to define path to configuartion file. Right button [...] opens dialog to choose required configuration file;
  9. button [Save] to save configuration to defined file.

Files, which are opened from macro-procedures during processing for read/write, for example:

procedure initialize
  in := open("infile.txt", "r")
  out := open("outfile.txt", "w")
  ...
  t := get_content("infile.txt")
end

by default are read/created by path of location of current markup rules' file. That is directory which locates file of markup rules always defines working directory. You may use relational paths which shall be specified relative to the working directory, Surely, you may use full paths - in this case files can be located anywhere. Mentioned above shall be applied also to macro-definition @read(file).

Please note that the results of processing are always created in defined output folder (see the next chapter).

Now file of markup rules is automatically saved (if it was previously changed) on processing start, debug compiling, debug run or building .exe file. So this feature is fixed and can not be changed!

The auto-check of update on site sourceforge.net is automatically performed when program starts in asynchronous mode.

4.3 Output

On this page the options of console output and creation mode for output results are set.

page Output

The page contains following elements.

    Options of console (screen) output:

  1. check-box [Save to file], which defines copying of screen output to a text file;
  2. text field to define name of the file (if path isn't specified then the file is created in defined working folder);
  3. button [...] to choose or create required file of screen output;
  4. button [Edit] to load file of screen output to external editor;
  5. check-box [Don't show processing statistics], which defines supressing of working messages while processing;
  6. field [Size of Screen Buffer] to define size of screen buffer in lines (screen buffer is cleared when number of output lines exceed this size).

    Parameters, which define how to store the results of processing:

  1. group box of radio-buttons to choose creation mode for output results:
  2. - create output files in directory structure the same as source files have;
    - create output files in a single flat folder;
    - create output files together with source files but with prefix xm$ in a name;
    - redirect all output to console screen (no output files are created);
    - do not create output files.
  3. text field [Output Path] to define path to root output folder;
  4. button [...] to choose or create required output folder;
  5. button [Explore] to open output folder in Windows Explorer.

4.4 Transformation rules

On this page the processing rules for source files are defined.

page Markup Rules

The page contains following elements:

  1. field [Script File] to define path to a script with processing rules;
  2. button [...] to load script, which was early stored;
  3. button [Edit] to open script of processing rules in external text editor;
  4. button [Save] to save script of processing rules to a file;
  5. button [Save As] to save script of processing rules to file with other name;
  6. button [Create] to create new script of processing rules;
  7. list-box [Text encoding] to define encoding of processing data: ANSI or UTF-8;
  8. window [Header] which contains comments or description of a script (these lines begins with character # or semicolon). Hight of header window may be adjusted by user;
  9. check-box to synchronize lists of start and stop marks (it means that each start mark corresponds to exactly one stop mark with the same position; else each stop mark are alternative);
  10. check-box to synchronize lists of start marks and transformation templates (it means that each start mark corresponds to exactly one transformation template with the same position; else only first transformation is choosen);
  11. table, which define lists of start and stop marks and transformation templates;
  12. field to define template of post-transformation (common for all transformations).

To add new line to the end of table you shall press Ctrl+Ins. To delete selected line you shall press Ctrl+Del.

As editing of lists in table form may be unconvenient (e.g. when you need to insert or delete rows) it's recommended to use external text editor for that (see chapter 5).

When UTF-8 text encoding selected then the script file is stored as UTF-8. In this case to get correct results all processing data must be in UTF-8. For ANSI mode the script file is stored in 1-byte encoding defined for your system locale (Windows-1251 for Russian or Windows-1252 for West Europe).

4.5 Options

On this page some additional options of processing are set. To get detailed description of these options please refer to xMarkup User's Guide.

page Markup Options

The page contains following elements.

    Parameters of internal counters:

  1. field [Initial Values] to define list of initial values of counters (size of this list defines number of used counters);
  2. field [Increments] to define increments of counters;
  3. check-box [Use AutoIncrement] to define auto-incrementation of counters after each call of macro @counter();
  4. list-box to define type of counters (relative or absolute).

    Additional options:

  1. check-box [Add newline...] to define adding of newline character (\n) to the end of each source line (by default);
  2. check-box [Case ignore search] to define case-insensitive search of start/stop marks;
  3. check-box [Skip HTML tags] to define skipping while processing the body of any HTML tag;
  4. field, which defines minimum length of searched text elements (that is a string between start and stop marks).

4.6 Procedures

On this page the data transformation procedures are defined. The description of used macro-language is provided in User's Guide.

page Macros

The page contains following elements:

  1. Window to edit source code of procedures;
  2. Bottom console window to view debug output while validating of procedures (hight of this window may be adjusted by user);
  3. Button [Test Compile] to perform validation of syntax of defined procedures by Icon compiler;
  4. Button [Test Run] to perform validation of procedures by simulation of Run-time execution.
  5. Button [Build .exe] to build loaded transformation rules to binary .exe file.
  6. Button [Remove .exe] to remove existing binary .exe file of transformation rules.
Note: if you use directive @include (to include content of external file) then you can open this file for editing by double mouse click on the line with directive.

4.7 Help

On this page the version info, copyright and links to program docs and external Internet resources are provided.

page Macros

5. Usage of external text editor

xMarkup GUI supports integration with any external text editor, which may be used for convenient viewing or editing of processed files or script with processing rules. If editor Notepad++ is installed on your system then it will be used by default. You may define other editor on tab page Preferences.

Notepad++ provides automatical highlighting of syntax of script with processing rules (file types .par or .xm). For example,

page Notepad++

Pressing of Ctrl+Space activates operation of text auto-completion, with help of which you may choose required name of macro-definition or built-in function.

When script is modified and saved in the external editor and then user returns to xMarkup the dialog window is opened with proposal to reload the script:

page Reload Please answer "Yes" if you want to synchronuze changes.

6. Usage of external diff tool

xMarkup GUI supports integration with external program to check differences between files (diff tool), with help of which you can visually analyze differences between source and output files. If program WinMerge is installed on your system then it will be used by default. You may define other diff tool on tab page Preferences. Only one requirement for diff tool exists - startup command for this programm shall be in format:

<program-name> file-1 file-2

To find differences between source and target files after completion of processing you shall choose required source file (on page Source Files) and click by rigt mouse on it. Then choose "Compare" in opened pop-up menu. Comparing is possible only when output files are created (see page Results).

7. Debugging of procedures

This chapter describes how to debug procedures used for transformation rules.

7.1 Debug compilation

With help of this mode the rough syntax errors in procedures are debugged. It done by compilation of source code of processing rules by Icon compiler. However, it shall be taken into account that Icon compiler checks code only by syntax (in Icon it may be very strange or exotic!). So some invalid constructions may be treated as valid and produce an error only during Real-time execution. For example, Icon doesn't check existance of called functions or procedures on compilation phase.

Test compilation is performed by pressing of button [Test Compile] on the page [Procedures]. Below the example of output listing of compiler is provided:

page Test Compile

In this case in source line #6 the rigth closing bracket is missed:
t := tower(@body
and following "if-then" statement in the line #7 was not recognized.

7.2 Debug run

With help of this mode the each statement of macro-code is checked during simulation of Run-time execution. This mode is useful for smooth debugging of source code. For example, to check usage of defined variables and functions. Test run is performed by pressing of button [Test Run] on the page [Macros]:

page Test Run

In this case source line
t := tower(@body)
produces Icon Run-time error 106 due to name "tower" is not recognized as name of defined procedure (right name is "lower"). Description of all possible Run-Time errors may be found in Appendix G (page 319) of book Icon Programming Language.

7.2 Debug processing

With help of this mode you can watch processing of source files step-by-step. To activate this mode you shall choose option [Debug Mode] on the page [Results] and then start processing:

page Debug Processing

After each processing step (that is search and transformation of the next text element) xMarkup suspends execution and waits user's input. You shall input in console window the number of answer (1-3) and then press Enter:

To quit from debug mode and stop processing in any moment you can press the button [Stop] or input Ctrl-C.

8. Build .exe file

Usually script of transformation rules, which contains procedures, is executed by console engine (xm.exe) in interpretation mode. Naturally it slows down the processing in great degree. Feature of building the markup rules into binary .exe file is introdiced in version 2.1.6 of xMarkup. If such file exists all processing is done by this binary. This may greatly speed up the processing - in 10 or more times!

page Build .exe

Binary .exe file of transformation rules is created in bin folder of xMarkup's installation (by default c:\Program Files\xmwin\bin). Name of the binary is the same as filename of markup rules (e.g. list_tags.par.exe for rules list_tags.par). When any file of markup rules is loaded utility checks if corresponding .exe file exists. If such binary exists then the window of macro-procedures is blocked to exclude any changes of these procedures. The button [Edit] to edit markup rules in external editor is also blocked in this case. To make any changes in macro-procedures you shall at first delete existing binary (button "Remove .exe").

If markup rules contains no procedural macros then creation of binary is not needed at all and button "Build .exe" is blocked.

8.1 For users of Windows Vista/7/8

In the newest Windows versions, starting with Windows Vista, the mechanism of User Access Control (UAC) was introduced. In this case even if you are the only user of computer and have all Administrator's rights the OS restricts some unsafe operations for you by default. It means that even system administrator is seen as usual user from system's point of view. For example, you can't modify files in folders of Program Files and Windows home. If you have appropriate rights you should imlicitly request for rights escalation to perform restricted operation. Practically that implemented as pop-up dialog window which propose to run the operation as Administrator (if you have such rights). However applications you run is executed by default without rights escalation, so any unsafe operations are blocked. For example, if you try to modify or create file in folder Program Files with help of Notepad you will fail. To avoid such situations the installation location of xMarkup at Windows Vista/7/8 shall be choosed not within folders \Program Files or \Windows. Else operations "Build *.exe" or "Debug Compile" will never work successfully. Also the program will fail to store its configuration file.

Below is shown how to workaround UAC restrictions but it's usually not recommended.

If you are the system administrator you can run any application with rights escalation. To do this you should right click shortcut of your application on Desktop and choose "Run as administrator".

page Run as administrator

You may fix property to run your application as administrator. To do this you should right click shortcut of your application and choose item "Properties". Then in opened window press "Advanced" and set check-box "Run as administrator". To fix changes press ОК.

page Run as administrator

© Sergey Logichev, 1999-2012
RVB