RE: [dita] Use of Syntax Elements

["Tony Self" <tself@hyperwrite.com>]

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