RE: [dita] Use of Syntax Elements

["Gershon Joseph (gerjosep)" <gerjosep@cisco.com>]

Hi Bruce,

I don't think Mark's algorithms are relevant to this discussion. His
code is a text parser that parses plain text as input and applies markup
to that text as output. The Adoption TC article should only discuss how
to mark up command syntaxes in DITA. A command syntax editor is beyond
the scope of the DITA and DITA Adoption TCs. Please take any further
discussion on this topic off-list privately with me only, since I don't
think it's correct to continue discussing this topic openly on the
public TC lists. Mark's work is Cisco IP and if it was shared with any
vendor, it was shared under NDA.


--
Gershon

-----Original Message-----
From: Bruce Nevin (bnevin) 
Sent: Wednesday, July 21, 2010 1:52 AM
To: tself@hyperwrite.com; Gershon Joseph (gerjosep); 'DITA TC'
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.

	/Bruce

> -----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 
> 
>