Hi all, I like mdoc. It feels like a natural fit for operating system documentation. Recently however, I've been in a position to document a REST API. I was wondering how mdoc could be made to work there. Many of the tags do not fit: For example, there seems to be nothing to properly map the request method (GET, POST, PUT, DELETE), the closest equivalents seem to be Dv and Ft, but neither really fit. Nm would *have* to contain the method and the path, but Nm also requires exactly one argument to be given, so that's extra quoting effort.
With REST, you often want to provide an overview of request input and outputs. These are somewhat analogous to function arguments and struct output types. Often, the responses may be ad-hoc and not really have a "type" of sorts. You tend to need a top-level explanation that describes how error handling works, how data is serialized (XML, JSON or something even more horrifying) and how authentication works. Would a dedicated introduction page be alright for that? Filenames are another issue. '/' is an invalid character on UNIX within a filename, but a REST method starts with a '/'. This will cause the Dt and filename to always mismatch. Has anyone used mdoc for REST API documentation before? How did you make it work? If not: What would be the path of least resistance, surely not DocBook? Max
