src.elv.sh@v0.21.0-dev.0.20240515223629-06979efb9a2a/pkg/mods/doc/doc.d.elv (about)

     1  # Shows documentation for `$symbol` in the terminal.
     2  #
     3  # If `$symbol` starts with `$`, it is treated as a variable. Otherwise it is
     4  # treated as a function.
     5  #
     6  # Symbols in a module should be specified using a qualified name as if the
     7  # module is imported without renaming, like `doc:source`. Symbols in the builtin
     8  # module can be specified either in the unqualified form (like `put`) or with
     9  # the explicit `builtin:` namespace (like `builtin:put`).
    10  #
    11  # The `&width` option specifies the width to wrap the output to. If it is 0 (the
    12  # default) or negative, `show` queries the terminal width of the standard output
    13  # and use it as the width, falling back to 80 if the query fails (for example
    14  # when the standard output is not a terminal).
    15  #
    16  # This command is roughly equivalent to `md:show &width=$width (doc:show
    17  # $symbol)`, but has some extra processing of relative links to point them to
    18  # the Elvish website.
    19  #
    20  # Examples:
    21  #
    22  # ```elvish-transcript
    23  # ~> doc:show put
    24  # [ omitted ]
    25  # ~> doc:show builtin:put
    26  # [ omitted ]
    27  # ~> doc:show '$paths'
    28  # [ omitted ]
    29  # ~> doc:show doc:show
    30  # [ omitted ]
    31  # ```
    32  #
    33  # See also [`md:show`]().
    34  fn show {|symbol &width=0| }
    35  
    36  # Finds symbols whose documentation contains all strings in `$queries`.
    37  #
    38  # The search is done on a version of the documentation with no markup and soft
    39  # line breaks converted to spaces. For example, if the Markdown source of a
    40  # symbol contains `foo *bar* [link](dest.html)`, with possible soft line breaks
    41  # in between, it will be matched by a query of `foo bar link`.
    42  #
    43  # The output shows each symbol that matches, followed by an excerpt of their
    44  # documentation with the matched queries highlighted.
    45  #
    46  # Examples:
    47  #
    48  # ```elvish-transcript
    49  # ~> doc:find namespace
    50  # ns:
    51  #   Constructs a namespace from $map, using the keys as variable names and the values as their values. …
    52  # has-env:
    53  #   … This command has no equivalent operation using the E: namespace (but see https://b.elv.sh/1026).
    54  # eval:
    55  #   … The evaluation happens in a new, restricted namespace, whose initial set of variables can be specified by the &ns option. …
    56  # [ … more output omitted … ]
    57  # ~> doc:find namespace REPL
    58  # edit:add-var:
    59  #   Defines a new variable in the interactive REPL with an initial value. …
    60  #   This is most useful for modules to modify the REPL namespace. …
    61  # ```
    62  fn find {|@queries| }
    63  
    64  # Outputs the Markdown source of the documentation for `$symbol` as a string
    65  # value. The `$symbol` arguments follows the same format as
    66  # [`doc:show`]().
    67  #
    68  # Examples:
    69  #
    70  # ```elvish-transcript
    71  # ~> doc:source put
    72  # ▶ "... omitted "
    73  # ```
    74  fn source {|symbol| }