Abusing HELP with 'literals?

Domains Help System
1

Following on from adding help #some-topic in Abusing help with tags? I was wondering about adding literals like help 'bugs ??

At the moment HELP with literals doesn't provide much enlightenment...

>> help 'bugs
'bugs is a lit-word

I was wondering we could hijack literals do same thing as (in this example) the BUGS function currently does?

My thinking is that all these HELP functions (except UPGRADE, but also add in DOCS) could be converted to HELP literals?...

 Other information:

      about - see general product info
      bugs - open GitHub issues website
      changes - show changelog
      chat - open GitHub developer forum
      install - install (when applicable)
      license - show user license
      topics - open help topics website
      upgrade - check for newer versions
      usage - program cmd line options

Then i add console shortcut for each one (so no need for functions as they are all console related).

Thoughts on above? I believe by adding this I can also do some additional refactoring on the code in mezz-help.r

2

Rebol is an internet language, and I think we should off load as much to shared repositories on the basis of many hands make light work and not too many cooks spoil the broth !

3

Make sense to move as much as possible to web.

On the above list (ignoring UPRADE & INSTALL?) all open in a web browser except:

ABOUT, LICENSE and USAGE

ABOUT has to remain local but we could move LICENSE & USAGE to web (though i recommend we use version numbering on URL link).

This does bring up the problem of opening a web browser in a non GUI setting (for eg. SSH to remote server). You could call some text browser like Lynx but ideally I think we would need to build in a small Rebol text "web-browser" (**) which we can fallback on when no external browser can be found or set.

** Not a full blown "web-browser" par se :slight_smile: Just one that can render structured info from our own web pages for HELP but not for CHAT and alike!

4

That's the issue with adding in spiffy graphics, and CSS etc., when you then have to deal with text based browsers.

If we want to do this, I suggest we think carefully how we are going to structure the text if we're going to have to add a markdown parser to the mix!

5

Agree.

BTW - Is your reboldocs pulled from some docs/website or generated directly from Rebol/Ren-C source code or introspection?

6

It's generated by introspection. Below the line comments are added manually.
The idea was that the script would run periodically to update with new words, changed definitions etc, and the manual edits would be retained.

However, that hasn't happened yet, so it's frozen at the creation date.

1 Like
7

Excellent stuff!

This is definitely the way forward and I'm sure we can even find a way to add line comments one day (may need a special document comment literal).

So just need to devise & add documentation specification to OBJECT! & MODULES! :slight_smile:

Thinking back to literals I'm wondering if HELP literal should be used for module help?

>> help 'altxml
!! This module has not been imported

>> import 'altxml
== make module! [...]

>> help 'altxml
... doc for altxml...

Thoughts?

8

I found the script [helpdocs]((https://github.com/gchiu/Rebol3/blob/master/scripts/helpdocs.reb) and just posted it. Still needs some love.

For instance

>> help/docs default
** Script Error: default does not allow path! for its target argument

So, currently, we have

help words eg. help help
help #issue eg. help #compile
source <tag> eg. source <webform>

I"m not certain we need a third format, literals for help.

9

We do need to add module documentation and then we need a way to call/render it.

So help 'module-name is one suggestion. help/module module-name is another? But we could use something else instead of HELP ??

You may also have some external documentation tool, which would look thru module-path and render module documentation. An example:

$ redoc -m altxml
... shows doc for altxml module ...

$ redoc -f print
... shows doc for PRINT function ...

PS. The link for helpdocs is empty :frowning:

10

Oh yeah. Help is only for core functions.

@rgchris uses a Home header to provide a URL to link to that describes the module.
Would that work for you?

11

Yes I think that could be very handy. As an example this could work like this:

>> import <webform>

>>  help/module-home rgchris.webform   ;; thats the module Name:
Opening browser at http://www.ross-gill.com/page/Web_Forms_and_REBOL

But I still see a place for something like this as well:

>> help/module rgchris.webform      

TITLE:
    Web Form Encoder/Decoder for Rebol 3

AUTHOR:
    Christopher Ross-Gill

VERSION:
    0.10.3 (6-Sep-2015)

PURPOSE:
    Convert a Rebol block to a URL-Encoded Web Form string

EXPORTS:
    URL-DECODE
        Decode percent-encoded text from URLs and Web Forms

    URL-ENCODE
        Encode text using percent-encoding for URLs and Web Forms

    LOAD-WEBFORM
        Loads data from a URL-Encoded Web Form string

    TO-WEBFORM
        Serializes block data as URL-Encoded Web Form string

EXAMPLE:
    load-webform "a=3&aa.a=1&b.c=1&b.c=2"
    [a "3" aa [a "1"] b [c ["1" "2"]]]
12

Sounds good. Want to implement?

13

It's on my (ever growing Rebol todo) list :slight_smile:

1 Like