Manpage documentation style

[mwichmann]

Various projects have differing style approaches for their reference manual. Some of the CPython developers are having a style discussion at the moment, which inspires me to ask the question here as well.

Should there be a preferred documentation style for SCons?

For this discussion, consider two styles: the classic "manpage style" is more narrative, and SCons mostly uses this style, but not always. An outside example is Python's open function.

For SCons, a similar example is Glob: parameters are described, often each in its own paragraph (although this is not universal in SCons' manpage), with supporting material such as tables when needed.

The contrasting style is more explicit about parameters. Some Python functions have been converted, or were just written, in a more explicit style, like for example sqlite3.connect. And of course, SCons has some of those as well, like the discussion of Scanner Objects. The SCons API docs are generated from code (by Sphinx) and so follow this style, but they're not designed as user-facing documentation, and we, perhaps unfortunately, do not get much help in generating user documentation from SCons code.

Why does this even matter? Some think the explicit style makes it easier to identify parameters (though there's been quite a debate - actually several threads over time - in the CPython community about this), and it's certainly easier to include typing information should that ever become a larger issue. Today, some type annotations have crept into SCons gradually, but more for internal use; any notation about types of parameters is either not mentioned or mentioned in a somewhat awkward prose style, like this snippet:

SCons searches for the toolname specification file as described above, and passes kw_dict, which must be a dictionary, as keyword arguments to the tool's generate function.

Note that a large percentage of the manpage content comes from the special SConsXML markup of builders, environment methods, construction variables and tools. The tooling helps define the presentation and some tweaks could be made there, but it's still up to each individual entry how the information is conveyed.

This isn't a "call to action", just a discussion topic to see if it's desirable to have a policy that says something like "for new or revised content, prefer XXX style".