Installing and Using the Command Line Checker
The Acrolinx Command Line Checker (CLC) is a Java-based client that you can call from a command-line shell or batch script. You can use the CLC to include Acrolinx checking in an automated document management workflow.
The CLC is delivered as a standalone package that is installed independently from the Acrolinx Server. Contact your Acrolinx project consultant to obtain a copy of the CLC package.
- Software Requirements
- Supported File Types
- Installing the Command Line Checker
- Directory Overview
- Configuring the Check Settings
- Checking with the Command Line Checker
- How the CLC Determines File Types
- Configuring Logging for the Command Line Checker
Before you install, make sure that you have the following software installed:
If you either don’t have an adequate Java version installed, or if that Java version isn’t used in your CLC startup script, then you might encounter an error similar to the following example upon when you start the CLC:
java.lang.UnsupportedClassVersionError: com/acrolinx/client/clc/CommandLineChecker (Unsupported major.minor version)
Acrolinx supports the following file types when working with the CLC:
Acrolinx only checks code comments in Java files.
|HTML||*.html, *.htm, *.xhtm, *.xhtml,|
The following formats are only supported in versions 3.4.7 or later of the Acrolinx Command Line Checker:
|Microsoft Word documents||*.docx|
|The following format is only supported with Acrolinx server version 5.1.1 or later and version 3.5.2 or later of the Acrolinx Command Line Checker:|
You'll receive the Acrolinx software files in a compressed zip file.
To install the Acrolinx Command Line Checker, follow these steps:
Extract the contents of the zip file to a location on your computer.
You can install the CLC anywhere where there’s a Java runtime environment installed.
If you’re running the CLC under Windows, configure the CLC to recognize where Java is installed on your computer.
- In the CLC installation directory, open the file clc. bat in a text editor.
In the file, set the variable that stores the location of your Java runtime environment by uncommenting the sample variable
and updating the path to your Java installation.
SET JAVA_HOME="C:\Program Files\Java\jre7"
Once you unpacked and installed the software, your CLC directory should contain the following files and directories:
|clc.bat||A script to run the CLC in Microsoft Windows.|
|clc.sh||A script to run the CLC in UNIX-based operating systems.|
|clc-<VERSION_NUMBER>.jar||The Java archive containing the CLC.|
|csd.profile.sample||Examples of how to configure a context segmentation definition (CSD).|
|log4j.xml||A logging configuration file that you can use to define how the CLC logs the steps the checking process.|
|mappingFileExtension.conf||Your extension mapping file. In this file, you can connect custom file extensions to the supported file types.|
|settings.conf.sample||Examples of how to configure the checking settings.|
||Mapping files for content.|
Before you start running checks with the CLC, you must define at least one check settings file. The check settings file stores all the standard check settings that the Acrolinx server requires to process a checking request, and several optional check settings.
To configure the check settings, follow these steps:
Create a copy of the sample configuration file that is located in your installation directory:
Rename the file to
and update the check settings.
To use different sets of check settings, you can create more check settings files with the extension "*.conf". For example, you can create the check setting files techdocs.conf , marketing.conf for checking different types of documents.
When you run a check, you enter the name of the check settings file that you want to use as the second argument.
If you’re unsure of what check settings are available for your server, you can run the CLC with the option -g . This generates a file that lists all possible check settings for a given server.
You can also use the following table as a guide on how to configure each setting:
Table 1. CLC Check Settings Setting Required? Default Value Description language Required No default Define the checking language.
For example, to define English as the checking language, update the setting as follows:
ruleset Required No default Define the rule set to check with.
For example, to define "Standard_US" as the rule set, update the setting as follows:
grammar Optional true Check for grammar issues. reuse Optional false Check for reuse issues. spelling Optional true Check for spelling issues. style Optional true Check for style issues. termsets Optional
Required if termstatuses is set.
No default Define the term sets to check with.
For example, to define "Routers" and "Switches" as the term sets, update the setting as follows:
termstatuses Recommended deprecated
Define the types of terms that you want to check.
For example, to check for deprecated and valid terms, update the setting as follows
termstatuses=deprecated,validPossible values are deprecated , valid , and admitted .
new_terms Optional false Generate a term harvesting report after each check.
- Save and close the file.
You run checks in the CLC by entering your Acrolinx Server address, check settings, input file locations, and user details. You can also perform other tasks such as generating a check settings file or displaying version information.
Before you run your first check you, ensure that you have defined a check settings file .
To run the CLC, follow these steps:
- Run the CLC from the command line or in your shell environment.
Navigate to the CLC installation directory and run the CLC with the following command syntax and parameter sequence:
clc.bat serverAddress checkSettingsFile inputFileLocations|stdin [-u <userName>] [-p <password>] [-i [text|application/xml]] [-m <extensionMappingFileName> [-s <resultslFileLocation>] [-r <resultUrlFileLocation>] [-a <aggregatedUrlFileLocation>] [-j <jsonUrlFileLocation>] [-f <userFileLocation>] [-e][-g][-v] [-h]
The following arguments are compulsory:
serverAddress checkSettingsFile inputFileLocations|stdin
To check standard input text that you enter directly into the command line (stdin), provide the arguments server Address and check Settings File then press Enter. Enter the text to check followed by an end-of-transmission character (EOT). To enter an EOT in Windows, press "Enter", "Ctrl-Z", then press "Enter" again. To enter an EOT in Unix, press "Ctrl-D" twice.The following examples show the basic commands for checking a single text file and XML file.
Tip: If you experience any memory-related problems while running checks, open the file clc. bat or clc. sh , uncomment the sample variable: set JAVA_OPTS , and save the file.The following table contains usage information for each CLC argument:
clc.bat acrolinx.topspin.com settings.conf C:\output\readme.txt
clc.bat acrolinx.topspin.com settings.conf C:\DITA\overview.xml -i application/xml
Table 2. CLC Parameters Parameter Required? Description server Address Required Enter the address of the Acrolinx server.The server address should be the first parameter in the command like the following example:
clc.bat acrolinx.topspin.comIf you’re connecting to a secure server you must enter the server address according to the following syntax:
clc.bat https://<SERVER_NAME>:8031For example, if your server name is acrolinx. topspin. com , you would enter the following URL as the server address:
check Settings File Required Enter a file name or path to the settings configuration file that contains your required check settings.Enter the checking options after the server address like the following example:
clc.bat acrolinx.topspin.com settings.conf
input File Locations Required Enter the location of one or more files to check.
You can enter a path to one file as in the following example:
clc.bat acrolinx.topspin.com settings.conf C:\pubs\overview.txt
You can also enter several paths to different input files or define a pattern for locating a set of input files. The patterns must be based on the syntax that is used in perform directory-based tasks in Apache Ant .For example, you could use the following pattern to check files in the "pubs" directory that are located underneath any subdirectory that has the name "output" and any files underneath the current directory that have the extension ".txt":
C:\tools\clc.bat acrolinx.topspin.com settings.conf C:\pubs\**\output\**\*.txt \**\*.txt
stdin Optional Enter the text that you want to check directly into the command line.For example, to check the text "This a test." in Windows, first enter the server address and the check settings file followed by any options and press Enter.
clc.bat acrolinx.topspin.com settings.conf -u admin -p qef9uPhEThe CLC connects to the server and pauses with the message:
[INFO ]  Waiting for user input from stdinEnter the text followed by an end-of-transmission character:
This is a test. ^Z
-u , --username <User_Name> Only on first check or if the server doesn’t support automatic user registration from clients. Connect to the Acrolinx server with the specified user name.
You must supply a user name when you run a check with the CLC for the first time.Define your user name by entering the -u argument followed by your user name. If your login details include a password, enter the argument -p followed by your password, like the following example.
clc.bat acrolinx.topspin.com settings.conf C:\pubs\overview.txt -u testuser -p qef9uPhE
If you don’t use this option, the CLC attempts to connect to the Acrolinx server with the name of the user account that is currently logged in to your computer.
After the CLC has connected to the server successfully, your user credentials are stored in a license store file so that you don’t have to provide your user details for subsequent checks.
-p , --password <Password> Only if you connect with a user name that requires a password. Connect to the Acrolinx server with the specified user password. -i , --input <FORMAT_NAME> No, but recommended if you want to manually specify the file type. Specify the input format of the file to be checked. If this option isn’t specified the CLC processes all files as plain text files.
Possible values are application/json, application/xml, docx, htm, html, java, json,pdf, properties, text, text/html, text/plain, txt, xhtm, xhtml, xml
If you use the value application/xml , ensure that you have server-side extraction enabled.
-m , --extensionMappingFile <FILE_NAME> Only if you plan to check XML file types with other extensions than .xml . Enter the file name of the extension mapping file.Enter the file name after the input format like the following example:
clc.bat acrolinx.topspin.com settings.conf example.txt -m mappingFileExtension.conf
Extension mapping is helpful if, for example, you want to check XML files with other file extensions. For example, to check XML-based .aml files, you would associate the file extension .aml with the XML format.
Or, to check a Java properties-based .string file, you would associate the file extension .string with the properties format.
Your installation includes the sample file mappingFileExtension.conf that you can adapt to your requirements.
If you specify an input format, the extension mapping is ignored.
Optional Store a summary of the checking result in a specified file.
The option -s should be followed by a path to a text file like in the following example:
clc.bat acrolinx.topspin.com settings.conf C:\pubs\taskA.txt -u testuser -p qef9uPhE -s C:\pubs\checkstatus.txt
The checking result is written to the first line of the file and contains comma-separated values like in the following example:
Optional Store the URLs to the Acrolinx Scorecards in a specified file.
If the file doesn’t already exist, it’s created during the check. Each URL is stored on a separate line in the file.
The option -r should be followed by a path to a text file like in the following example:
clc.bat acrolinx.topspin.com settings.conf C:\pubs\taskA.txt -u testuser -p qef9uPhE -r C:\pubs\reportURLs.txt
Optional Specify a license store file to read and store user licenses like in the following example.
clc.bat acrolinx.topspin.com settings.conf C:\pubs\taskA.txt -f C:\Oxygen\license.store
The CLC creates this file the first time you run a check so that you don’t have to enter your user details every time you run the CLC.
The file is called license.store and is created in the same directory as the CLC script.
Optional Specify the encoding for text files so that special characters are processed correctly.In the following example, the encoding for a text file is configured as UTF-16:
clc.bat acrolinx.topspin.com settings.conf C:\pubs\taskA.txt -e utf-16
Optional Generate a file that lists all possible check settings for a given server. You can use this file to help you create a check settings file. For example, you might be unsure of the rule sets that are available for a specific server. In this case, you can refer to the list of possible check settings that you created with this option.The following example command creates a list of possible check settings for the server "acrolinx.topspin.com":
clc.bat acrolinx.topspin.com -gThe file is created in the CLC installation directory and has the naming convention settings-<SERVER_ADDRESS>-<TIMESTAMP>.conf .
Optional Display version information about the current version of the CLC.
Optional Display help for each argument.
Generate an aggregated report file when you use the Acrolinx Command Line Checker to check files. An aggregated report contains a summary of the results of all the individual scorecards. By default, the aggregated report is saved on the server. You can define a file to save the report URL locally.
clc <servername> CheckSetting.conf <filename_list> -u <username> -p <password> -a <aggregatedUrlFileLocation>
Generate a check result in JSON format. By default, the JSON check result file is saved on the server. You can define a file to save the check result URL locally.
clc <servername> CheckSetting.conf <filename_list> -u <username> -p <password> -j <jsonUrlFileLocation>
To check and correctly process your content, the CLC must know which file type you're checking. There are several ways how the CLC can determine the file type: you can either specify it manually, or you can let the CLC automaticaly detect the file type. It is important that you understand the order in which the CLC tries to determine the file type.
- The -i option . First, the CLC looks for this parameter. If it’s used, the CLC treats the file according to the specified file type.
- The -m option . If the -i option isn’t used, the CLC looks for the -m option. If it’s used, the CLC tries to identify the file type according to the defined file types in the mapping file.
- The file extension . If no file types are specified, the CLC tries to determine the file type according to its file type extension.
- The file content . As a last measure to identify the checked file, the CLC analyses the content of the file. If a file type mapping exists, the CLC processes the file accordingly.
- Plain text . If the CLC can't identify the file type, it processes the file as plain text.
By default, all events in the checking process are logged in the CLC console. However, you might prefer to store the logging information in a file or require more detailed logging information. For this, you can update the logging configuration file to change the logging behavior.
To configure CLC logging, follow these steps:
Open the CLC logging configuration file in the following location:
Locate and edit the following line near the end of the file:
To save standard logging information to a file, change the value
like in the following example:
The next time you run a check, the log file is created at the following location:
To save detailed logging information to a file for debugging purposes, change the value
like in the following example:
The next time you run a check, the log file is created at the following location:
- To save standard logging information to a file, change the value console to standard like in the following example:
- Save and close the file, then run a check and confirm that a log file was created in the appropriate location.