From e5b9401bf35a26ba1a00426875a18f2588ef2b99 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 17 Nov 2025 12:44:41 +1300 Subject: [PATCH] documenting.rst: Command line rendering --- .../extending_yosys/documenting.rst | 60 +++++++++++-------- 1 file changed, 35 insertions(+), 25 deletions(-) diff --git a/docs/source/yosys_internals/extending_yosys/documenting.rst b/docs/source/yosys_internals/extending_yosys/documenting.rst index c0f51f637..7038b61d9 100644 --- a/docs/source/yosys_internals/extending_yosys/documenting.rst +++ b/docs/source/yosys_internals/extending_yosys/documenting.rst @@ -66,22 +66,22 @@ indicate mutually exclusive arguments. The ``Pass::help()`` method ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This is the original way to provide help text, and as of this writing is still -the most common. The ``log()`` function should be called directly to print and -format the help text, and each line should be limited to 80 (printed) -characters. While it is possible to provide arbitrary formatting, it is -preferred to follow the guidelines here to maintain consistency with other +Overriding this method is the original way to provide help text, and as of this +writing is still the most common. The ``log()`` function should be called +directly to print and format the help text, and each line should be limited to +80 (printed) characters. While it is possible to provide arbitrary formatting, +it is preferred to follow the guidelines here to maintain consistency with other passes and to assist in correct parsing and formatting during RST generation (i.e. these docs). -The first line should always be a blank line, followed by the primary usage -signature for the command. Each usage signature should be indented with 4 -spaces, and followed by a blank line. Each option or flag should start on a new -line indented with 4 spaces, followed by a description of the option which is -indented by a further 4 spaces, and then a blank line. Option descriptions -typically start with lower case, and may forgo a trailing period (``.``). Where -multiple options share a description the blank line between options should be -omitted. +The first and last lines should always be blank (usually ``log("\n");``), +followed by the primary usage signature for the command. Each usage signature +should be indented with 4 spaces, and followed by a blank line. Each option or +flag should start on a new line indented with 4 spaces, followed by a +description of the option which is indented by a further 4 spaces, and then a +blank line. Option descriptions typically start with lower case, and may forgo a +trailing period (``.``). Where multiple options share a description the blank +line between options should be omitted. .. note:: @@ -203,24 +203,34 @@ highlighting). Command line rendering ~~~~~~~~~~~~~~~~~~~~~~ -- if ``Pass::formatted_help()`` returns true, will call - ``PrettyHelp::log_help()`` +Rendering text for the command line is done by the ``Pass::help`` method. When +this method is not overridden, the default behavior is to call +``Pass::formatted_help()``. If this method is also left unimplemented, or the +return value is explicitly false, then a default message about missing help text +for the command is displayed. Returning true, however, will then call +``PrettyHelp::log_help()`` to convert the formatted help content into plain +text. - + traverse over the children of the root node and render as plain text - + effectively the reverse of converting unformatted ``Pass::help()`` text - + lines are broken at 80 characters while maintaining indentation (controlled - by ``MAX_LINE_LEN`` in :file:`kernel/log_help.cc`) - + each line is broken into words separated by spaces, if a given word starts - and ends with backticks they will be stripped +Rendering rich help text as plain text is done by traversing over all the +``ContentListing`` nodes and printing the body text. ``usage`` nodes are +preceded by an empty line and indented one level (4 spaces). ``option`` nodes +are also indented one level, while their children are indented an extra level (8 +spaces). Each section of body text is broken into words separated by spaces. +If a word would cause the line to exceed 80 characters (controlled by +``MAX_LINE_LEN`` in :file:`kernel/log_help.cc`), then the word will instead be +placed on a new line, with the same level of indentation. -- if it returns false it will call ``Pass::help()`` which should call ``log()`` - directly to print and format help text +Special handling is included for words that begin and end with a backtick +(`````) so that these are stripped when printing to the command line. Compare +:ref:`chformal_help` below with the :ref:`chformal autocmd` above. The content +is still the same, but for the command line it uses a fixed width. - + if ``Pass::help()`` is not overridden then a default message about missing - help will be displayed +.. todo:: spaces in backticks (``assert(...)`` vs ````assert(s_eventually ...)````) .. literalinclude:: /generated/chformal.log :lines: 2- + :name: chformal_help + :caption: Command line output for `help chformal` Cell help