Modified: 31.01.2009
	Russian Virtual Library

xMarkup GUI User's Guide

Content

• 1. Introduction
• 1.1 Credits
• 1.2 History of changes
• 2. Getting started?
• 3. Description of user interface
• 4. Tabs of main window tabs
• 4.1 Source files
• 4.2 Preferences
• 4.3 Output
• 4.4 Markup rules
• 4.5 Markup options
• 4.6 Macros
• 4.7 Help
• 5. Usage of external text editor
• 6. Usage of external diff tool
• 7. Debugging of procedural macros
• 7.1 Test compilation
• 7.2 Test run
• 7.3 Debug processing

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 Win32 application for Windows 9x/NT/2K/XP/2003 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. GUI is developed in Delphi 7 and incorporated many useful features.

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, MyDevStudio 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:

• mode when all output is redirected to console window;
• step by step execution in debug mode;
• double mouse click on the line with @include directive open included file for edit.

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 be named by adding "xm$" prefix to the name of source files. On the tab "Help" added link to download page of xmarkup.

2. Getting started

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

• Compose list of source files to process (with help of search by mask, manual adding or loading from early prepared file);
• Define or load processing script;
• Define working directory in which all temporary and working files will be located (by default the location of a script);
• Define output mode, which describe how to create output files;
• Define additional options of processing;
• Start processing and analyze its results.

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.



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.

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:


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).



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.



The page contains following elements:

1. field [Working Folder] fo define folder, which will be used as default location of working files to be opened for read/write during processing (please don't mess it with output folder where the results are created!);
2. button [...] to choose or create required working folder;
3. button [Explore] to open working folder in Windows Explorer;
4. list-box [Interface Language] to define language of GUI (at the moment Russian and English only);
5. 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);
6. field [External Diff Tool] to define path to a program, which can display differences between files (by default WinMerge);
7. check-box to define auto-saving of script before start of processing (provided that it was changed);
8. check-box to define auto-sorting of source list when new files are added to it;
9. check-box to define auto-saving of configuration when you quit from program (afterwards this configuration may be loaded);
10. buttons to define style (font and background) of working windows;
11. buttons to define style (font and background) of console windows;
12. field [Configuration] to define path to configuartion file. Right button [...] opens dialog to choose required configuration file;
13. button [Save] to save configuration to defined file.

Files, which are explicitly opened from macro-procedures during processing for read/write shall be located in defined working folder. For example,

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

If you specife full paths to these files they may be located anywhere, of course. This also true for macro-definition @read(file).

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

4.3 Output

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



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 [Debug Mode], which defines processing of source files in debug mode (see Debug processing);
6. check-box [Quiet Mode], which defines supressing of working messages while processing;
7. 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:
- 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.
2. text field [Output Path] to define path to root output folder;
3. button [...] to choose or create required output folder;
4. button [Explore] to open output folder in Windows Explorer.

4.4 Markup rules

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



The page contains following elements:

1. field [Parameter 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. 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;
8. 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);
9. 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);
10. table, which define lists of start and stop marks and transformation templates;
11. field to define template of post-transformation (common for all transformations).

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).

4.5 Markup 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.



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);
5. window [TagExceptions] with a list of names of paired HTML tags, content of which shall be skipped while procressing.

4.6 Macros

On this page the procedural macros are defined.



The page contains following elements:

1. Window to edit source code of macro-procedures;
2. Bottom console window to view debug output while validating of macro-procedures (hight of this window may be adjusted by user);
3. Button [Test Compile] to perform validation of syntax of defined macro-procedures by Icon compiler;
4. Button [Test Run] to perform validation of macro-procedures by simulation of Run-time execution.
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 copyright and links to program documentation are provided.



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,



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:

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 procedural macros

This chapter describes how to debug macro-procedures defined in processing rules.

7.1 Test compilation

With help of this mode the rough syntax errors in macro-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 [Macros]. Below the example of output listing of compiler is provided:



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 Test 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]:



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:



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:

• 1 - resumes processing in debug mode;
• 2 - resumes processing in normal mode without debug;
• 3 - stops processing.
To quit from debug mode and stop processing in any moment you can press the button [Stop] or input Ctrl-C.

© Sergey Logichev, 1999-2008