00:00:07The purpose of this video is to demonstrate
how to generate various reports that show
00:00:11the results of a file comparison using
scripts in a command line window.
00:00:16I start with my command line navigated to the
scripts folder within the Oxygen installation
00:00:21directory ... and I'll paste a command I
have prepared to simply compare two files.
00:00:29You can see that the comparison
report was generated in the console
00:00:33and by default, it's in YAML format.
The report shows information such as the
00:00:38total number of differences found, the
number of differents for each category,
00:00:43and a list of document offsets that
identify the fragments with differences.
00:00:49As you can see, the report is not very easy to
interpret in this format, but you can generate
00:00:54the report in other formats such as JSON, XML, or you can generate the report in HTML format with
00:01:00the modified text displayed side-by-side.
Note that I can use the -help option to show the
00:01:06script's specifications, including information about the supported options and arguments.
00:01:12For example, if I want to change the
output format for my comparison report,
00:01:17I can use the -out option to specify the
output format and the -outfile option to
00:01:22specify the path for an output file where
the comparison results will be saved.
00:01:29So, I'll show some examples using the -out option,
00:01:32and for this first one, I'll specify JSON as the
format. And, you can see that it generated the
00:01:38comparison results in the command line window and in a JSON file format.
00:01:46Next, an example using HTML for the format.
00:01:50And, you can see that the resulting report is formatted in HTML structure.
00:01:57Back in the help documentation, there's
a recommendation that if you choose the
00:02:01HTML output format (as I did), it is recommended
that you choose to save the console to a
00:02:07specified HTML file to view the comparison result in your preferred browser...
00:02:13and this is where the -outfile option
is helpful. So, I'll add it to the end
00:02:18of my previous command, specifying a
path and name for an output file.
00:02:24Now, I can locate that specified
file and open it in my browser.
00:02:29It results in a user-friendly HTML report with
the differences presented and highlighted based
00:02:35on the types of differences. I'll
quickly go over parts of the report
00:02:39so you understand what you're seeing.
There is a legend at the top that shows the
00:02:43number of differences and includes
some filtering checkboxes.
00:02:48I can hover over a checkbox to see a tooltip
with more information about the filter, and
00:02:52if I select a particular filter, the
results are filtered accordingly.
00:02:57The columns in the middle separate the
two files and also include symbols that
00:03:01represent the type of difference.
Now, I'll talk about some of the
00:03:05specific differences. Notice that the
2nd block of difference seems to just
00:03:10be a comment added by John and doesn't affect the actual document content.
00:03:16Within the 3rd block of differences, there seems
to be some empty lines that were added by Mary,
00:03:22but again, they didn't affect the actual content.
00:03:25and the 4th block of differences seems
to just be reporting a difference
00:03:28in the order of an attribute.
I also want to point out that I can
00:03:34refine the report by using filtering
options in the script itself.
00:03:39For example, back in the help
documentation, you can see that
00:03:43there are various supported options for
ignoring certain types of differences.
00:03:48I'll paste a command that includes
some ignore options ... specifically,
00:03:53to ignore differences in whitespaces,
comments, and the order of attributes.
00:03:59Again, I can open the resulting output file in
my browser and now there are 3 less entries in
00:04:05the results table, since I chose to ignore
those specific types of differences.
00:04:11It's also possible to generate a
comparison report for a 3-way comparison.
00:04:15In this case, I need to specify the
paths of the 2 files to be compared,
00:04:20immediately followed by the path
to the base reference file.
00:04:25I'll open the resulting report ...
notice that it's a bit different.
00:04:30For example, the filters are a little
different since the context is different
00:04:35than with the 2-way comparison. For a 3-way
comparison, the report is structured according
00:04:38to the context of what you would
expect for a versioning system.
00:04:43Back in the help documentation, notice that
when using the HTML format for the -out option,
00:04:49it supports an inlineCSS qualifier that results
in the HTML report being formatted with inline
00:04:56CSS styling that is, for instance, more suitable for inserting it into the body of emails.
00:05:04So, I'll paste an example of a command
with the inline CSS qualifier...
00:05:10And when I view the resulting
HTML report in the browser,
00:05:14the CSS styling is now "in-line",
the filters are hidden and the
00:05:18middle columns that normally include
the diff symbols are now hidden.
00:05:24Just for context, you could see the
results of the "behind the scenes"
00:05:29implementation by viewing the source of
the reports. I can right-click anywhere in the
00:05:31reports and then select "View page source" and you can see how each report is constructed.
00:05:38For 3-way comparisons, you also have the ability
to merge the modifications that are detected,
00:05:43as long as there are no conflicting changes.
This is achieved by using the -merge or -mergeout
00:05:49options. The -merge option results in the incoming
differences being merged into the 1st file
00:05:55(again, unless there are conflicts, in
which case, the merge is aborted).
00:06:01However, if you don't want to directly affect
the content of the first file, you can use the
00:06:06-mergeout option to instead create a new file
that includes the results of the merge operation
00:06:11and it is saved in a specified directory.
Now, I'll paste a command that oompares the file
00:06:17that just resulted from the mergeout option with the 2nd file involved in the comparison.
00:06:23I'll open the resulting file in my browser. And
if I compare it to the first results file, you can
00:06:27see that there are no more incoming changes.As you can see, there are a lot of different
00:06:36options that you have available to refine
the HTML reports to suit your specific needs.
00:06:42This concludes the demonstration.
Thank you for watching.