Re: [xmile] version control for Spec documents
Great, I think that works fine.
WILL
On Tue, Sep 3, 2013 at 1:44 PM, Karim Chichakly <> wrote:
Hey everyone,
I just want to pipe in that Word documents are no longer binary, they are zipped XML (we should be using docx, not doc). I don't know about git, but TortoiseSVN does an awesome job with Word files. I use it a lot for this because I haven't seen anything else come close.
Bob also raises an excellent point in that we are breaking the document into different pieces that are worked on by at most a couple of people who should be able to avoid conflicts. If somehow there is a mixup and whatever we are using cannot handle it properly, you can still fix it manually using TortoiseSVN's Diff.
I think when each subgroup has a version they want the rest of the committee to look at, they put it in the OASIS documents folder to be reviewed. When we get to the point where we all think we have all pieces the way we want them, we can integrate them into one document. Better, we can use Word inserts until we get to the end as there are several rounds in the approval process.
Karim
On Tue, Sep 3, 2013 at 11:45 AM, Will Glass-Husain <> wrote:
I'm fine with this.
This does mean that we need one person to centrally collect all pieces of the document and integrate them. Does that mean that each piece should be saved to "Documents" in the oasis project and Karim will integrate?
WILL
On Tue, Sep 3, 2013 at 8:15 AM, Bobby Powers <> wrote:
Hi Bob,
Thanks for the reply. I think that makes sense - my concern mostly resided in how individuals collaborating on a piece were interacting. Leaving that to people working together on a piece simplifies things, but does require that the person holding the pen on the section do some additional work to synchronize between piece-collaborators and the rest of the TC.
Lets go with what you suggest, unless other people have objections or concerns.
yours,
Bobby
On Tue, Sep 3, 2013 at 10:30 AM, Bob Eberlein <> wrote:
Hi Bobby,
My belief, and perhaps others do not agree, is that we can subdivide
our final document into a relatively small number of pieces and
assign authorship control of those pieces to one or two individuals
at a time (essentially between meetings). Currently we have
identified 5 pieces, and that might grow to 10 or 12, but I don't
see it getting bigger than 20.
With that approach there is never any issue of merging content,
since the editors of each piece are clearly identified. If two
people are working together on a piece then they can use whatever
form they want to do so (track changes, google docs...). That
editing is not being presented to the committee as a whole and need
not be kept with the documentation records for the committee. When
they finish editing to the point of wanting to share, that document
then needs to be uploaded to oasis.
I think this approach is both simple and practical. Allowing more
people to change more things is necessary in code, but could be
problematic in writing a spec. It seems more sensible to communicate
how and why things need changing to the people holding the pen on
the section needing change. If they disagree, or have a different
idea, it could save a lot of rework and prevent unpleasant
surprises.
Bob Eberlein
On 9/3/2013 10:13 AM, Bobby Powers
wrote:
Sorry, I didn't fully finish my thoughts in that
last email. I am suggesting we worry about the major content of
the spec now by using something like markdown or google docs (a
lot of this content is currently contained in Karim's v4
documents, but as per our last call we have a number of areas we
would like to work on) that is easy to collaborate in, and once
we have the majority of the content written in a way we're happy
with, worry about moving it into a format suitable for
generating the required HTML & PDF outputs.
I explicitly worry that the overhead involved with managing
10 people's changes to a set of Word documents will discourage
collaboration and progress. With that said, if that is the
format most people are comfortable with I am happy to quiet
down and defer to the group on this subject - I just want to
effectively communicate my concerns before doing so.
yours,
Bobby
On Tue, Sep 3, 2013 at 10:00 AM, Bobby
Powers <>
wrote:
Hi Steve,
I think there has been a little confusion - my
understanding of Billy's email was that he was
suggesting making the final spec available in PDF - not
collaborating on the content in PDF form.
I think there are 2 separate issues here
1 - collaborating on the content of the spec
2 - formatting and providing the finished spec (and
potentially draft forms) in formats required by OASIS
I had originally suggested Markdown in my email to
Will because it is about as simple a format as possible,
and there are lots of tools to generate PDF, Word and
DocBook documents from Markdown source [1]. It would
let us individually edit files and then merge changes in
a straightforward manner, and is readable in a simple
text editor:
https://raw.github.com/bpowers/xmile-doc/master/2_container.md
Similarly, Google Docs allows multiple people to edit
the same document - since it is server-based, the base
document never diverges and explicit merges aren't
needed.
Merging Word documents is challenging and does not
integrate into version control tools like Subversion or
git - it would require additional work from us to avoid
having to do merges, or manually merge documents when
the need arises. It is manageable, but worth explicitly
mentioning
I hope this helps move us towards a shared
understanding of the discussion - please correct any
mistakes I have above :)
yours,
Bobby
1 - http://johnmacfarlane.net/pandoc/
for example
On Tue, Sep 3, 2013 at 9:45 AM, Steven
Adler <>
wrote:
PDF is not editable. We have
to publish
in forms that can be edited, copied, derived,
etc.
Best Regards,
Steve
From:
Bobby
Powers <>
To:
Robin
Cover <>
Cc:
Billy
Schoenberg <>,
Karim Chichakly <>,
Date:
09/03/2013
09:41 AM
Subject:
Re:
[xmile] version control for Spec
documents
Hi Robin,
Can you explain what you mean
by editable source? All
of the options we have been mentioning have
been editable-source formats
matched with potentially a version control
system (which is tangental to
the editable source requirement). The only
thing I can think of that
might conflict is Google Docs, where we
would have to export from Google
Docs to get the source (I think).
Did you see specific problems
with what we were discussing,
or were you just reminding us about the
OASIS requirements?
Thanks!
yours,
Bobby
On Tue, Sep 3, 2013 at 9:00 AM,
Robin Cover <>
wrote:
About GitHub, spec formats,
word processor files, etc...
I see that the TC members are
sorting out options for
version control in connection
with a partitioned spec
(assignment of parts for different
authors/editors).
You might want to consider the
use of DocBook (XML) based
upon the package
of XSLT scripts prepared by Ken
Holman for the publication
process. Or.. you
can roll your own. We (OASIS
Staff) encourage you
to use whatever tools
are best for your productivity,
but we try to promote
the use of tools that match
the vintage-1993 origins of the
organization = structured
information based upon
separation of concerns
(content/structure versus
display/presentation)
qua SGML/XML.
As to the formats, and "final"
publication formats,
I spotted this:
"... our
final
product should be distributed in PDF form as
opposed to Word..."
Reminder: OASIS requires
editable source as well as (X)HTML
and PDF:
https://www.oasis-open.org/policies-guidelines/tc-process#quality-fileFormats
Why? for many reasons, but we
allow derivative works,
and for use of
a reliable source as a basis
for a derivative work, the
editable source
is obviously the best. Trying
to create (secondary)
"editable" source from
PDF is not a good idea.
- Robin
On Tue, Sep 3, 2013 at 7:41 AM,
Billy Schoenberg <>
wrote:
Hey,
Merges are the main reason why
something like .doc files
are not great with something like github.
Because the format is binary
and git does textual merges obviously a
merge will never be successful.
I feel that our final product
should be distributed in
PDF form as opposed to Word because of the
wider availability and the high
availability of free viewers/editors.
With that said since we need to
use the OASIS template
we should see if the word template opens
nicely in google docs. If
so I think that would probably be the best
place for us to do our work
as it would handle for us the version
control fully (including merges)
and the styles/templates required by OASIS.
Best,
Billy
On Mon, Sep 2, 2013 at 4:11 PM,
Karim Chichakly <>
wrote:
Hi Will,
Thanks for your suggestions. I will echo
Bob's sentiments since:
a) Our final specification is
supposed to be in something
like Word (I also prefer Word over the other
choices), and
b) We should be starting this
effort from the OASIS Word
Template, to avoid reformatting later. I
will have to get hold of
that and pass around.
Karim
On Mon, Sep 2, 2013 at 2:50 PM,
Bob Eberlein <>
wrote:
Hi Will,
My preference on this would be able to work
in Word. Splitting the document
up into the appropriate pieces will take a
bit of work, but that structure
won't change often. I also think it would
be useful to hand the pen
off on the different pieces pretty
explicitly outside the context of the
version control system (basically during our
meetings).
Is there any reason not to use github for
managing .doc files? Or phrased
another way is there any reason not to use
.doc files on github?
Bob Eberlein
On 9/1/2013 9:46 PM, Will
Glass-Husain wrote:
Hi,
Hope everyone (in the US) is
enjoying their Labor
Day weekend.
In the last committee meeting,
we split up the document
writing into various sections.
I'd like to propose we use
version control while writing
the spec documents. This helps
collaboration by seeing changes added
over time by various members of the group
and make it easier to provide
comments.
I suggest one of the following two options.
The simplest (for most people)
is to use Google Docs.
You can edit the document using a Microsoft
Word like approach (WYSIWYG).
The document lives on line, formatted.
Each time it is changed
and saved a version is stored. This allows
us to review the changes to
the doc over time. Final version of the doc
may be downloaded as
MS Word and if necessary additional
formatting applied. A benefit
of this approach would be ease of use for
those familiar with Microsoft
Word and other word processors. A negative
is that everything needs
to be edited online.
A second approach would be to
use plain text documents
formatted with Markdown, and to use Github
as version control. The
more technical members of the committee may
prefer this. Bobby powers
(see appendix to my email) has assembled
several examples of how this would
work. This would be a good approach if
everyone writing was comfortable
with git and version control. Github has
something called a "pull
request" which makes it easy to comment on
specific parts of a document.
The final document could be converted to PDF
or HTML.
Once we choose an approach, I
can set everything up, with
Google Docs or Github. We should probably
choose one approach for
the entire document.
Any comments?
WILL
---------- Forwarded message
----------
From: Bobby Powers <>
Date: Thu, Aug 29, 2013 at 6:38 PM
Subject: markdown example
To:
Here is the repo:
https://github.com/bpowers/xmile-doc
Here is a page with some of the
things we want (code blocks
of XML, inline tags, and lists):
https://github.com/bpowers/xmile-doc/blob/master/2_container.md
And here is the source for that
page:
https://raw.github.com/bpowers/xmile-doc/master/2_container.md
This is a pull request which
can be used to manage changes:
https://github.com/bpowers/xmile-doc/pull/1
And here is the markdown
syntax:
http://daringfireball.net/projects/markdown/syntax
I didn't do a GDoc example - I
think that is more self
explanatory (Word on a web page).
yours,
Bobby
--
Robin Cover
OASIS, Director of Information Services
Editor, Cover Pages and XML Daily Newslink
Email:
Staff bio: http://www.oasis-open.org/people/staff/robin-cover
Cover Pages: http://xml.coverpages.org/
Newsletter: http://xml.coverpages.org/newsletterArchive.html
Tel: +1
972-296-1783
--
Forio Online Simulations
Will Glass-Husain
415 440-7500x89
www.forio.com
--
Forio Online Simulations
Will Glass-Husain
415 440-7500x89
www.forio.com