OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Subject: DOCBOOK: Marking up generic names for API functions

I have the job of marking up the manual for a cross-platform API. Most of
the issues are resolved however I have one left. In the description of
each function the function name is given in a generic form. This API has
different bindings depending upon the platform, e.g. UNIX, client-side
(actually Microsoft Windows and because of poor configuration management
over the years there are three separate MS bindings with incompatible
argument lists!), or OpenVMS. With this in mind it would be inappropriate
to use a specific name from one of these bindings in the description of
the function.

For example, the generic name of a routine might be EAT JERKY with
bindings of XyzEatJerky (UNIX), XyzEatJerky (client-side, which at least
is consistent across all the clients) and xyz$eat_jerky (OpenVMS). The
description of this function might be:

"The EAT JERKY function is used when the user wishes to gain some
immediate sustenance. It is should only be called after VISIT STORE has
been executed."

How would others markup the EAT JERKY (and VISIT STORE) string in this
text? I thought function might be appropriate but I have some nagging
doubts that this is right expecially as it's used heavily earlier in the
refentry when the bidings are presented. Many sugegstions?

Regards, Trevor

British Sign Language is not inarticulate handwaving; it's a living language.
Support the campaign for formal recognition by the British government now!


<>< Re: deemed!

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC