Hi Kris
I would hope this would be something that is of general
interest, but maybe few people are actually documenting command line systems? I’m
getting to the difficult bits of the DITA Style Guide that I’ve been
working on for the past few years as part of my PhD, and that’s where it
cropped up. (And I am building up a stock of potential articles; there are two
in the system at the moment as academic papers. I’ve attached copies in
case you’re interested.) I would be very grateful if you could dig up any
education documents and examples! That would be most useful. But don’t
spend a lot of time looking... you are busy enough as it is.
Which leads me nicely to something that I should have written
earlier. Thank you, thank you, thank you, for all the work you’ve put
into 1.2. I’m certain I’m not alone in admiring your tenacity and
dedication in driving the process forward, and I feel very guilty for not
contributing more myself. You’re my hero.
Cheers
Tony
From:
Kristen James Eberlein [mailto:kris@eberleinconsulting.com]
Sent: Monday, 19 July 2010 9:34 PM
To: dita@lists.oasis-open.org
Subject: Re: [dita] Use of Syntax Elements
Hi,
Tony.
I don't know whether IBM further specialized the elements for command-line
syntax or not. If not, I have extensive examples and documentation written to
educate team members on how to use them which I'd be happy to share. This is
material that I produced back (in 2004? Early 2005?) when IBM's internal
documentation did not have much written about the DITA elements used for
command-line syntax.
Do you think that an article about this would be of general interest?
Best,
Kris
Kristen James Eberlein
Principal consultant, Eberlein Consulting
Secretary, OASIS DITA Technical Committee
Charter member, OASIS DITA Adoption Committee
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)
On 7/19/2010 1:20 AM, Tony Self wrote:
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