How to specify a "build target" and other similar things

Hello, Team,

I am remiss in getting this out. However, it has proven an interesting issue to analyze.

It turns out the term “target” is used by many build systems, with at least three meanings:

1. A set of rules to build a project or product.

2. The file or files that the build will produce or location of the build result.

3. The hardware and/or software platform that the code should be prepared for (this sometimes overlaps with the first definition).

These definitions are used singly or in combinations in various build environments. Some build systems use alternatives such as “goal” for the set of rules concept while retaining usage of the term “target” for the destination of the build. Given the ambiguity of the term “target” it may not be the best choice for an additional DocBook element. Which brings up the question of how to represent what Ant and make refer to as a “target.”

Stepping back, Ant and Make are both commands that accept specific arguments that invoke specific behaviors (in both cases, user defined). Other commands such as git provide arguments that perform specific operations, but not specifically user-defined. However, it seemed worthwhile to look at things like git for their descriptive terminology. Git uses the term “command” for what invokes specific operations (for example: git pull origin or git commit). It would be a reasonable extension for something like Ant to use the same model, perhaps with a role or class attribute on the command element to provide information like that it is considered a build target. The cmdsynopsis element allows multiple command elements as children, which would make it possible to document Ant using this convention.

From a program interpretation standpoint, the “target” values passed into make or Ant are simply arguments to the command itself, so it might make sense to simply say use arg for it (again, an attribute could be used for clarification). Another alternative would be option, but those typically indicate controls over how something performs rather than what it does (by the way, I was somewhat surprised that options is not a valid child of cmdsynopsis – it has to be wrapped in an arg element, which seems needlessly complex).

Another potential is to use the procedure element, since in both Ant and make it is essentially a user-defined procedure definition that is being executed. Slightly further afield would be methodname, but it is tightly bound to object-oriented languages. I also considered token, but it does not seem to fit very cleanly.

During the discussion last month, the suggestion was made to consider whether the concept of a REST endpoint could be wrapped into this analysis. This is an interesting area of comparison, since in REST conventions, the endpoint is typically an object or collection and the HTTP request method determines the action applied to whatever is specified by the specified endpoint. In definition 1 of “target” it operates more like and action than an object, although the second definition makes the two more similar. While some APIs that are REST-like use endpoints that are operation (such as /initialize), many REST purists reject that model and insist on object/collection and the HTTPS methods for the operations (good old CRUD).

Other elements I considered but had difficulty reconciling with the meanings of “target” included interfacename and literal. I also considered adding a subcommand element, but I’m not sure how much that would buy us.

By the way, I was using the HTML version of the Definitive Guide at http://tdg.docbook.org/tdg/5.1/index.html and found that the DocBook Element Reference in the ToC does not list the entries in alphabetical order, which I found somewhat surprising.

I know that this is late to start the discussion, but this is what I came up with looking through things.

Regards,

Larry Rowland

docbook-tc message