Adding Tools
Adding Tool Documentation to TooLoo
Adding tools to TooLoo is pretty straight-forward. You fill in a TOML1 template and then tell TooLoo to read it in.
Getting A Blank template
TooLoo will generate a blank template for you to fill in with the following command
tooloo template <command_name>
It will find the command in your PATH and attempt to store a file with the same name + .toml
For example, if you have an executable at ~/bin/foo and run tooloo template foo a new file will be created at ~/bin/foo.toml
If the directory isn't writable, or TooLoo can't find the command, it will ask you for the path to another directory where it can be written.
Note that TooLoo does not care where these files live. Keeping them next to the executable, just increases the chances that people will remember to update them when the tool changes. Since TOML is very readable, having it in the same directory as the tool means that people who don't use TooLoo will still see something giving them additional information about the tool.
Another strategy is to create a "tool_docs" directory, and keeping all your TooLoo TOML files in there.
Documentation Details
The comments in the generated template should be enough to convey what your tool is for, and why someone should use it, but here are some additional notes.
Whenever there's a listing of commands, short_description will be used. Depending on
your personal usage description may not be worth it. However, if
you're exporting and generating a static web site from tooloo you'll
definitely want to include a full description.
See demo.tooloo.dev for an example of how this looks in a static site.
Documenting Usage
The Usage section of each command is generated on the fly whenever
possible. Some commands don't have a --help option or anything
similar, in which case you'll need to fill in the fallback_usage. When
doing so, be sure to not use any tab characters. They'll muck with the table
that's displayed in the terminal.
If your commands usage invocation returns a non-zero exit code TooLoo will look for the word "USAGE" in the output. If it doesn't find it, it will assume that an error was encountered and state that the usage is "UNKNOWN".
Remember when creating your tools, that non-zero exit codes should only be returned when there's an error, and users requesting help or documentation shouldn't be considered an error.
Modifying The Template
The default template has lots of comments in it to get you started. After a while you may want to get rid of them, or maybe add additional fields.
You can find your customizable copy of the default template in XDG_CONFIG_HOME/tooloo/template.toml If you haven't set it explicitly, XDG_CONFIG_HOME usually defaults to ~/.config
Don't worry about accidentally messing it up. If you delete your copy, TooLoo will automatically regenerate it the next time you ask it to make a template for something.
Additional Fields
TooLoo will ignore additional fields that it's not familiar with. The only "gotcha" with adding your own, is that they may conflict with fields used in future versions of TooLoo.
