OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: RE: [dita] Use of Syntax Elements

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.


> -----Original Message-----
> From: Tony Self [mailto:tself@hyperwrite.com] 
> 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:gerjosep@cisco.com]
> Sent: Monday, 19 July 2010 6:42 PM
> To: tself@hyperwrite.com; 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 

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]