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
