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

[Mark Giffin <mgiffin -at- earthlink -dot- net>]

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: