On Tue, Sep 3, 2013 at 8:45 AM, Steven Adler <> wrote:
> PDF is not editable. We have to publish in forms that can be edited, copied, derived, etc
That's correct. One of the three formats required for publication must be the
"editable" source, viz., the textual source that is used for authoring/editing, etc.
As to the three formats and use of non-OASIS-owned venues for VCS, etc:
I neglected to copy out the text to make it clear; see below:
https://www.oasis-open.org/policies-guidelines/tc-process#quality-fileFormats
(4) File Formats. Editable formats of all versions of TC
documents must be delivered to the TC's document repository.
Working Drafts may be in any format (i.e. produced by any
application). All approved versions of OASIS Deliverables
must be delivered to the TC's document repository in the
(1) editable source, (2) HTML or XHTML, and (3) PDF formats;
and the TC must explicitly designate one of those delivered
formats as the authoritative document. Any links referenced
by the TC shall be to the HTML, XHTML and/or PDF formats
stored using repositories and domain names owned by OASIS
and as approved by the TC Administrator.
It's best to check with Chet Ensign is you are planning to use
an off-site VCS repo or other resource for (pieces of) early
working draft content. The key requirement is that the TC's
work must be open to inspection and audit from anyone
(public read), and "editable" only by persons who are
TC Members, per TC Process:
2.8 TC Visibility
The official copies of all resources of the TC and its
associated Subcommittees, including web pages, documents,
email lists and any other records of discussions, must
be located only on facilities designated by OASIS. TCs
and SCs may not conduct official business or technical
discussions, store documents, or host web pages on
servers or systems not designated by OASIS. All web pages,
documents, ballot results and email archives of all TCs
and SCs shall be publicly visible.
- Robin
On Tue, Sep 3, 2013 at 8: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
--
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
