I’m not sure I understand the concern about the description being too long or confusing. The screenshot you provided looks concise and very clear to me.
Due to the command window being quite small, the screenshot might not have conveyed my problem with the current description field.
When I execute the HELP command on my printer, I currently get this output:
Available extended commands:
ACTIVATE_EXTRUDER: Change the active extruder
BED_MESH_CALIBRATE: Perform Mesh Bed Leveling
BED_MESH_CLEAR: Clear the Mesh so no z-adjustment is made
BED_MESH_MAP: Serialize mesh and output to terminal
BED_MESH_OFFSET: Add X/Y offsets to the mesh lookup
BED_MESH_OUTPUT: Retrieve interpolated grid of probed z-points
BED_MESH_PROFILE: Bed Mesh Persistent Storage management
BED_SCREWS_ADJUST: Tool to help adjust bed leveling screws
BLTOUCH_DEBUG: Send a command to the bltouch for debugging
BLTOUCH_STORE: Store an output mode in the BLTouch EEPROM
CALIBRATE_MPC: Calibrate MPC for the specified heater.
Usage: CALIBRATE_MPC HEATER=extruder Z=1.0
Parameters:
- [HEATER] The heater to calibrate, by default the extruder.
- [Z] How close the nozzle should be to the bed for calibration.
CALIBRATE_PID: Calibrate PID for extruder and bed.
Usage: CALIBRATE_PID EXTRUDER_TEMP=215 BED_TEMP=60
Parameters:
- [EXTRUDER_TEMP] The temperature of the extruder when calibrating.
- [BED_TEMP] The temperature of the bed when calibrating.
CALIBRATE_PRESSURE_ADVANCE: Print calibration pattern for pressure advance value.
CALIBRATE_XYZ_CUBE: Print XYZ calibration cube.
CANCEL_PRINT: Cancel the actual running print
CANCEL_PRINT_1: Renamed builtin of 'CANCEL_PRINT'
CLEAR_PAUSE: Clears the current paused state without resuming the print
D117 : Emit a message to the console.
DEBUG_EXTRUDER_VALUES: Prints the extruder values that depend on nozzle/filament diameter, useful for debugging.
END_PRINT : G-Code macro
EXCLUDE_OBJECT: Cancel moves inside a specified objects
EXCLUDE_OBJECT_DEFINE: Provides a summary of an object
EXCLUDE_OBJECT_END: Marks the end the current object
EXCLUDE_OBJECT_START: Marks the beginning the current object as labeled
FIRMWARE_RESTART: Restart firmware, host, and reload config
G28 : Home one or more axes.
Usage:
G28 [O] [X] [Y] [Z]
Parameters:
- [O] Flag to skip homing if the position is already trusted ("smart home")
- [X] Flag to home X axis
- [Y] Flag to home Y axis
- [Z] Flag to home Z axis
https://marlinfw.org/docs/gcode/G028.html
G28.1 : Renamed builtin of 'G28'
GET_POSITION: Return information on the current location of the toolhead
GET_RETRACTION: Report firmware retraction paramters
HELP : Report the list of available extended G-Code commands
LINE_PURGE: A purge macro that adapts to be near your actual printed objects
LOAD_FILAMENT: Load filament into the active extruder.
Usage: LOAD_FILAMENT EXTRUDER_TEMP= PURGE_LENGTH= PURGE_FEEDRATE=
TRAVEL_SPEED=
Parameters:
- [EXTRUDER_TEMP] Temperature of the extruder for purging filament
- [PURGE_LENGTH] How much filament should be extruded (purged) in mm
- [PURGE_FEEDRATE] How fast the filament should be purged (in mm/s)
- [TRAVEL_SPEED] How fast the printer should move
M17 : Enables the specified stepper motors.
If no flags are specified, all motors are enabled.
Usage: M17 [E] [X] [Y] [Z]
Parameters:
- [E] Enable extruder
- [X] Enable x stepper
- [Y] Enable y stepper
- [Z] Enable z stepper
https://marlinfw.org/docs/gcode/M017.html
M18 : Disables the specified stepper motors.
If no flags are specified, all motors are disabled.
Usage: M18 [E] [S] [X] [Y] [Z]
Parameters:
- [E] Enable extruder
- [X] Enable x stepper
- [Y] Enable y stepper
- [Z] Enable z stepper
- [S] Inactivity Timeout. If none specified, disable now.
https://marlinfw.org/docs/gcode/M018.html
M18.1 : Renamed builtin of 'M18'
M600 : Change filament.
Usage: M600 [R] [B] [X] [Y] [Z]
Parameters:
- [R] Temperature of the extruder for purging filament, by default target temperature or 180°C if target is lower.
- [R] Temperature of the bed, by default remains unchanged.
- [X] X position for filament change
- [Y] Y position for filament change
- [Z] Z relative lift for filament change position
https://marlinfw.org/docs/gcode/M600.html
M701 : Load filament into the active extruder.
Usage: M701 [T] [L] [F] [S]
Parameters:
- [T] Temperature of the extruder for purging filament, by default 210°C.
- [L] How much filament should be extruded (purged) in mm, by default 50mm.
- [F] How fast the filament should be purged, by default 3
- [S] How fast the printer should move, by default 1000
https://marlinfw.org/docs/gcode/M701.html
M702 : Unload filament from the active extruder.
Usage: M702 [S]
Parameters:
- [S] Temperature of the extruder for purging filament, by default 210°C.
https://marlinfw.org/docs/gcode/M702.html
M84 : Disables the specified stepper motors.
If no flags are specified, all motors are disabled.
Usage: M84 [E] [S] [X] [Y] [Z]
Parameters:
- [E] Enable extruder
- [X] Enable x stepper
- [Y] Enable y stepper
- [Z] Enable z stepper
- [S] Inactivity Timeout. If none specified, disable now.
https://marlinfw.org/docs/gcode/M018.html
M84.1 : Renamed builtin of 'M84'
MANUAL_PROBE: Start manual probe helper script
MPC_CALIBRATE: Run MPC calibration test
MPC_ENABLE: Enable MPC algorithm for heating
MPC_UPDATE: Update values for the MPC algorithm
OFF : Macro to power off everything.
Usage: OFF
https://ellis3dp.com/Print-Tuning-Guide/articles/useful_macros/off.html
PAUSE : Pause the actual running print
PAUSE_BASE: Renamed builtin of 'PAUSE'
PID_CALIBRATE: Run PID calibration test
PRINT_VARIABLES: Prints all variables or only those that match a specific filter.
PROBE : Probe Z-height at current XY position
PROBE_ACCURACY: Probe Z-height accuracy at current XY position
PROBE_CALIBRATE: Calibrate the probe's z_offset
QUERY_ADC : Report the last value of an analog pin
QUERY_ENDSTOPS: Report on the status of each endstop
QUERY_FILAMENT_SENSOR: Query the status of the Filament Sensor
QUERY_PROBE: Return the status of the z-probe
RESPOND : Echo the message prepended with a prefix
RESTART : Reload config file and restart host software
RESTORE_GCODE_STATE: Restore a previously saved G-Code state
RESUME : Resume the actual running print
SAVE_CONFIG: Overwrite config file and restart
SAVE_GCODE_STATE: Save G-Code coordinate state
SCREWS_TILT_CALCULATE: Tool to help adjust bed leveling screws by calculating the number of turns to level it.
SDCARD_PRINT_FILE: Loads a SD file and starts the print. May include files in subdirectories.
SDCARD_RESET_FILE: Clears a loaded SD File. Stops the print if necessary
SET_DISPLAY_TEXT: Set or clear the display message
SET_EXTRUDER_ROTATION_DISTANCE: Set extruder rotation distance
SET_EXTRUDER_STEP_DISTANCE: Set extruder step distance
SET_FILAMENT_DIAMETER: Sets the filament diameter to the specified value
SET_FILAMENT_SENSOR: Sets the filament sensor on/off
SET_GCODE_OFFSET: Set a virtual offset to g-code positions
SET_GCODE_VARIABLE: Set the value of a G-Code macro variable
SET_HEATER_TEMPERATURE: Sets a heater temperature
SET_IDLE_TIMEOUT: Set the idle timeout in seconds
SET_NOZZLE_DIAMETER: Sets the nozzle diameter to the specified value
SET_PAUSE_AT_LAYER: Enable/disable a pause if a given layer number is reached
SET_PAUSE_NEXT_LAYER: Enable a pause if the next layer is reached
SET_PRESSURE_ADVANCE: Set pressure advance parameters
SET_PRINT_STATS_INFO: Overwrite, to get pause_next_layer and pause_at_layer feature
SET_PRINT_STATS_INFO_BASE: Renamed builtin of 'SET_PRINT_STATS_INFO'
SET_RETRACTION: Set firmware retraction parameters
SET_STEPPER_ENABLE: Enable/disable individual stepper by name
SET_VELOCITY_LIMIT: Set printer velocity limits
SHUTDOWN : Powers off the klipper host.
SIMPLE_PURGE_LINE: Implements the standard purge line on the left side of the bed.
START_PRINT: G-Code macro
STATUS : Report the printer status
STEPPER_BUZZ: Oscillate a given stepper to help id it
SWAP_FILAMENT: Change filament.
Usage: SWAP_FILAMENT [EXTRUDER_TEMP=] [BED_TEMP=] [X=] [Y=] [Z=]
Parameters:
- [EXTRUDER_TEMP] Temperature of the extruder for purging filament, by default 180°C.
- [BED_TEMP] Temperature of the bed for purging filament, by default 0°C.
- [X] X position for filament change
- [Y] Y position for filament change
- [Z] Z relative lift for filament change position
SWAP_RESUME: Resume a print after swapping filament.
SYNC_EXTRUDER_MOTION: Set extruder stepper motion queue
SYNC_STEPPER_TO_EXTRUDER: Set extruder stepper
TEMPERATURE_WAIT: Wait for a temperature on a sensor
TEST_BATTERIES_INCLUDED: A test macro to show that the script is working
TUNING_TOWER: Tool to adjust a parameter at each Z height
TURN_OFF_HEATERS: Turn off all heaters
UNLOAD_FILAMENT: Unload filament from the active extruder.
Usage: UNLOAD_FILAMENT EXTRUDER_TEMP=
Parameters:
- [EXTRUDER_TEMP] Temperature of the extruder for unloading filament
UPDATE_DELAYED_GCODE: Update the duration of a delayed_gcode
Z_OFFSET_APPLY_PROBE: Adjust the probe's z_offset
My own macros are the ones with more than one sentence as descriptions. I intentionally did not add more documentation (even though I want to), so I can still scroll through all commands.
The output in its current state is fine, but it will take a while to scroll through all of them and with multiline descriptions, it is easy to miss a command. For example here:
CALIBRATE_MPC: Calibrate MPC for the specified heater.
Usage: CALIBRATE_MPC HEATER=extruder Z=1.0
Parameters:
- [HEATER] The heater to calibrate, by default the extruder.
- [Z] How close the nozzle should be to the bed for calibration.
CALIBRATE_PID: Calibrate PID for extruder and bed.
Usage: CALIBRATE_PID EXTRUDER_TEMP=215 BED_TEMP=60
Parameters:
- [EXTRUDER_TEMP] The temperature of the extruder when calibrating.
- [BED_TEMP] The temperature of the bed when calibrating.
CALIBRATE_PRESSURE_ADVANCE: Print calibration pattern for pressure advance value.
one might overlook the CALIBRATE_PID command, because there isn’t any spacing between the descriptions.
Users who install random macros from “somewhere on the internet” without knowing why or what they do aren’t going to read documentation
Well, I am one of those people who install random macros like KAMP or klippain from somewhere on the internet. Like, why should you redo all the work that other people already did for you? This feature is obviously not for those who have no clue what they are doing or refuse to read documentation.
On Linux (and Windows, more like any operating system) it is the standard to provide some mechanism to get the usage documentation conveniently in the terminal. I do not want to open a browser window and search for docs every time I forget what some flag was called. Most people can not remember all the different ways a command can be used, or what the exact name of some command line flag was. For example, this is the help command for git:
âžś ~ git --help
usage: git [--version] [--help] [-C <path>] [-c <name>=<value>]
[--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
[-p | --paginate | -P | --no-pager] [--no-replace-objects] [--bare]
[--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
[--super-prefix=<path>] [--config-env=<name>=<envvar>]
<command> [<args>]
These are common Git commands used in various situations:
start a working area (see also: git help tutorial)
clone Clone a repository into a new directory
init Create an empty Git repository or reinitialize an existing one
work on the current change (see also: git help everyday)
add Add file contents to the index
mv Move or rename a file, a directory, or a symlink
restore Restore working tree files
rm Remove files from the working tree and from the index
examine the history and state (see also: git help revisions)
bisect Use binary search to find the commit that introduced a bug
diff Show changes between commits, commit and working tree, etc
grep Print lines matching a pattern
log Show commit logs
show Show various types of objects
status Show the working tree status
grow, mark and tweak your common history
branch List, create, or delete branches
commit Record changes to the repository
merge Join two or more development histories together
rebase Reapply commits on top of another base tip
reset Reset current HEAD to the specified state
switch Switch branches
tag Create, list, delete or verify a tag object signed with GPG
collaborate (see also: git help workflows)
fetch Download objects and refs from another repository
pull Fetch from and integrate with another repository or a local branch
push Update remote refs along with associated objects
'git help -a' and 'git help -g' list available subcommands and some
concept guides. See 'git help <command>' or 'git help <concept>'
to read about a specific subcommand or concept.
See 'git help git' for an overview of the system.
For most programs, you can find all the necessary documentation through their help commands and don’t have to look up their help pages: Git - git Documentation. I think this is very convenient, and I do not understand why a similar convenience should not exist in klipper.
And if macro authors aren’t already providing usage instructions, it’s not because of a lack of a dedicated mechanism. The existing description field is well suited for providing usage instructions if the author so desires.
Because of the lack of a dedicated mechanism, many document their macros not in the description field, but on their github page or as a comment in the source code:
Most of the bigger macro repos do provide usage instructions, but they end up in places that are suboptimal for macro users. The description field seems to be intended as a short description of what the command does in a single line and dedicated documentation is supposed to be somewhere else (like for the built-in klipper commands).
