* Steve Cogorno <Steven.Cogorno at Sun.COM> [2006-01-18 10:11]: > Ben Rockwood wrote: > > I vote for an SCM, which means it would be implemented with the code SCM > > whenever that happens. I'm not sure what you use to write your docs > > Brendan, but mine are done in LaTeX and DocBook making an SCM the prime > > way to go about it. I manage all my docs and the docs for Enlightenment > > this way. If you then want automation to a public locale, assuming you > > don't just link to a web viable SCM interface (CVS-Web or Subversion) > > you can dump the doc into the final location. > > I'd strongly caution against using an SCM-type system for the XML files. > This would work OK if the files were always edited using a standard > text editor, but it will not work if any sort of GUI XML editor is used > because the line breaks will change each time the file is saved. This > won't allow proper diffs and hence merging will be almost impossible. > > Also, the method by which the documents will be exported from the Sun > content repositories will not guarantee any sort of consistency of line > breaks. From release to release of the base Sun documentation, the line > breaks will be completely different.
One possibility is, prior to integration, to pass documents through a consistent formatting filter, much like indent(1) for C. Constructing a filter that had a reasonable set of defaults to minimize line break drift doesn't seem profoundly difficult. That is to say, assuming the toolchain to be unchangeable might be unnecessarily constraining. - Stephen -- Stephen Hahn, PhD Solaris Kernel Development, Sun Microsystems stephen.hahn at sun.com http://blogs.sun.com/sch/
