Links to online help in command line help?

General Usage
1

Sometimes, the doc strings are too short:

help?> import
search: import export import_log isqrt ispow2 isperm insorted Cshort sort hypot

  import

  import Foo will load the module or package Foo. Names from the imported Foo
  module can be accessed with dot syntax (e.g. Foo.foo to access the name
  foo). See the manual section about modules for details.

julia>

The notation

import GLMakie as ma

for example is not mentioned at all. And the sentence “See manual section…” is missing a hyperlink.

Is it possible to add hyperlinks that work and keep working in the future to docstrings?

1 Like
2

There is a type of docstring that has double ??

Extended help is available with `??Threads.@threads`

Why need this? We are in command line environment.

3

Because the help string is referencing the manual. And the help string is insufficient. And there is no extended help for this command available.

1 Like
4

That is why in GMT I created the @? macro that automatically opens the extended (web) man page, when it exists ofc.

1 Like
5

Where is it defined? I could not find it in GMT.jl .

And how does it work, and how can it be used?

6

I’ll point to it tonight when I get back to my computer.

Found it. See
GMT.jl/src/common_options.jl at master · GenericMappingTools/GMT.jl

It works by opening a html man page in s browser.

1 Like
7

The @docs macro of the PkgOnlineHelp.jl package is designed for this purpose. By default, typing

julia> @docs SomePackage

will open your default browser to the package repository site. But you can customize it (only needs to be done once) so that typing the same thing takes you directly to the documentation of the package (or anywhere else you choose). For instance, I have mine set up so that

julia> @docs julia

opens the Julia language documentation.

Disclaimer: I am the author of PkgOnlineHelp.jl.

1 Like
8

I think documentation should be helpful. Adding a link to the “full” documentation is definitely helpful, and it’s also probably not that hard. Users shouldn’t have to search “the manual” (beginners may not even know where to find “the manual” itself) or use third-party macro packages to access documentation for the Julia language itself or its standard library.

The obvious response here is “if it’s not that hard, why don’t you submit a PR adding the links?”, and that’s probably the right thing to do…

2 Likes
9

I created an issue:

I think, using a package like PkgOnlineHelp.jl in the documentation of Base does not make sense.

1 Like