Re: Git for Tech Pubs [was FW: L@@king for recommendations

Subject: Re: Git for Tech Pubs [was FW: L@@king for recommendations
From: Mark Giffin <mgiffin -at- earthlink -dot- net>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Thu, 22 Nov 2018 22:19:43 -0800

Chris Despopoulos mentions that he does not want to diff and merge of XML/DITA files in Git. I agree. You can make DITA XML work well with Git, but you should keep in mind a few things if you do it.

There is a conflict between XML (including DITA) and source control programs like Git. XML by default does not care about white space like carriage returns, tabs, spaces, it works at a level above plain text. You can change a few spaces and carriage returns in a DITA XML file and there will be no validation errors from a DITA or XML viewpoint. An XML editor like XMetal or Oxygen or FrameMaker won't care. But those white space changes are noticed by git, which is set up to notice ANY change to a source code file, which is what programmers want.

So you should make sure your XML editor (for all writers on the project) is configured to leave the white space alone in your DITA XML files, if you are using git or another source control program. It also helps to make the editor use some standard line length that everyone should use. Some XML editors by default will mess with the white space, and you need to turn it off. I've seen it happen where an author changed a word or two in a DITA file and went to commit it to git, did a git diff and the entire file was marked as changed because the XML editor had "pretty printed" the XML (formatted the white space in an orderly way so it's readable). If you used the git diff tool, it would be way too hard to figure out the actual changes.

Scott Prentice told me he has seen FrameMaker DITA XML work well with git. An example is some of the docs for his DITA-FMx FrameMaker plugin, edited in FrameMaker and stored on GitHub:

https://github.com/leximation/docs-ditafmx-2

Mark Giffin
Mark Giffin Consulting, Inc.
http://www.markgiffin.com/

On 22-Nov-18 2:36 AM, Chris Despopoulos wrote:

[...]
But merge and DIFF of XML files isn't something I really want to do anyway. These tools are designed for source code where even line breaks carry significance. XML as it's used in DITA does not carry the same line-based significance. Also, you probably don't want to use raw XML for your doc reviews... Who wants to read that?
But the bottom line for DITA and GIT is that it's great. Like others have said, it's not about locking files. It's about tracking versions and merging conflicts. We do our best to divide the labor so that two people don't work on the same file at the same time. But if a conflict does come up, it's not too hard to resolve. And FrameMaker has a negligible impact on the work flow, compared to other editors (including text editors).
But I would not recommend using MIF as a format for source control. MIF includes unique IDs for every document object, and those can change arbitrarily just by opening and saving a file. You would find yourself forced to track and manage commits to files that you thought you hadn't changed. And forget about resolving a merge conflict in MIF... Again, you could have conflicts for hundreds of lines of MIF that you never touched. And don't forget that a MIF file is really big -- It doesn't only represent the content and structure of a document, it represents all the formatting, including the underlying template, and lots of other headroom that FrameMaker uses to describe a document. Definitely, XML is the way to go if you want to store Maker files in GIT.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | https://techwhirl.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives

References:
Re: Git for Tech Pubs [was FW: L@@king for recommendations: From: Chris Despopoulos

Previous by Author: Re: Git for Tech Pubs [was FW: L@@king for recommendations for a doc source-file management system....]
Next by Author: Re: TECHWR-L Digest, Vol 157, Issue 14
Previous by Thread: Re: Git for Tech Pubs [was FW: L@@king for recommendations
Next by Thread: Re: TECHWR-L Digest, Vol 157, Issue 14


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads