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

Wed Sep 16 17:46:12 EDT 2020

Alan,

I will definitely take you up on this RIGHT NOW.

Attached is a MS-Word docx file which is my current working draft, but I've
removed all change tracking and deleted all comments.

If you are successful I'd need to re-edit back in the comments, as they are
placeholders for reviewers to find, or point out ongoing issues unresolved.

But I am very curious about this gitbook thing.

This MS-Word doc does have cross references in it, and hyperlinks to
outside web docs, also footnotes. My hope is that conversion doesn't lose
these, as they would be very tedious to recreate.

It is otherwise a big, but not terribly complex document. But MS-Word is
just not up to the job any more.

Mike Beckerle | OGF DFDL Workgroup Co-Chair | Owl Cyber Defense |
www.owlcyberdefense.com
Please note: Contributions to the DFDL Workgroup's email discussions are
subject to the OGF Intellectual Property Policy
<http://www.ogf.org/About/abt_policies.php>

On Tue, Sep 15, 2020 at 3:50 PM Sill, Alan <Alan.Sill at ttu.edu> wrote:

> 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>
> 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
>
> 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/20200916/b588a689/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: gwdrp-dfdl-v1.0.5-r28-no-changes-no-comments.docx
Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Size: 892349 bytes
Desc: not available
URL: <http://www.ogf.org/pipermail/dfdl-wg/attachments/20200916/b588a689/attachment-0001.docx>