Gershon, as I recall Mark Novembrino thoroughly documented his
algorithms for the in-line syntax editing widget so that it could be
re-implemented. This would be useful information for the Adoption TC
paper. There's nothing proprietary about it, and I see no reason why we
could not share it. Do you? I think Just Systems already has that info.
/Bruce
> -----Original Message-----
> From: Tony Self [mailto:]
> Sent: Tuesday, July 20, 2010 7:28 AM
> To: Gershon Joseph (gerjosep); 'DITA TC'
> Subject: RE: [dita] Use of Syntax Elements
>
> Thanks for the great information, Gershon!
>
> The use of <synblk> is an innovative approach. I hadn't
> thought at all about the role of the @importance attribute,
> so that's a fantastic suggestion by itself!
>
> Would you be so kind as to send me some sample mark-up?
>
> Cheers!
>
> Tony Self
>
>
>
>
> -----Original Message-----
> From: Gershon Joseph (gerjosep) [mailto:]
> Sent: Monday, 19 July 2010 6:42 PM
> To: ; DITA TC
> Subject: RE: [dita] Use of Syntax Elements
>
> Hi Tony,
>
> I have "hacked" the syntax diagram elements to successfully
> mark up CLI commands and the like.
>
> For command blocks, for example in a command reference topic,
> we use <synblk>. This has everything we need to mark up a command:
>
> Within the syntax block, which represents a single instance
> or form of a command, we use <groupseq>, <groupchoice> and
> <groupcomp>, where:
> <groupseq> has keywords and/or arguments that must occur in a
> specific sequence <groupchoice> has a choice of
> keywords/arguments <groupcomp> contains both group sequences
> and group choices.
>
> Within each group*, we use <kwd> and <var> mainly, sometimes
> also using <delim> and <oper> when relevant.
> <kwd> represents a keyword (the command name comprises one or more
> keywords)
> <var> represents an argument (or variable).
>
> In command blocks this markup works quite well. We've
> obviously tweaked our stylesheets to format the braces etc.
> automatically, and we use @importance="optional" on a group
> choice, group sequence, keyword or argument that is optional,
> and rendering does the right thing (again, we had to tweak
> the stylesheets for this).
>
> When commands or fragments of a command syntax appear inline,
> it's more challenging. Here we use <synph> and don't have the
> luxury of the group* elements, so we use need to mark up the
> pipes etc. manually in the syntax phrase. This means:
>
> 1) we can't easily reuse parts of command syntaxes between
> <synblk> and <synph>.
>
> 2) authors need to mark up the syntax markers in <synph>
> instead of having the stylesheets do it for them, which is
> painful and error-prone.
>
> Due to the lack of symmetry between synph and synblk, I plan
> to create a specialization for Cisco to better capture CLI
> command syntax than the current out-of-the-box DITA provides.
> I expect I'll contribute this back to the Technical
> Communication Subcommittee that I plan to kick off after the
> summer holidays are over. We need to be able to reuse command
> syntax fragments between syntax blocks and syntax phrases in
> various contexts that are not supported today. There may also
> be a need to identify a command name (as opposed to keywords)
> via the markup, which we can't do today.
>
> Hoping this helps. Let me know if you have any specific
> questions or would like me to provide some sample markup. We
> use this markup successfully in production where we
> single-source the CLI command references of our entire IOS XR
> family of routers.
>
>
> --
> Gershon
>
>
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS
> TC that generates this mail. Follow this link to all your
> TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgr
> oups.php
>
>
