Skip to content

Use fullhelper.py to simplify writing and updating fullhelp messages

lgsmith edited this page Jun 4, 2019 · 2 revisions

We encourage adding a --fullhelp option to most LOOS tools. Where --help (or no arguments at all) will simply list the command line options with a short description, --fullhelp should provide details about the algorithm, suggested workflows, assumptions and gotchas, references, etc.

However, writing (and especially editing) the fullhelp text can be a little irritating, because we expect the coder to handle linebreaks, etc, to make it readable in the terminal. To make this process a little easier, we supply fullhelper.py in the main LOOS directory.

Usage is:

fullhelper.py thefullhelpmessage.txt thetool.cpp '\"the locator string\"' [desired_num_cols]"

thefullhelpmessage.txt is a standalone text file containing the fullhelp message, while thetool.cpp is the tool to which you want to add it. In thetool.cpp, you put a piece of marker text (eg "XXXXX") where you want the fullhelp text to go, and fullhelper.py will put it there in a test file for your review, correctly reflowing it so that the text is 80 columns wide; if you want a different textwidth, supply it as desired_num_cols. The test file will be called 'fullhelp-test-thetool.cpp', and you can simply 'mv' it to 'thetool.cpp' once you're happy with how it looks.