Merge pull request #46 from veraPDF/update_documentation

REL 1.24 - Update documentation

cli/config/index.md

@@ -6,8 +6,7 @@ title: veraPDF CLI Configuration
 Introduction
 ------------
 
-Below the veraPDF installation directory there is a sub-directory called
-`config`. This contains the XML configuration files for the veraPDF software
+There is a sub-directory called `config` below the veraPDF installation directory or in folder `verapdf` in the user directory. It contains the XML configuration files for the veraPDF software
 components. To see the contents of this directory from a terminal session
 in the installation root directory type <kbd>ls config/</kbd> on Mac or Linux
 machines or <kbd>dir config</kbd> on Windows machines. On my Windows test VM
@@ -35,35 +34,7 @@ installation. The software generates default configuration files on start-up if
 none exist. Try running <kbd>verapdf --version</kbd> which should generate the
 missing files.
 
-### Running veraPDF without installation gives no configuration files
-All of the above assumes that you've installed veraPDF with the downloaded
-installer. If you're running a version of the application you've built
-yourself and not installed you won't have an application home directory. The
-following only applies if you're running a jar directly from the command line,
-that is something like : <kbd>java -jar target/{{ site.verapdf_version_number }}.jar</kbd>, from the [`veraPDF-apps/gui` module](https://github.com/veraPDF/veraPDF-apps/tree/integration/gui).
-The problem is that the installer adds a couple of invocation scripts that set
-up the application home directory. The solution is to choose a config directory
-and pass it to the application when you call it. Here's an example:
-
-1. Select a folder you want to use as home and create it, a good suggestion is `~/.verapdf` beneath your home directory, in my case `/home/cfw/.verapdf`.
-2. Execute the following command: <kbd>java -Dapp.home="/home/cfw/.verapdf" -jar gui-{{ site.verapdf_version_number }}-SNAPSHOT.jar --version</kbd>
-3. <kbd>ls ~/.verapdf/config</kbd>
-
-and you should see
-
-```bash
--rw-rw-r-- 1 cfw cfw 375 Jan 28 20:36 app.xml
--rw-rw-r-- 1 cfw cfw 186 Jan 28 20:36 features.xml
--rw-rw-r-- 1 cfw cfw 109 Jan 28 20:36 fixer.xml
--rw-rw-r-- 1 cfw cfw   0 Jan 28 20:36 plugins.xml
--rw-rw-r-- 1 cfw cfw 131 Jan 28 20:36 validator.xml
-```
-
-Now proceed to use the config files in this directory, which will work as long as you use `java -Dapp.home="/home/cfw/.verapdf" -jar gui-{{ site.verapdf_version_number }}-SNAPSHOT.jar` as oppose to `java -jar gui-{{ site.verapdf_version_number }}.jar` when you start the app. This form of invocation supports all command line options, e.g.
-
-- <kbd>java -Dapp.home="/home/cfw/.verapdf" -jar gui-{{ site.verapdf_version_number }}-SNAPSHOT.jar -f 1b somefile.pdf</kbd>
-- <kbd>java -Dapp.home="/home/cfw/.verapdf" -jar gui-{{ site.verapdf_version_number }}-SNAPSHOT.jar --extract somefile.pdf</kbd>
-- <kbd>java -Dapp.home="/home/cfw/.verapdf" -jar gui-{{ site.verapdf_version_number }}-SNAPSHOT.jar --policyfile my-policy.sch somefile.pdf</kbd>
+If you are running a version of the application you have built yourself and not installed, config folder would be located in folder `verapdf` in the user directory.
 
 ### veraPDF config files
 There are four config files available:
@@ -104,7 +75,7 @@ The `appConfig` element has a set of attributes can be used as follows:
   - `RAW` : the raw XML data used by the veraPDF APIs, it's not quite as readable as the MRR format but can be de-serialised by the veraPDF API for further processing.
   - `HTML` : a formatted HTML report intended for human consumption.
   - `TEXT` : very brief single line text output.
-- `isVerbose` can be set to `false` for brief output which is the default, or `true` for verbose output.
+- `isVerbose` can be set to `false` for brief output which is the default, or `true` for verbose output in text report.
 
 #### <a name="fixerFolder"></a> fixerFolder
 The `fixerFolder` element sets a default folder where the repaired files generated by the metadata fixer are written.
@@ -122,7 +93,7 @@ The default validation config file contains:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<validatorConfig flavour="NO_FLAVOUR" recordPasses="false" maxFails="-1"/>
+<validatorConfig flavour="NO_FLAVOUR" defaultFlavour="PDFA_1_B" recordPasses="false" maxFails="-1" debug="false" showErrorMessages="true" isLogsEnabled="true" loggingLevel="WARNING" maxNumberOfDisplayedFailedChecks="100" showProgress="false"/>
 ```
 
 ### <a name="validatorConfig"></a> The validatorConfig element
@@ -131,6 +102,13 @@ The `validatorConfig` element defines the following attributes:
 - `flavour` the default flavour to use when none is specified by the user, can be PDF_A_1A, PDF_A_1B, PDF_A_2A, PDF_A_2B, PDF_A_2U, PDF_A_3A, PDF_A_3B, PDF_A_3U, PDF_A_4, PDF_A_4E, PDF_A_4F, PDF_UA1, or NO_FLAVOUR (for automatic detection).
 - `recordPasses` set `true` to report passed validation checks, `false` to report failures only.
 - `maxFails` specifies the maximum number of failed checks before validation is terminated, the default value of -1 means report all failures.
+- `maxNumberOfDisplayedFailedChecks` specifies how many failed tests are reported per validation rule.
+- `debug` set `true` to output all processed file names
+- `showErrorMessages` set `true` to add detailed error message for each check (xml, json, raw or html)
+- `isLogsEnabled` set `true` to add logs to report (xml, json or html)
+- `loggingLevel` determine the log level, can be "OFF", "SEVERE", "WARNING", "CONFIG", "ALL"
+- `showProgress` set `true` to show the current status of the validation job (only in cli)
+- `defaultFlavour` the default flavour to use when automatic detection did not work
 
 <a name="features.xml"></a>Configuring feature extraction
 ----------------------------------------------------

cli/fixing/index.md

@@ -3,7 +3,7 @@ layout: page
 title: veraPDF CLI Metadata Fixing
 ---
 
-veraPDF can optionally fix issues related to document metadata provided that there are no other PDF/A or PDF/UA issues detected. This includes:
+veraPDF (Greenfield version only) can optionally fix issues related to document metadata provided that there are no other PDF/A or PDF/UA issues detected. This includes:
 - adding document-level XMP metadata if it is missing
 - adding PDF/A or PDF/UA identification to the already existing XMP metadata, if there are no other PDF/A (or PDF/UA) issues detected and the document will become PDF/A (or PDF/UA) compliant after this fix
 - removing PDF/A or PDF/UA identification from the XMP metadata if it is present, but the document does not conform to the declared PDF/A (or PDF/UA) flavour

cli/validation/index.md

@@ -31,7 +31,7 @@ veraPDF supported PDF/A and PDF/UA profiles:
 You can specify a built in profile for validation using either the `-f` or
 `--flavour` options followed by the 2 character profile code.
 
-### <a name="choose-profile"></a>Choosing a PDF/A profile
+### <a name="choose-profile"></a>Choosing a profile
 To validate a single PDF/A file from the corpus using the PDF/A-1B profile type
 
 <kbd>verapdf -f 1b corpus/veraPDF-corpus-staging/PDF_A-1b/6.6\ Actions/6.6.1\ General/veraPDF\ test\ suite\ 6-6-1-t02-pass-a.pdf</kbd>
@@ -50,8 +50,8 @@ You should see something very similar to the following output:
       <job>
         <item size="10230">
           <name>/home/cfw/verapdf/dev/corpus/veraPDF-corpus-staging/PDF_A-1b/6.6 Actions/6.6.1 General/veraPDF test suite 6-6-1-t02-pass-a.pdf</name>
-          </item>
-          <validationReport profileName="PDF/A-1B validation profile" statement="PDF file is compliant with Validation Profile requirements." isCompliant="true">
+        </item>
+        <validationReport profileName="PDF/A-1B validation profile" statement="PDF file is compliant with Validation Profile requirements." isCompliant="true">
             <details passedRules="102" failedRules="0" passedChecks="504" failedChecks="0"></details>
         </validationReport>
         <duration start="1485134290404" finish="1485134290797">00:00:00:393</duration>
@@ -201,3 +201,17 @@ option. While convenient this is not always desirable. You can disable
 validation by passing the `-o` or `--off` option. This is usually done during
 [feature-extraction](../feature-extraction), for example
 <kbd>verapdf --off --extract somefile.pdf</kbd>.
+
+<a name="extension"></a>Non pdf extension
+------------------------------------------------
+You can validate pdf files with non-pdf extension by passing the `--nonpdfext` option. For example
+<kbd>verapdf somefile --nonpdfext</kbd>.
+
+<a name="encrypted-pdf"></a>Encrypted pdf
+------------------------------------------------
+By default, verapdf is trying to decrypt encrypted PDF file using empty user password. You can validate encrypted pdf  files with non-empty password by passing the `--password` option. 
+For example <kbd>verapdf --password "12345" encrypted.pdf</kbd>.
+
+<a name="wiki-path"></a>Profiles wiki
+------------------------------------------------
+HTML report contains reference links to veraPDF validation rule wiki https://github.com/veraPDF/veraPDF-validation-profiles/wiki/. You are unlikely going to change this unless you intend to host your own local version of the veraPDF validation rule wiki by using `--wikiPath` option.

develop/index.md

@@ -30,7 +30,7 @@ There are two implementations of the veraPDF software library, one that uses a
 fork of the [Apache PDFBox project](https://github.com/veraPDF/veraPDF-pdfbox)
 as a PDF parser and validation model. 
 
-#### Greenfield vs PDFbox
+#### Greenfield vs PDFBox
 
 Since releasing the PDFBox implementation
 the veraPDF consortium have developed their own "Greenfield" PDF parsing and validation model 
@@ -67,7 +67,7 @@ Both implementations above depend on javax. If your project uses jakarta, you sh
 ```xml
 <dependency>
   <groupId>org.verapdf</groupId>
-  <artifactId>validation-model-arlington</artifactId>
+  <artifactId>validation-model-jakarta</artifactId>
   <version>1.24.1</version>
 </dependency>
 ```
@@ -77,7 +77,7 @@ for Greenfield implementation and
 ```xml
 <dependency>
   <groupId>org.verapdf</groupId>
-  <artifactId>pdfbox-validation-model-arlington</artifactId>
+  <artifactId>pdfbox-validation-model-jakarta</artifactId>
   <version>1.24.1</version>
 </dependency>
 ```
@@ -149,7 +149,7 @@ PdfBoxFoundryProvider.initialise();
 
 ### Validating a PDF File
 You only need to initialise once, whichever version you're using, now the code to
-validated a file called `mydoc.pdf` against the PDF/A 1b specification is:
+validate a file called `mydoc.pdf` against the PDF/A 1b specification is:
 
 ```java
 PDFAFlavour flavour = PDFAFlavour.fromString("1b");

gui/index.md

@@ -14,7 +14,7 @@ This Quick Start Guide explains some basic concepts relevant to the veraPDF Conf
 The veraPDF GUI provides the features of veraPDF Java Library in a desktop windows GUI. Users can configure their own validation and policy checking jobs by selecting:
 - which combination of tasks to perform;
 - PDF Documents to analyse;
-- the PDF/A part and conformance level to test for; and
+- the PDF/A or PDF/UA part and conformance level to test for; and
 - various task specific settings.
 
 The software carries out the configured task and reports the results in both XML and HTML formats. The XML report is intended for consumption by automated processes while the HTML report is designed for human readability.
@@ -43,7 +43,7 @@ The options are as follows:
 
 | Option         | Description                                                                                               |
 |----------------|-----------------------------------------------------------------------------------------------------------|
-| Auto-detection | The veraPDF software will detect the PDF/A or PDF/UA flavour when parsing the file and use the appropriate profile. |
+| Auto-detect | The veraPDF software will detect the PDF/A or PDF/UA flavour when parsing the file and use the appropriate profile. |
 | PDF/A-1a       | Use the PDF/A-1a validation profile, i.e. assume that the file is a PDF/A-1a.                             |
 | PDF/A-1b       | Use the PDF/A-1b validation profile, i.e. assume that the file is a PDF/A-1b.                             |
 | PDF/A-2a       | Use the PDF/A-2a validation profile, i.e. assume that the file is a PDF/A-2a.                             |
@@ -76,7 +76,7 @@ The available options are:
 
 If Policy is selected the `Choose Policy` button is activated, the user can use this to load a [policy schematron file](/policy) or user can drag&drop policy file into `Policy file not chosen` area.
 
-The Fix Metadata checkbox determines whether the software will attempt to amend the PDF document metadata to ensure it is compliant with the PDF/A or PDF/UA specification.
+The Fix Metadata checkbox (enabled only in the Greenfield version) determines whether the software will attempt to amend the PDF document metadata to ensure it is compliant with the PDF/A or PDF/UA specification.
 
 ### Execute button
 This button is only enabled when a PDF file has been chosen. If you've chosen to use a custom validation profile from the dropdown then you must also select an external profile file. Once enabled and pressed the PDF file will be processed according to the selected options.

policy/info-dict/report.xml

@@ -117,4 +117,4 @@
 <repairReports failedJobs="0">4</repairReports>
 <duration start="1485516602855" finish="1485516603155">00:00:00:300</duration>
 </batchSummary>
-</report>
+</report>