Re: [Nmh-workers] Documenting @folder WAS Re: relative message numbers?

[Ralph Corderoy]

Hi David,

> > > Is `scan +/tmp/foo' documented anywhere, i.e. the ability to treat
> > > any directory as a folder, not just one under Path?  And address@hidden'
> > > after that..
> 
> How's this:
> 
>     Commands which take a folder name (inc, refile, scan, sortm, ...)

Three's enough?  "(inc, refile, scan...)"?

>     accept the folder name in two formats:  "+folder" or "@folder".
>     "+folder" specifies a folder underneath the Path defined in your
>     profile;  e.g., with the usual "Path: Mail", "+folder" tells nmh
>     to use "Mail/folder".

That's incorrect, corrected later.  Might be nicer to explain the warty
truth from the off.  How about

    Commands that take a folder name (inc, refile, scan...) accept the
    folder name in two formats:  "+folder" or "@folder".  In both cases,
    "folder" can be a "/"-separated path, e.g. "foo/bar".

    "+folder" specifies a directory path to a folder.  If "folder"
    starts with "/" then it's an absolute path from the root directory.
    If it is "." or "..", or starts with "./" or "../", then it's
    relative to the current working directory.  Otherwise it's relative
    to mh-profile(5)'s "Path", i.e. as given by `mhpath +'.

    "@folder" is a shorthand for "+curfolder/folder";  it's a relative
    path from the current folder.  "curfolder" is given by `mhpath'.

        scan +inbox       Scan $HOME/Mail/inbox assuming default Path.
        scan +work/todo   Scan $HOME/Mail/work/todo.
        scan @todo        Same if current folder is +work.
        refile @../done   $HOME/Mail/work/done if currently +work/todo.
        scan +/tmp        Scan /tmp.
        scan +.           Scan the current directory.
        refile @.         Refile current message to end of current folder.

> Lyndon, please let me know if I need to correct any formatting.

Having the examples indented would be nice.

> Also, I plan to change "+folder" to "+folder|@folder" in synopses.

How about [+|@]folder since many synopses are already wordy.

Cheers, Ralph.