I would like to know if there are guidelines for package writers regarding the interface preferred for passing arguments to macros. Suppose I am writing a package for typesetting a titlepage. There are three main options:

  1. LaTeX macro style \titlepage[color]{<title>}{<author>}
  2. key-val style \titlepage{author=..., title=..., color=...}
  3. "declarative" style \author{...}\title{...}\maketitlepage

Now, I prefer 2 and 3 to 1 because they do not require the user to remember the order of the arguments, they are more "literate" and they seem to be easier to extend.

Moreover, suppose I want to make my title page "themable". Would mixing keys for "data" (author/title) and "appearance" (color) be acceptable? Is key-val better suited for customisation rather than specification of content?

I think it is important to aim at uniform passing style to make adoption of packages smoother, but I could not find a clear guideline.

  • 4
    Excluding the first that could be acceptable with at most the three argument you propose, choosing between the other two is just a matter of taste. However, as the number of options increases, the second way seems more easy to manage both for the developer and the user; with only a few options to choose from, 2 and 3 are mostly equivalent. – egreg Oct 4 '13 at 23:45
  • Thanks for the feedback. I still feel though that there are "conceptual" differences between arguments like author and color, for example, that may be reflected in the "calling" convention. If I can make it clearer in my mind I may attempt to write my own answer to foster discussion – Bordaigorl Oct 5 '13 at 10:12
  • Meta: should this question be a community wiki? – Bordaigorl Oct 5 '13 at 10:57

My rule of thumb is: if the number of possible arguments is small, and all but one or two are mandatory, I use standard arguments. If the number is large, or there are several optional arguments, key-value interface is probably better.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.