search

petermr / ami3

Integration of cephis and normami code into a single base. Tests will be slimmed down
Apache License 2.0
17 stars 5 forks source link

Documentation: create man pages for ami commands #16

Open remkop opened 4 years ago

remkop commented 4 years ago

Background

The ami toolset is used in the https://github.com/petermr/openVirus project to convert scientific papers from PDF and other formats into machine-readable and searchable formats. The toolset is very large, being the result of many years of work; we want to make it more accessible and lower the learning curve for collaborators.

Proposed Change

I propose that we add a step to the Maven build to generate man pages (in unix man page format and HTML). Picocli can auto-generate AsciiDoc pages for all picocli commands; these pages can then be converted to various other formats with the AsciiDoctor tool.

TBD: should the generated HTML pages be hosted somewhere in the ami3 project for easy reference?

Benefits

Make it easier for ami users to find commands that meet their needs, and how to use these commands.

Man page documentation can be generated automatically for all commands.

Drawbacks

Adds dependencies to the project and complicates the build.

remkop commented 4 years ago

Also, as mentioned in #15, the usage help message for all ami commands should show runnable examples.