RE: about specifications format

[Jacques Durand <JDurand@us.fujitsu.com>]

All:
Following on Chet's mail about which format to author in:
We have these 2 options:
Option (1): "conservative": keep source in XML (wsi-specific schema), then generate HTML and PDF
Option (2): "mainstream": convert source to word processor XYZ (e.g. MSWord, OpenOffice), generate HTML and PDF.
Possibly Option (3) could be considered: "standard XML":  an alternative would be to convert first to such a well known XML format as Docbook. Then use standard OASIS conversions from there.
plus and minuses:
------------------- If we author in XML:
+ we already have the XML source and a dedicated stylesheet to convert to HTML. We just need to get a good HTML-to-PDF conversion.
- On the minus side: our XML is not a well-known format like Docbook, and that means we can't reuse whatever standard OASIS stylesheet exists - meaning we'd have to tweak our own stylesheet to add OASIS front page, conf clause section etc.
- any future editing - if any - may require from editor the ability to understand and tweak the wsi stylesheet, unless the edits are minor.
- the test assertions are blended with the profile doc. Show-up nicely as pop-ups in HTML, but would not show up in an PDF automatic conversion I guess.
------------------- If we author in a more conventional word processor:
+ on the plus side: we reuse a well-know format that many understand and can edit, and for which OASIS templates exist. Seems to be less trouble on the way forward. Easier to find editors!
- minus side: need to port the current XML source to the more conventional processor format (MSWord, OpenOffice...). We are talking of RSP=35 pages, BP12=60 pages, BP20=60 pages. But just selecting the HTML content of these and importing it say in MSWord already gives a good starting point for editing: all that remains to do is the reformatting of imported content (sections / titles / styles).
- minus side: we loose the nice integration with Test Assertions (these were part of the "profile" and showed up in pop-up windows in HTML). Either we detach the TAs from the profile doc (become another doc), or we keep them in Appendix. In both cases, we need to keep these same TAs in XML format in a separate XML file as this is input to the test tool (currently the XML of the profile doc is used directly for such input).
--------------------- my take on this:
- I have a preference for the "mainstream" approach (2) - doing away with the wsi proprietary XML format and its complex stylesheet, convert in a WYSIWYG editor and source. This is a "dumber" approach, need a couple of hour of dumb manual reformatting for each profile doc, but less trouble on the way forward. Option (3) comes as a close next.
Now I may be missing some aspects of this, might downplay some difficulties or some benefits. So let us see what others think.
Thanks,
Jacques

-----Original Message-----
From: ws-brsp@lists.oasis-open.org [mailto:ws-brsp@lists.oasis-open.org] On Behalf Of Chet Ensign
Sent: Wednesday, October 17, 2012 6:23 AM
To: Gershon Janssen
Cc: ws-brsp@lists.oasis-open.org
Subject: Re: [ws-brsp] MINUTES OASIS WS-BRSP TC Meeting 27 September 2012

Hi Gershon & all -

I saw the discussion about document formats below. Here are a couple of quick comments.

- If you want to author in XML and generate HTML and PDF, let's talk.
I can work with you to match the formats we use for output. AMQP does this, as does Docbook, DITA, UBL and I believe some others.

- The UBL TC, compliments of Ken Holman has a package of style sheets already set up that can do this, so you could work in Docbook and have the publication package all set.

- If you want to convert HTML into Word or Open Office and author/edit in those, please be sure to request templates from TC Admin using https://www.oasis-open.org/resources/tc-admin-requests/work-product-registration-template-request
. That will ensure that you have the right cover page contents and styles and such and avoid delays when you are ready to go to public review.

Let me know if you have any questions on these...

/chet

On Wed, Oct 17, 2012 at 7:59 AM, Gershon Janssen <gershon@qroot.com> wrote:
> ----------------------------------------
> DRAFT MINUTES
> OASIS WS-BRSP TC Meeting
> 27 September 2012, 12:00pm
> ----------------------------------------
>
> * Member status changes after 27 September 2012 meeting:
>
> Lost voting rights:
> None.
>
> Gained voting rights:
> None.
>
> Now: 9 voting members in TC.
>
> * New Action Items:
>
> Action Item: Jamie Clark: Confirm what has been discussed by message
> to the list Action Item: Micah Hainline: look at how much we can do to
> fix the bug and as part of that investigate the SVN repo access
>
> Scribe: Gershon Janssen
>
> 0. Call to Order and roll call
>
> Jacques Durand calls the meeting to order and welcomes everyone.
>
> * Roll call:
> Jacques Durand
> Gershon Janssen
> Doug Davis
> Alessio Soldano
> Micah Hainline
> Ram Jeyaraman
> Jamie Clark
>
> 6 voting members present; this meeting quorates.
>
> * Changes to the proposed agenda:
> Extend meeting with 15 minutes.
> Some members need to leave after 1 hour.
>
> Agenda approved.
>
>
> 1. Administrative
>
> * Minutes previous meeting
> https://www.oasis-open.org/apps/org/workgroup/ws-brsp/email/archives/2
> 01209/
> msg00008.html
> Minutes approved by unanimous consent.
>
> * WS-I MS affiliation update
> WS-I MS StC was cancelled, so decision deferred to October StC meeting.
>
> * Extend some meetings
> Extend meeting to 90 minutes due to the infrequent meetings and workload?
> Back-up meeting time is 1 hour earlier than the regular time.
> All agree that 1 hrs earlier + 90 minutes would work.
>
>
> 2. Logistics / Process about Maintenance of profiles, tools
>
> * JIRA for WS-BRSP
> JIRA has been setup, see message for details:
> https://www.oasis-open.org/apps/org/workgroup/ws-brsp/email/archives/2
> 01209/
> msg00010.html
>
> * Comment list and its use.
> Comment list has been setup.
>
> * General process to handle users requests/comments
>
> - Process is all feedback should come through the comments list and
> bug reports should go JIRA
> - Suggestion to systematically report all comments that qualify for
> subsequent action into a JIRA issue
> - Best for someone to monitor this process, which involves: look at
> comments list --> qualifies for an issue? --> create a JIRA issue
> - Gershon will start monitoring this as secretary of this TC
>
> - Next steps are: based on issue posted, person to be assigned to
> issue in order to work on a solution
> - Assignee can work on resolution; post comments; reassign, etc. This
> is to make sure issues don't stay unassigned.
> - Final decisions on issues to be taken at TC meetings.
>
> - TC agrees to start handling feedback and issues by the following process:
>
> Process for handling feedbacks:
> 1. Users must report comments / issues on the BRSP comment list.
> 2. The "comments monitor" (TC member, currently Gershon) files a JIRA
> issue for every comment that looks like it needs TC action.
> 3. Assignment of the issue for further investigation: either TC
> members pick-up the issue on their own, or chair finds an assignee.
> 4. The assignee makes a recommendation to TC, that could informally be
> communicated to the user as just in-progress (not formally
> TC-approved) 5. The TC makes a formal decision about this
> recommendation at next meeting
> - either a resolution, or just a direction to take to make progress on it.
>
>
> * Inventory: Current set of tools: nature,  suites, availability:  (1)
> old profiles tools (for BP1.1 and derived,  BSP1.1): monitors +
> analyzers (C#, Java), (2) new profiles tools  (for BP1.2/2.0 and
> RSP1.0): logger + analyzers (python, XSLT).
>
> - 2 sets:
>  (1) old profiles tools (for BP1.1 and derived, BSP1.1): monitors +
> analyzers (C#, Java)
>  (2) new profiles tools (for BP1.2/2.0 and RSP1.0): logger + analyzers
> (python, XSLT)
>
> - SVN repo -- See
> https://tools.oasis-open.org/version-control/browse/wsvn/ws-brsp/
>
> Action Item: Micah Hainline: look at how much we can do to fix the bug
> and as part of that investigate the SVN repo access
>
> - Micah: our section of the SVN repo is empty
> - Dug: we need to upload our src
>
> * The current bug report (Gerwins BP10 bug)
>
> MOTION:
>
> Motion to approve the proposed resolution (BRSP mailing list,
> https://lists.oasis-open.org/archives/ws-brsp/201209/msg00016.html) to
> Gerwin issue report, and communicate it as TC-BRSP decision to Gerwin,
> with the condition that Gerwin posts prior to this his report in our
> comment list.
>
> Jacques moves; Micah seconds. Motion carries.
>
>
> 3. Distribution and management of source code (long term)
>
> * Role of OASIS
> * Licensing aspects (Micah), OSS solutions
>
> Jamie Clark shares and clarifies what has been discussed by email offline.
>
> - Question: Past users of WS-I profiles claim conformance and use of logo?
> Jamie: logo did come with the work, so we can continue the use of
> logo, though, check with WS-I Member Section StC.
>
> Action Item: Jamie Clark: Confirm what has been discussed by message
> to the list
>
> Next step is to go to the WS-I Member Section StC, which in turn will
> make a recommendation to the Board.
>
>
> 4.Other lines of work
>
> * Profile Specifications Moving current Profiles toward OASIS CS or further.
> Formatting & source doc considerations.
> - BP1.2 BP2.0 and RSP1.0; specs are complete, maybe should be updated
> a bit
> - formatting aspect; source is XML.
> - by oasis rules: source format, PDF and xHTML
> - we have a source format (XML); from XML to HTML and from HTML to PDF
> should be possible
> - problem is how to render the front page.
> - so there is an issue how to convert current format to a format
> editors are more familiar with, e.g. MS WORD.
> - Two options:
> - solution1: XML=source, generate HTML (using ws-i XSLT converter),
> generate PDF (from HTML)
> - solution 2: port the spec (probably from its HTML format) into a
> conventional word processor (MS word, OO..) and work from there.
> - Gershon has a preference for generating, though front page issue.
> Need to investigate.
> - Comments and ideas are welcome ; to be shared on the list.
>
> * Still clarify our work priorities (testing? Profiles/tools maintenance?
> Progress latest profiles as OASIS specifications/standards?) Who is
> interested in what line of work.
>
> Deferred to next meeting.
>
>
> 5.  Adjourn
>
> Next meetings:
> - 18/Oct @ 3p
> - 15/Nov @ 3p or 2p (tentative)
>
>
> ---------------------------
> RAW CHAT TRANSCRIPT
> ---------------------------
> [11:55] Gershon Janssen: WS-BRSP TC Meeting [11:55] Gershon Janssen:
> Thursday, 27 September 2012, 12:00pm to 01:00pm PDT [11:55]
> AlessioSoldano morphed into AlessioSoldano(RedHat) [11:55] Gershon
> Janssen: Host confcall: Fujitsu US Toll Free: 877-995-3314 US
> Toll/International: 210-339-1806 Passcode: 9589308 [11:55] Dug: hey
> Alessio! long time no chat!
> [11:55] AlessioSoldano(RedHat): hi Dug [11:58] Gershon Janssen: Agenda
> 1.Administrative -Minutes previous meeting
> (https://www.oasis-open.org/apps/org/workgroup/ws-brsp/email/archives/
> 201209
> /msg00008.html) -WS-I MS affiliation update. -Some meetings may need
> be extended a bit? 2.Logistics / Process about Maintenance of
> profiles, tools -JIRA for WS-BRSP
> https://www.oasis-open.org/apps/org/workgroup/ws-brsp/email/archives/2
> 01209/ msg00010.html -Comment list and its use. -General process to
> handle users requests/comments. -Inventory: Current set of tools:
> nature, suites,
> availability: (1) old profiles tools (for BP1.1 and derived, BSP1.1):
> monitors + analyzers (C#, Java), (2) new profiles tools (for BP1.2/2.0
> and
> RSP1.0): logger + analyzers (python, XSLT). -In the short term: Test
> tools
> access: downloads from http://www.ws-i.org/, set-up in OASIS
> infrastructure (we are currently sorting out with OASIS staff the use
> of Subversion s.code control, IP aspects, giving access to TC members,
> for code use / code updates). -The current bug report (Gerwins BP10
> bug), proposed resolution to be sent out before meeting.
> 3.Distribution and management of source code (long term) -Role of
> OASIS (Jamie?) -Licensing aspects (Micah), OSS solutions. 4.Other
> lines of work -Profile Specifications Moving current Profiles toward OASIS CS or further. Formatting & source doc considerations.
> -Still clarify our work priorities (testing? Profiles/tools maintenance?
> Progress latest profiles as OASIS specifications/standards?) Who is
> interested in what line of work.
> [12:02] anonymous morphed into Micah Hainline [12:03] Gershon Janssen:
> Scribe: Gershon Janssen [12:04] Gershon Janssen: 0. Call to Order and
> Welcome [12:04] Gershon Janssen: Roll call: Voting members: <Present,
> Name> Mike DeNicola x Jacques Durand x Gershon Janssen x Doug Davis x
> Alessio Soldano x Micah Hainline x Ram Jeyaraman Tom Rutt Joel Fleck
> [12:05] Gershon Janssen: 6 voting members on the line; this is a
> quorate meeting.
> [12:05] Gershon Janssen: 1.Administrative [12:05] Gershon Janssen: J:
> Extend today&apos;s meeting with 15 minutes?
> [12:06] Gershon Janssen: Some members need to leave after 1 hour
> [12:07] Gershon Janssen: Approval of Minutes of previous meeting
> (https://www.oasis-open.org/apps/org/workgroup/ws-brsp/email/archives/
> 201209
> /msg00008.html)
> [12:07] Gershon Janssen: Objections to approval? Minutes approved by
> unanimous consent.
> [12:07] Gershon Janssen: -WS-I MS affiliation update.
> [12:08] Gershon Janssen: WS-I MS StC was cancelled, so decision
> defered to October StC meeting.
> [12:09] Gershon Janssen: -Some meetings may need be extended a bit?
> [12:09] Gershon Janssen: Next meet in 3 weeks?, so October 18?
> [12:11] AlessioSoldano(RedHat): any time earlier then this (12 PDT) is
> fine for me [12:12] Gershon Janssen: Back-up meeting time is 1 hour
> earlier than the regular time.
> [12:12] Gershon Janssen: Next meeting is 18/oct @ 3p or 2p [12:13]
> Gershon Janssen: After that the next meeting is on 15/nov @ 3p or 2p
> (tentative)
> [12:14] Gershon Janssen: Extend meeting to 90 minutes due to the
> infrequent meetings and workload?
> [12:14] Gershon Janssen: 1 hrs earlier + 90 minutes would work.
> [12:14] Gershon Janssen: 2.Logistics / Process about Maintenance of
> profiles, tools [12:15] Micah Hainline: I don&apos;t think 90 minute
> meetings work well [12:15] Gershon Janssen: Comment list has been
> setup (corrected); JIRA has been setup.
> [12:16] Gershon Janssen: - General process to handle users
> requests/comments [12:16] Gershon Janssen: J: process is all feedback
> should come through the comments list [12:17] Gershon Janssen: J: bug
> reports should go JIRA [12:18] Gershon Janssen: J: suggestion to
> systematically report all comments that qualify for subsequent action
> into a JIRA issue [12:18] Gershon Janssen: J: assign a person for
> this?
> [12:19] Gershon Janssen: Micah: all have a JIRA account -- whoever has
> time can put it in as a JIRA issue [12:19] Gershon Janssen: J:
> preference for a designated person; e.g. chair or secretary can
> monitor this process.
> [12:20] Gershon Janssen: J: this involves: look at comments list -->
> qualifies for an issue? --> create a JIRA issue [12:21] Gershon
> Janssen: Gershon volunteers to start with this.
> [12:22] Gershon Janssen: J: next steps are: based on issue posted,
> person to be assigned to issue in order to work on a solution [12:24]
> Gershon Janssen: J: assignee can work on resolution; post comments;
> reassign, etc. This is to make sure issues don&apos;t stay unassigned.
> [12:24] Gershon Janssen: J: final decisions on issues to be done at TC
> meetings.
> [12:26] Gershon Janssen: TC agrees to start with handling issues like this.
> [12:26] Gershon Janssen: - Inventory: Current set of tools:
> [12:27] Gershon Janssen: 2 sets:
> [12:27] Gershon Janssen: (1) old profiles tools (for BP1.1 and
> derived,
> BSP1.1): monitors + analyzers (C#, Java) [12:28] Gershon Janssen: (2)
> new profiles tools (for BP1.2/2.0 and RSP1.0):
> logger + analyzers (python, XSLT)
> [12:33] AlessioSoldano(RedHat): is there the link of the svn repo?
> [12:33] Gershon Janssen: Action Item: look at how much we can do to
> fix the bug and as part of that investigate the SVN repo access
> [12:34] Gershon Janssen: SVN repo -- See
> https://tools.oasis-open.org/version-control/browse/wsvn/ws-brsp/
> [12:34] AlessioSoldano(RedHat): thanks [12:35] Gershon Janssen: Action
> item: look at how much we can do to fix the bug and as part of that
> investigate the SVN repo access; report at next meeting on what we
> have.
> [12:37] anonymous morphed into Jamie Clark [12:37] Jamie Clark: (Which
> is why i joined the call) [12:37] Gershon Janssen: Micah willing to
> look into this -- JAVA based stuff.
> [12:38] Gershon Janssen: @Jamie: added you to the roll [12:38] Gershon
> Janssen: 3.Distribution and management of source code (long
> term) - Role of OASIS (Jamie?) - Licensing aspects (Micah), OSS solutions.
> [12:39] Gershon Janssen: Jamie to speak about this.
> [12:39] Gershon Janssen: Jamie: share what has been discussed by email
> offline.
> [12:39] Gershon Janssen: Jamie: all WS-I testing tools belongs to
> OASIS now [12:40] AlessioSoldano(RedHat): AFAICS our section of the
> svn repo is simply empty atm [12:41] Dug: right - we need to upload
> our src [12:41] Dug: tool src [12:44] Gershon Janssen: Jamie: donate
> code to public domain; licensing not important but important is what
> we want to do.
> [12:47] Jamie Clark: (License could be "important" but isn&apos;t part
> of what we thibk the TC needs to focus on ...) [12:49] Gershon
> Janssen: @Jamie: thanks -- my wording was a bit off...
> [12:59] Dug: I need to drop
> [12:59] Gershon Janssen: Thank dug; cheers!
> [12:59] Dug: bye
> [13:01] Dug: dropped
> [13:02] Dug: byte Jacques - see you next week at cmwg [13:02] Gershon
> Janssen: @jacques to post resolution to chat room for minutes.
> [13:02] Gershon Janssen: Micah: StC will make recommendation to Board
> [13:03] Gershon Janssen: Jamie: confirm what has been discussed by
> message to the list [13:03] Gershon Janssen: Jamie: does it cover all
> concerns?
> [13:04] Gershon Janssen: J: past users of WS-I profiles claim
> conformance and use of logo?
> [13:04] Gershon Janssen: Jamie: logo did come with the work.
> [13:04] Gershon Janssen: Jamie: continue use of logo, check with WS-I StC.
> [13:08] Gershon Janssen: Next step is to ask the MS StC.
> [13:09] Jacques (Fujitsu): Resolution: to approve the proposed
> resolution (BRSP mailing list, 9/26) to Gerwin issue report, and
> communicate it as TC-BRSP decision to Gerwin, with the condition that
> Gerwin posts prior to this his report in our comment list.
> [13:11] Gershon Janssen: jacques moved; micah seconded it. motion carries.
> [13:12] Gershon Janssen: 4. Other lines of work [13:12] Gershon
> Janssen: J: Profile Specifications Moving current Profiles toward
> OASIS CS or further.
> [13:13] Gershon Janssen: J: BP1.2 BP2.0 and RSP1.0 [13:13] Gershon
> Janssen: J: specs are complete, maybe should be updated a bit [13:13]
> Gershon Janssen: J: formatting aspect.
> [13:13] Gershon Janssen: J: source is XML [13:14] Gershon Janssen: J:
> by oasis rules: source format, PDF and xHTML [13:14] Gershon Janssen:
> J: we have a source format, XML.
> [13:14] Gershon Janssen: J: from XML to HTML and from HTML to PDF
> shoud be possible [13:15] Gershon Janssen: J: problem is how to render
> the frontpage.
> [13:15] Gershon Janssen: J: how to convert current format to a format
> editors are more familiar with, e.g. MS WORD.
> [13:16] Micah Hainline: I have another call [13:16] Micah Hainline: I
> have to go [13:16] Gershon Janssen: J: so two options: 1. use source
> and convert; 2.
> convert to WORD and work from there.
> [13:17] Gershon Janssen: ideas? comments?
> [13:18] Gershon Janssen: Gershon has a preference for generating,
> though frontpage issue. probably investigate a bit [13:18] Gershon
> Janssen: comments and ideas are welcome ; to be shared on the list.
> AlessioSoldano(RedHat): bye
> Jacques (Fujitsu): spec editing and progression: solution1:
> XML=source, generate HTML (using ws-i XSLT converter), generate PDF
> (from HTML) Jacques (Fujitsu): solution 2: port the spec (probably
> from its HTML format) into a conventional word processor (MSword, OO..) and work from there.
> Jacques (Fujitsu): Process for handling feedbacks:
> Jacques (Fujitsu): 1. Users must report comments / issues on the BRSP
> comment list.
> Jacques (Fujitsu): 2. The "comments monitor" (TC member, currently
> Gershon) files a JIRA issue for every comment that looks like it needs TC action.
> Jacques (Fujitsu): 3. Assignment of the issue for further investigation:
> either TC members pick-up the issue on their own, or chair finds an
> assignee.
> Jacques (Fujitsu): 4. The assignee makes a recommendation to TC, that
> could informally be communicated to the user as just in-progress (not
> formally
> TC-approved)
> Jacques (Fujitsu): 5. The TC makes a formal decision about this
> recommendation at next meeting - either a resolution, or just a
> direction to take to make progress on it.
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: ws-brsp-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: ws-brsp-help@lists.oasis-open.org
>



--

/chet
----------------
Chet Ensign
Director of Standards Development and TC Administration
OASIS: Advancing open standards for the information society http://www.oasis-open.org

Primary: +1 973-996-2298
Mobile: +1 201-341-1393

TC Administration information and support is available at http://www.oasis-open.org/resources/tcadmin

Follow OASIS on:
LinkedIn:    http://linkd.in/OASISopen
Twitter:        http://twitter.com/OASISopen
Facebook:  http://facebook.com/oasis.open

---------------------------------------------------------------------
To unsubscribe, e-mail: ws-brsp-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: ws-brsp-help@lists.oasis-open.org