Allow for Script documentation

[quintesse]

Some scripts are getting pretty complicated, more so than perhaps is easily handled by any --help options. So it would be nice to have a command like:

jbang docs alias@catalog

Possible options are to look for *.html, *.md or *.txt files with the same name as the script and open them up somehow.
We could also add a docs-url to the entries in a Catalog file and open that in a browser.

[maxandersen]

Should be independent of the catalog feature I would say.

Could support .adoc kinda natively as we can actually build .adoc somewhat automatic with a jbang script ;)

I kinda did a proof-of-concept of the value of .adoc and jbang scripts as .adoc can refer to lines in the script. Look at examples/tz.java and examples/tz.adoc.

But yeah, like the idea of having a default or prioritized search for docs for a script; possibly with a //DOCS <url> explicit option (not sure if that is even needed though)

[quintesse]

Should be independent of the catalog feature I would say.

You're right

[maxandersen]

not sure if overdoing it but asciidoctor supports generating man pages https://asciidoctor.org/docs/user-manual/#man-pages and picocli actually supports generating that https://picocli.info/#_generate_man_page_documentation ... maybe make the docs feature somehow check for these being present ...just a thought.

[andsel]

I think the developer's task should be defined.
If he provides an html file then jbang should just open the browser to point to that page, is responsibility of the developer to generate the html, writing it manually or generating from a markdown or asciidoc file. In this case the styling is on its own.
If instead he's asked to provide the markdown or asciidoc then is Jbang responsibility to generate an html (or a man page) and show it.

In the first case there isn't common styling across various tool's doc pages, while with the second the styling is uniformed across all Jbang scripts.

WDYT?

[quintesse]

Personally I'm not very worried about the type of document, the options you mention are all valid. It's more about the how. In JBang we can't have, or at least try not to have, files with special names. Instead we always explicitly mention each file that we want to use (there are some exceptions like allowing //FILES images/*, but even in those cases we advice against them because it will fail for remote scripts).

So should we introduce something like //DOCS script_docs.html?

[andsel]

So should we introduce something like //DOCS script_docs.html?

I think that would be a good starting point to provide this functionality, just drive the user to the html guide that the developer shaped for his script. Should be only one //DOCS tag per application pointing to an html file located in the folder of the script. Do you think it could be also a full URL to some website?

[quintesse]

We often allow "references" to be either local files or full URLs, I don't see a reason why we wouldn't do the same in this case.

Btw, these are just some of my ideas, we haven't heard from @maxandersen yet.

[maxandersen]

for some reason I keep thinking I left a comment here :)

for me a //DOCS <url> makes sense for scripts but equally should alias'es have a way to associate docs with them.

Maybe have it be jbang info docs <scriptref> and also have it included in jbang info tools ?

Examples of things that would work:

//DOCS https://myawesome.doc/acme.html
//DOCS readme.md

question is of course how to handle that you could have multiple of them. Maybe have it be like //REPOS that are key/value pairs where key is optional and respect the ordering?

[quintesse]

Maybe have it be like //REPOS that are key/value pairs where key is optional and respect the ordering?

We could do that, yes. Although I've never understood why Maven repos have keys, I've never seen them used for anything. So given that we could also simplify the //DOCS to a simple list.

[andsel]

question is of course how to handle that you could have multiple of them.

About the collision of multiple //DOCS tag in the same script. My question is "should be admitted"?
Which is the value in having multiple //DOCS in the same script?
I could thing that the first is the one to display, but use the next one if the first has some issues, like HTTP error in reaching the URL or the path to a local file points to a non existing file.
However, if the //DOCS point to a URL and the URL is temporarily not available, if the user issue multiple time the command:

jbang info docs <scriptref>

could result in displaying different files.

Could jbang info docs return an error if it identifies multiple //DOCS tags in the script?

[quintesse]

Which is the value in having multiple //DOCS in the same script?

Honestly, there probably isn't any real value. But we tend to be very lenient in what we allow. So we try not to give any errors. (eg. if you supply multiple //JAVA tags that really doesn't make any sense, but instead of giving an error we'll use the newest version)
So that means we either allow multiple ones and we do something useful with it or we just select one (first, last, whatever).

[andsel]

So that means we either allow multiple ones and we do something useful with it or we just select one

It also means that all files could be opened in an editor or browser, depending on the extension.

[andsel]

What should happen if the //DOCS tag is present and also an url in the alias ?