[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. /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 > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]