OASIS Darwin Information Typing Architecture (DITA) TC

 View Only

  • 1.  Use of Syntax Elements

    Posted 07-19-2010 05:22 
    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


  • 2.  RE: [dita] Use of Syntax Elements

    Posted 07-19-2010 08:43 
    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


  • 3.  RE: [dita] Use of Syntax Elements

    Posted 07-20-2010 11:30 
    Thanks for the great information, Gershon!

The use of


  • 4.  RE: [dita] Use of Syntax Elements

    Posted 07-20-2010 22:53 
    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


  • 5.  RE: [dita] Use of Syntax Elements

    Posted 07-21-2010 09:57 
    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


  • 6.  Re: [dita] Use of Syntax Elements

    Posted 07-19-2010 11:34 
    

  


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


  • 7.  RE: [dita] Use of Syntax Elements

    Posted 07-19-2010 12:06

    Attachment(s)

    pdf
    editing_paper2.pdf   402 KB 1 version
    pdf
    ANZCA_Context_Agnostic_Tony_Self_final.pdf   52 KB 1 version


  • 8.  Re: [dita] Use of Syntax Elements

    Posted 07-19-2010 20:53 
    On 7/19/10 6:33 AM, "Kristen James Eberlein"


  • 9.  Re: [dita] Use of Syntax Elements

    Posted 07-19-2010 22:03 
    Sounds like a good feature article for the Adoption TC.
JoAnn


On 7/19/10 2:51 PM, "Eliot Kimber"


  • 10.  RE: [dita] Use of Syntax Elements

    Posted 07-19-2010 23:10 
    Thanks, Eliot and JoAnn. And I think you have answered what would have been
my next question, JoAnn, about whether the article should be under the
auspices of the Adoption TC. I will start working on it.

Tony


    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 11.  Re: [dita] Use of Syntax Elements

    Posted 07-20-2010 14:58 
    Thanks, Tony,
Could you please add this to the Adoption TC Feature Articles wiki? With a
proposed completion date?

http://wiki.oasis-open.org/dita-adoption/SignUp

Thanks, JoAnn


On 7/19/10 5:08 PM, "Tony Self"


  • 12.  RE: [dita] Use of Syntax Elements

    Posted 07-21-2010 00:51 
    Hi JoAnn

Done!

Tony


    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


Related Content