5

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.

Bordaigorl
  • 15,135
  • 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 04 '13 at 23:45
  • related http://tex.stackexchange.com/questions/132928/why-various-syntaxes-for-various-commands/132935#132935 and http://tex.stackexchange.com/questions/23075/packages-graphics-vs-graphicx/86725#86725 – David Carlisle Oct 04 '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 05 '13 at 10:12
  • Meta: should this question be a community wiki? – Bordaigorl Oct 05 '13 at 10:57

1 Answers1

4

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.

Boris
  • 38,129