Re: Documentation of gb.args and gb.highlight - Gambas

[Bruce Steers <bsteers4@xxxxxxxxx>]

Your info on setting your own help text is wrong and makes duplicate output.

Your method produces this result...

MyApp - Image processing

Usage: gbx3 /path/to/project -- [options] [-- <args>]

Example: gbx3 $HOME/MyApp -- -m deep -r 0.5 -- img1.png img2.png

Options:
 -m --mode <MODE>          Processing mode (fast|normal|deep)
 -r --ratio <RATIO>        Compression ratio (default: 0.75)
 -f --force                Force processing
 -V --version              Display the version
 -h --help                 Display this help


Options:
 -m --mode <MODE>                       Processing mode (fast|normal|deep)
 -r --ratio <RATIO>                     Compression ratio
 -f --force                             Force processing without
confirmation
 -V --version                           Display version
 -h --help                              Display this help

The "Options" are shown twice.

Args.HelpText() was made for custom help. you should not cram it all in the
"usage" field of the Args.Begin() call.
The Args.HelpText() command returns what would normally be automatically
printed when using the -h (--help) arg so you can add your own text before
or after it.

see here...
https://gambaswiki.org/edit/comp/gb.args/args/helptext

The example should look more like this..

Public Sub Main()

  Dim sMode As String
  Dim fRatio As Float
  Dim bForce As Boolean
  Dim bHelp As Boolean
  Dim aArgs As String[]

  Args.Begin()

  sMode = Args.Get("m", "mode", "Processing mode (fast|normal|deep)",
"MODE")
  fRatio = Args.GetFloat("r", "ratio", "Compression ratio", "RATIO", 0.75)
  bForce = Args.Has("f", "force", "Force processing without confirmation")
  bHelp = Args.Has("h", "help", "show this help.")

  aArgs = Args.End()

  If bHelp Then ShowHelpText()

  Print "Mode: " & sMode
  Print "Ratio: " & fRatio
  Print "Force: " & bForce
  Print "Args: " & aArgs.Join(", ")

End

Private Function ShowHelpText()

  Print "MyApp - Image processing\n"  ' additional text before the arg list.
  Print Args.HelpText()
  ' any additional info can also be printed here.
  Quit

End

Both -V and -h can be overridden using Args.Has()
-V (--version) is overridden the same way as explained here..
https://gambaswiki.org/edit/comp/gb.args/args

If you use -V or -h with Args.Has() their default output is suppressed so
you can output your own text.


PS. for "See also" just add text like this..

### See also
[[ seealso
* [/doc/gb-args]
]]

Respects.
BruceS


On Thu, 30 Apr 2026 at 00:26, Olivier Cruilles <olivier.cruilles@xxxxxxxx>
wrote:

> Hi Benoit,
>
> I did the 2 first step: /doc + /topic but I don't find how to do the
> last point -> "See also"
>
> https://gambaswiki.org/edit/doc/gb-args
>
> https://gambaswiki.org/edit/doc/gb-highlight
>
> Olivier
>
>
>
> Le 29/04/2026 à 17:42, Benoît Minisini a écrit :
> > Le 29/04/2026 à 22:45, Olivier Cruilles a écrit :
> >> Hello everyone,
> >>
> >> I would like to share with you 2 little documentations regarding
> >> gb.args and gb.highlight component in Gambas.
> >>
> >> As the original documentations for both components were not enough to
> >> clearly use them (on my opinion), I decided to created two new little
> >> docs with more details.
> >>
> >> I have attached both of them docs in format Markdown Gambas (like
> >> that they could be added in the wiki of Gambas easily), and also both
> >> docs in HTML to show you what they are.
> >>
> >> Let me know if you find glitches or errors in those docs please.
> >>
> >>
> >> Now the question is where to place them into the Gambas Wiki, which
> >> section will be the best please ?
> >>
> >>
> >
> > You should put such documentation pages under the '/doc' url.
> >
> > Then update the '/topic' page which reference almosts all pages under
> > '/doc', but sorted by topics instead of the default alphabetic order.
> >
> > Then put reference on these pages in the "See also" section of the
> > corresponding components.
> >
> > Tell me if you have any problem with that.
> >
> > Regards,
> >
> --
> Olivier Cruilles
>
>
>