RE: [dita] Use of Syntax Elements

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

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

-----Original Message-----
From: Tony Self [mailto:tself@hyperwrite.com] 
Sent: Monday, July 19, 2010 8:20 AM
To: 'DITA TC'
Subject: [dita] Use of Syntax Elements

Greetings colleagues

Does anyone have any good examples of the elements used to describe
command line syntax in action?

The Microsoft Manual of Style for Technical Publications (MSTP) suggests
command line syntax is made up of:
. name of the command (bold)
. a set of choices ({ })
. separator for mutually exclusive choices (|) . arguments (italics) .
optional items ([ ]) . repeated items (...)

The DITA synph element can include the following elements:
. codeph
. delim
. kwd
. oper
. option
. parmname
. sep
. var

Some of these elements are from the programming domain, and others from
the software domain. 

When trying to map the MSTP to the DITA synph elements, it seems that
there is no semantic element to indicate a set of choices, and possibly
the separator for mutually exclusive choices and repeated items. (I say
possibly because the <sep> element looks good at first as the separator,
but the spec seems to suggest it is used for something else.) 

Also confusing is the var element, which the spec description says is
only used in syntaxdiagrams, but in fact may occur within synph. 

I've come up with a simple syntax example of:

<synph>
  <kwd>ant</kwd>
  <option>-f</option>
  <var>filename</var>
  <option>-logfile</option>
  <var>filename</var>
  <option>-verbose</option>
</synph>

Is this right? Should <var> have been <parmname>?

And how would I mark-up a slight more complicated example (from MSTP)
of:
{[form.] [control.]|Printer.}FontSize[=points%]

Am I right in thinking this might be an under-documented area of DITA?

Tony Self




---------------------------------------------------------------------
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_workgroups.php