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.
Development of GUI was done within ISTC project #3361р. Participation in this project became possible due to support of Vladimir Litvinov (firstname.lastname@example.org), 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.
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:
@includedirective 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 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 2012Fixed minor bugs and added some enchancements:
Version 3.2, November 2012Release 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.
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.
xMarkup GUI contains from a main window, which has a set of functional tabs. Below is description of these tabs.
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:
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.
On this page the needed parameters of user's interface are set.
The page contains following elements:
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.
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:
Parameters, which define how to store the results of processing:
On this page the processing rules for source files are defined.
The page contains following elements:
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).
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:
On this page the data transformation procedures are defined. The description of used macro-language is provided in User's Guide.
The page contains following elements:
@include(to include content of external file) then you can open this file for editing by double mouse click on the line with directive.
On this page the version info, copyright and links to program docs and external Internet resources are provided.
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.
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).
This chapter describes how to debug procedures used for transformation rules.
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:
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.
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.
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:
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!
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.
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".
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 ОК.
|© Sergey Logichev,