Loading ...
Sorry, an error occurred while loading the content.

Re: Documenting SOAP methods using apiref

Expand Messages
  • kyleschwamkrug
    What s the status of the APIref (and Java/C++ Ref) specialization, anyway? When I last checked, which was quite a while ago, the official word was that they
    Message 1 of 3 , Apr 27 7:53 AM
    View Source
    • 0 Attachment
      What's the status of the APIref (and Java/C++ Ref) specialization, anyway? When I last checked, which was quite a while ago, the official word was that they were going to be redone for several reasons, one of them being DITA 1.2.

      --- In dita-users@yahoogroups.com, Don Day <donday@...> wrote:
      >
      > Hi, Heather.
      >
      > Does this example represent a language-agnostic syntax in SOAP, or is it
      > a specific server-side language binding? I ask because the generic
      > APIref structure supports being specialized to represent a more specific
      > binding, at which point the Result and Errors structures could be
      > systematized as elements of that binding (as has been done for the C++
      > and Java representations).
      >
      > For now, your use of outputclass models your intent, as long as your
      > writers can follow this template reliably. I certainly see nothing
      > hugely concerning (as long as writers are consistent about adding the
      > correct outputclass values)--the model is consistent for structures in
      > any language reference topic. Thoughts from anyone else?
      > Don R. Day <mailto:donday@...>
      > DITA and XML Consultant, Learning by Wrote <http://learningbywrote.com/>
      > Co-Chair, OASIS DITA Technical Committee
      > <http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita>
      > "Where is the wisdom we have lost in knowledge?
      > Where is the knowledge we have lost in information?"
      > --T.S. Eliot
      >
      > On 4/25/2012 7:17 PM, Heather Wymer wrote:
      > >
      > >
      > > Hi,
      > >
      > > I'm reasonably new to DITA and am trying to document SOAP methods
      > > using the apiref specialisation. The methods send a snippet of XML and
      > > return a larger chunk of XML. I want my topic to look something like:
      > >
      > > Method
      > > Example
      > > Response
      > > Example
      > > Errors
      > >
      > > I've come up with the following structure, but I'm not sure how
      > > semantically accurate it is because of the number of <section> and
      > > <example> elements. Please let me know your thoughts.
      > >
      > > <apiOperationid="Subscription_Update">
      > > <apiName><apiname>update()</apiname></apiName>
      > > <shortdesc>This method updates the properties of a
      > > subscription.</shortdesc>
      > > <apiOperationDetail>
      > > <apiSyntax>
      > > <apiSyntaxText>method method(
      > > string text)</apiSyntaxText>
      > > <apiSyntaxItem>
      > > <apiItemName>string text</apiItemName>
      > > <apiDefNote>Specifies the name of the subscription to update.</apiDefNote>
      > > </apiSyntaxItem>
      > > </apiSyntax>
      > > <example><title>Example: The update() method</title>
      > > <p>This example updates some subscription properties:</p>
      > > <codeblock>some sample XML code</codeblock>
      > > </example>
      > > <sectionoutputclass="result"><title>Results</title>
      > > <p>If product ABC successfully updates the subscription, it returns an
      > > XML document that describes the subscription properties.</p>
      > > </section>
      > > <example><title>Example: A returned Subscription XML document</title>
      > > <p>This example shows you the XML document that will be returned if
      > > the method is successful:</p>
      > > <codeblock>some sample XML code</codeblock>
      > > </example>
      > > <sectionoutputclass="errors"><title>Errors</title>
      > > <msgph>Error message</msgph>
      > > <p>This error is returned if the subscription does not exist.</p>
      > > </section>
      > > </apiOperationDetail>
      > > </apiOperation>
      > >
      > > Thanks in advance,
      > > Heather
      > >
      > >
      > >
      >
    Your message has been successfully submitted and would be delivered to recipients shortly.