[DFDL-WG] MS Word Limitations for DFDL Spec Review

[Sill, Alan]

I have gotten a lot better at use of GitBook and can now import Word documents more or less seamlessly, with only a small amount of formatting fix-up needed. Changes can be tracked as GitBook comments by simple markup within the text once uploaded, managed by branching and merging within GitBook, or when synchronized with the OGF GitHub, you can manage them with bidirectional syncing through GitHub pull requests and associated discussion tools.

I’m willing to take on uploading the current (or other good baseline) DFDL document (s) and make them available for your evaluation and analysis if you provide me with a clean, non-marked-up copy of any document or documents.

I think this is the future of OGF document production and that moving to tools like this will both allow us to modernize our infrastructure and leave the path forward to any future migration with minimal difficulties.

Thanks,
Alan

On Sep 15, 2020, at 12:26 PM, Mike Beckerle <mbeckerle.dfdl at gmail.com<mailto:mbeckerle.dfdl at gmail.com>> wrote:

Two topics:

* change tracking
* hyperlinks

So...

Change Tracking:

I have reached the limits of MS-Word with change tracking in this roughly 250 page DFDL spec document.

I believe at this point I am going to have to give up on change tracking, I.e., providing drafts with accumulated changes since a prior major version marked with change bars.
I have found that a PDF export from MS Word with tracked changes even with only "simple markup" is quite illegible, with heading numbers appearing not on the same line even as their heading, etc.  I believe this is an interaction of renumbering of sections and change tracking. Either way, MS Word crashes often and I am worried about losing work or corrupting the document. I found already that in revision r22, a cross-reference to the section about recoverable errors was not putting in a cross reference to that section, but rather was repeating the entire contents of the section at each point of cross reference. I had to hand delete all of these as I encountered them when going through the reviewer comments page by page.

I think at this point we're forced to greatly reduce use of MS-Word change tracking, and if a reader wants to study the changes between two revisions, they have to fire up MS-Word, and use it to compare two working draft versions of the document.

So the version I am going to push up for consideration soon (which is probably r27 or r28) will have change tracking, and also I will create a version with all changes accepted. Further changes will happen in the one with all (current) changes accepted, creating a new, smaller set of changes, not an accumulated set of all changes since the prior official draft. In addition, for various large changes like section moves, I plan to accept them, and just add a comment bubble to remind reviewers to read the section, as having the whole change visible with strikethrough of the deleted and colored/underlined text for the insertions ruins the flow of the document.

The only reliable viewer for the document, which can show the tracked changes in "simple markup" so that you see change bars on sides of pages only, is MS Word itself. Creating a PDF with "simple markup" doesn't work right.

Hyperlinks:

I have determined that MS-Word cross references are simply NOT converted into navigable hyperlinks when the document is output as an HTML document. This appears to be simply a MS-Word limitation. The same limitation exists in OpenOffice. A PDF gets navigable hyperlinks, but not an HTML output.
Furthermore, I have determined that an MS-Word Index results in a printable index, but again there are no navigable links from the index to the referenced pages/locations.

Based on this I am going to abandon, for now, creating a easily/readily used HTML version of the spec., and stick with just PDF.


Mike Beckerle | OGF DFDL Workgroup Co-Chair | Owl Cyber Defense | www.owlcyberdefense.com<https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.owlcyberdefense.com%2F&data=02%7C01%7Calan.sill%40ttu.edu%7Cdd68dcfaf7c34740a57108d8599c87f5%7C178a51bf8b2049ffb65556245d5c173c%7C0%7C1%7C637357876118107787&sdata=YUJcXUbE9uoFsHl3qzTLVoUqSsxY8FiMfSbEQclceV8%3D&reserved=0>
Please note: Contributions to the DFDL Workgroup's email discussions are subject to the OGF Intellectual Property Policy<https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.ogf.org%2FAbout%2Fabt_policies.php&data=02%7C01%7Calan.sill%40ttu.edu%7Cdd68dcfaf7c34740a57108d8599c87f5%7C178a51bf8b2049ffb65556245d5c173c%7C0%7C1%7C637357876118107787&sdata=2Fz4rszMO%2F4DzlUAcdIf21cuLgEuuE%2FaDGYZNsmI2g0%3D&reserved=0>

--
 dfdl-wg mailing list
 dfdl-wg at ogf.org<mailto:dfdl-wg at ogf.org>
 https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.ogf.org%2Fmailman%2Flistinfo%2Fdfdl-wg&data=02%7C01%7Calan.sill%40ttu.edu%7Cdd68dcfaf7c34740a57108d8599c87f5%7C178a51bf8b2049ffb65556245d5c173c%7C0%7C1%7C637357876118137764&sdata=99C%2FIK%2FSlyHe8UneoEHxVTDyh8bKf32bIdgZQzPH82I%3D&reserved=0

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.ogf.org/pipermail/dfdl-wg/attachments/20200915/e09d5569/attachment-0001.html>