Standardized modular manpage sections (environment variables, files, exit status, see also,...)

[taladar]

clap_mangen currently does not do much yet to generate man pages that can not directly be fully derived from the clap configuration.

I think there are a couple of man page sections which are fairly standardized (as in a lot of CLI program man pages have them if applicable) but they are also highly modular.

It might be useful to have some way to assemble these in clap_mangen from different sources to avoid duplicate effort on writing the same documentation over and over again.

For the pieces from which these are assembled it might make sense to stick to standard types that require no dependencies so libraries could easily include a relevant snippet or two (e.g. database library could document the format of its DATABASE_URL variable or a logging library could document RUST_LOG).

Since some libraries might want to include several related ones which should be displayed in a group in a specific order it would probably be useful to allow adding vectors of several such objects too. Potentially the type should also include section headings.

Some of the sections might want to generate some content from clap config and the rest could be specified manually.

The following sections come to mind (after using grep on my man1 folder)

Environment Variables

Usually these list all the environment variables (besides the standard ones like PATH or HOME) that influence the functioning of the program. A good example for a long list of variables would be the git man page.

Files

The files section usually contains config files, some relative, some using variables like the XDG ones for their paths. Some common groups of files are those where several locations are tried in a specific order until a file is found or those where settings missing from one file are looked up in another (e.g. local, user-wide, system-wide).

Usually the locations are listed, followed by a block of explanation

Exit Status

This section documents the various exit statuses and their meaning, each exit status is fairly independent though this is less likely than other sections to need inclusion of values provided by libraries.

It might also make sense to allow the user to include some information on when the program might be expected to panic or have other abnormal exits, either in this or in a dedicated section rendered near this one.

See Also / Further Documentation

This section could easily include links for the main application but also for libraries used, e.g. when using sqlx for a server application one might want to link to the format for migrations and sqlx migrate run,...

This is also where other man pages should be mentioned. Perhaps clap_mangen could automatically include the ones it generates here if a crate has multiple binaries or if support for generating config file man pages is added later.

Reporting Bugs

This usually includes information on how to report bugs, probably less modular than some of the other sections but could still benefit from modular assembly if there are libraries involved that require their bugs to be reported elsewhere.

Copyright / Acknowledgements / License

This could benefit from modularity to allow people to include snippets about libraries they use that require them to mention their use.

Author / Authors

This might be similar to the above but more about the authors of the current program, not sure if it would benefit from modularity but it certainly couldn't hurt to be able to add independent snippets per author.

Bugs / Known problems / Caveats

Making this modular would allow library authors to just export a symbol that the CLI program author includes and the known bugs in the library change automatically without further work on the CLI program author's part.

Examples

This is probably less about libraries but it could still be beneficial to assemble examples from different parts of the CLI program's codebase.

History

This section often seems to include less of a changelog and more bits and pieces about the historical context of a program, e.g. in which historic OS versions it first appeared (or the programs which inspired its creation) or in which standards it was influded

Conclusion

I think this could be done in a relatively simple way for most of these sections, most likely as a type similar to

(Option, Vec<(String, String)>)

where the first String would be a heading within the relevant section and the second would be a list of e.g. Environment Variable name and a string documenting it. Obviously for certain sections it would have to be modified, e.g. for the files section you might want the name to be a Vec instead.

It might also be possible to use custom types from some light-weight crate most libraries interested in the feature wouldn't mind including. Ideally the format should not be too clap-specific or man page specific though to maximize adoption.

So, after writing all of this I was wondering what others here think about the idea.

[epage]

Thanks for writing this up! This is good information for #3354. Mind posting it over there to continue the conversation there?