TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
In a syntax summary -- what if one argument is a list of name-val ue pairs?
Subject:In a syntax summary -- what if one argument is a list of name-val ue pairs? From:"Haas, Guy" <ghaas -at- selectica -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Mon, 22 Jul 2002 11:46:31 -0700
I am documenting a family of APIs in the world of C and Visual Basic. Every
release, some new functions are added to each API, and some existing
functions have their capabilities extended. This can mean that their
signature changes.
Many of the arguments to the functions are optional, offering default
values. Some are simple flags (true or false), some can take one of a short
list of values, and some take an expression (such as a file name, or a
formatting string).
We have adopted a mechanism of using a list (which we call BatchArgs) of
name-value pairs in the most volatile of the functions, so that the
signature as such does not change when a new capability is added. Instead, a
new name and accepted set of values is added to the list.
Now, I have a syntax summary appendix, which the reader who is acquainted
enough with the API would use as a handy reminder about the signature of any
function. BUT, the down side of a BatchArgs argument is that my summary
appendix shows only that such functions USE a BatchArgs argument, but gives
no clue about which of the (scores of) names are acceptable in it.
Has any of you addressed this sort of issue? How to helpfully advise the
reader of the syntax summary about such flexible arguments? Or whether the
reader even cares?
--Thanks
Guy K. Haas ghaas -at- selectica -dot- com or gkhaas -at- usa -dot- net
Software Exegete in Silicon Valley
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Buy RoboHelp Deluxe starting at only $798: you'll get RoboDemo, the hot new
software demonstration tool that's taking the Help authoring world by storm,
together with RoboHelp Office. Learn more at http://www.ehelp.com/techwr-l
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
