Re: [fossil-users] incomplete documentation?

[Isaac Jurado]

El 09/08/2013 14:18, "Richard Hipp"  escribió:
>
>
>
> On Fri, Aug 9, 2013 at 7:40 AM, Isaac Jurado  wrote:
>>
>> As I understand it, in Fossil, the history is mostly driven by the date
>> and time of the events, whereas in Git and Hg ancestry relationship
>> comes first.  I gues this is one of the reasons of why there typical
>> "log" command is called "timeline" in Fossil; and also why hiding the
>> possibility of altering the commit time, because it would lead to a
>> confusing timeline graph.
>>
>> When I converted an Hg repo that had its history reordered (with "hg
>> histedit"), the resulting Fossil timeline had an arrow pointing
>> downwards which made it look a bit weird.
>
>
> The timeline display in Fossil is date driven.  But the underlying
repository uses ancestry relationships, just like Git and Mercurial.

Sure, I didn't mean otherwise.  What I was trying to explain is that when
using Git or Mercurial one is under the impression that commit dates are
just informative.  However, Fossil's timeline pays more attention to dates.

Of course, all systems properly record ancestry relationships.

> When you have a parent that is younger than its child, we call that a
"time-warp" and it results in a funky backwards arrow on the timeline
display. See http://www.sqlite.org/src/timeline?c=3f30f00a384d&nd for an
example.  Timewarps can be caused, for example, when commits occur on a
system were the system clock is set to the wrong time.
>
> When doing a sync, Fossil compares timestamps on the local and remote
machines and issues a warning if they are misaligned.  The whole point of
that warning is to try to prevent timewarps.
>
> You can get a list of all timewarps in a project by visiting the
/test_timewarps page in the web interface.  There were several timewarps in
the SQLite history (as seen at http://www.sqlite.org/src/test_timewarps)
but most of them have been fixed by adding tags to check-ins that "correct"
their check-in time.  The
http://www.sqlite.org/src/info/cbfe6e9df3check-in, for example, had an
original check-in time of 2009-08-20 09:11:06
but this was adjusted to 2009-08-20 16:11:06 for display purposes using a
tag, specifically the http://www.sqlite.org/src/info/14cc3387df tag.
>
> You could, in theory, generate timewarps in Git too, since each check-in
has a timestamp, iirc.  Does anybody know what would happen on the GitHub
timeline graph for a Git repository that contains a timewarp?

I can't speak for git, but in Mercurial when examinig the history graph the
dates are secondary. Therefore, time warps are not highligthted and it's up
to the user to check.

Thanks for the other information.
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] incomplete documentation?

[Stephan Beal]

On Fri, Aug 9, 2013 at 1:36 PM, j. van den hoff
wrote:

> fossil --user joedoe ci filename
>
> fossil ci --user joedoe filename
>
> the second version looks "normal" in that `ci' apparently takes a `--user'
> option plus argument. the first one is the "problem" for the `fsl'
> wrapper since it of course cannot (and should not need to) mimic the
> complete command line parsing of `fossil' in order to get it correctly
> interpreted.


A side-note on WHY that happens, for those who are interested... when
find_option() is used to fetch a flag, the caller has to tell it the name
of the flag and whether or not that flag expects a value. The the above
case the name would be "user" and it does expect a value. So fossil starts
looking through g.argv (an array of strings) to find the option. If it
does, it _removes_ it from g.argv (and decrements g.argc: the count of
items in g.argv). If the argument expects a value, it also removes the
_next_ entry from g.argv and decrements g.argc. So after calling that,
fossil effectively has fewer arguments than it had before, which means that
the command can then simply look at g.argc to figure out if the user passed
in the right number of arguments (for many cases, anyway, though some
require more advanced logic).

Anyway... i found those details highly interesting when i started work on
the JSON API. At first the update-g.argv behaviour annoyed me (on a
philosophical level), but now that i understand why it works that way, i'm
good with it.


> bottom line: I really would be grateful if someone could clarify whether
>
> fossil COMMAND ?args and files?
>
> is actually the only "valid" syntax for command line usage (ignoring the
> `--args FILENAME' way of feeding `fossil' commands from a file)
> and that things like
>
> fossil --user joedoe ci filename
>
> are not guaranteed to work/should be avoided?
>

The current code can't make such a guaranty. It can guaranty that the above
two variants are functionally equivalent, but ONLY if the specific command
handler does its argument/flag checks in such a way that makes them
equivalent. i.e. the commands which do all flag-checking up front, before
examining other arguments will treat the above as equivalent because the
flag-checking filters out g.argv for their later processing.

In case you don't know about it, there's another seldom-used feature which
potentially adds even more confusion/combinations to your examples: the
--args FILENAME option, which basically replaces the (--args FILENAME) args
with the contents of the given filename:

http://fossil-scm.org/index.html/artifact/952d72d35e5ab9ea4815d68e7820d9deae701433?ln=357-366

-- 
- stephan beal
http://wanderinghorse.net/home/stephan/
http://gplus.to/sgbeal
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] incomplete documentation?

[Richard Hipp]

On Fri, Aug 9, 2013 at 7:40 AM, Isaac Jurado  wrote:

> As I understand it, in Fossil, the history is mostly driven by the date
> and time of the events, whereas in Git and Hg ancestry relationship
> comes first.  I gues this is one of the reasons of why there typical
> "log" command is called "timeline" in Fossil; and also why hiding the
> possibility of altering the commit time, because it would lead to a
> confusing timeline graph.
>
> When I converted an Hg repo that had its history reordered (with "hg
> histedit"), the resulting Fossil timeline had an arrow pointing
> downwards which made it look a bit weird.
>

The timeline display in Fossil is date driven.  But the underlying
repository uses ancestry relationships, just like Git and Mercurial.

When you have a parent that is younger than its child, we call that a
"time-warp" and it results in a funky backwards arrow on the timeline
display. See http://www.sqlite.org/src/timeline?c=3f30f00a384d&nd for an
example.  Timewarps can be caused, for example, when commits occur on a
system were the system clock is set to the wrong time.

When doing a sync, Fossil compares timestamps on the local and remote
machines and issues a warning if they are misaligned.  The whole point of
that warning is to try to prevent timewarps.

You can get a list of all timewarps in a project by visiting the
/test_timewarps page in the web interface.  There were several timewarps in
the SQLite history (as seen at http://www.sqlite.org/src/test_timewarps)
but most of them have been fixed by adding tags to check-ins that "correct"
their check-in time.  The
http://www.sqlite.org/src/info/cbfe6e9df3check-in, for example, had an
original check-in time of 2009-08-20 09:11:06
but this was adjusted to 2009-08-20 16:11:06 for display purposes using a
tag, specifically the http://www.sqlite.org/src/info/14cc3387df tag.

You could, in theory, generate timewarps in Git too, since each check-in
has a timestamp, iirc.  Does anybody know what would happen on the GitHub
timeline graph for a Git repository that contains a timewarp?
-- 
D. Richard Hipp
d...@sqlite.org
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] incomplete documentation?

[Isaac Jurado]

Replying j. van den hoff:
> as a follow up on this (and the response to the original post by drh):
>
> it _is_ bad that options like `--date-override' are not
> comprehensively documented (notably with `commit') since they can be
> important for "normal" users as well. e.g.:
>
> accidentally, I'm just now in the somewhat painful process of
> extracting a subset of files (and their revision history) from a
> rather big/old/messy `hg' repository. the usual route would be to
> use `hg convert' plus a filemap specification to generate a new `hg'
> repository containing only the desired stuff then the rest would be
> easy (hg -> git -> fsl). alas! this strategy does not allow to
> "flatten" the directory tree (in the old repo the files are "way
> down" in some subdir, in the new one they should be at the
> toplevel). retrospective `mv' actions than lead to problems
> with diffing across the renames in fossil (at least this seems to be
> the situation?). there where more problems with renames in the `hg'
> repo not being handled too good in the whole conversion process -- at
> least I could not achieve a satisfactory fossil repo in the end.

I know it is a bit off-topic, but I have a small branch that enhances
the fossil import code a bit.  My motivation was the same: I wanted to
convert some Hg repos via Git but wanted to preserve renames.

In the end I also added an option to generate delta manifests in Fossil,
which reduces the total artifact size (as reported by "dbstat").

The problem is that I haven't found the time to configure a spare
hosting of mine to publish it.  Sending the whole patch set by e-mail
would be rather tedious.  I should have done it a few weeks ago but the
lack of time and motivation just delayed it indefinitely.  If you are
interested on testing, I can find a spot to upload it this weekend.

> so what I did is I wrote a shell script collecting all relevant
> revisions in the `hg' repo, updating in turn to each revision and
> committing the `hg' working copy files to the new `fossil' repo
> directly. and here is the catch: _only_ when using the --date-override
> flag (and knowing that it is there is a prerequisite...) this can work
> sanely by extracting the date from the `hg log' and inserting it
> correctly during the `fossil ci' (instead of ending up with 100
> commits within 10 seconds...)
>
> just wanted to support julian in his opinion, that fossil's CL help
> should strive to be complete. so, please augment information like the
> one in question here if your time allows for this. I believe the user
> base would appreciate this.

As I understand it, in Fossil, the history is mostly driven by the date
and time of the events, whereas in Git and Hg ancestry relationship
comes first.  I gues this is one of the reasons of why there typical
"log" command is called "timeline" in Fossil; and also why hiding the
possibility of altering the commit time, because it would lead to a
confusing timeline graph.

When I converted an Hg repo that had its history reordered (with "hg
histedit"), the resulting Fossil timeline had an arrow pointing
downwards which made it look a bit weird.

Best regards.

-- 
Isaac Jurado

"The noblest pleasure is the joy of understanding."
  Leonardo da Vinci
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] incomplete documentation?

[j. van den hoff]

coming back to this (the question whether or not there are `fossil'  
options like `--user'). my interest in this question is related to this  
project


http://fossil.0branch.com/fsl

where the wrapper script `fsl' which can be used as a transparent drop-in  
replacement for the `fossil' command (and makes live with fossil on the  
command line much easier: alias mechanism, output filtering etc.) of  
course needs to know the syntax accepted by `fossil' on the command line:


by try and error (no documentation whatsoever...) I found out that both  
these commands work:


fossil --user joedoe ci filename

fossil ci --user joedoe filename

the second version looks "normal" in that `ci' apparently takes a `--user'  
option plus argument. the first one is the "problem" for the `fsl'
wrapper since it of course cannot (and should not need to) mimic the  
complete command line parsing of `fossil' in order to get it correctly  
interpreted. so this wrapper (and any other, I'd say) relies on the  
assumption that the command line syntax is the one stated by `fossil' when  
called without args


fossil COMMAND ...

so that the wrapper can take action depending on the identified COMMAND  
(being on position one of the list of arguments).


bottom line: I really would be grateful if someone could clarify whether

fossil COMMAND ?args and files?

is actually the only "valid" syntax for command line usage (ignoring the  
`--args FILENAME' way of feeding `fossil' commands from a file)

and that things like

fossil --user joedoe ci filename

are not guaranteed to work/should be avoided?

thanks in advance
joerg


On Thu, 08 Aug 2013 17:00:08 +0200, Stephan Beal   
wrote:



On Thu, Aug 8, 2013 at 2:32 PM, Stestagg  wrote:

I would agree here, it's not at all clear.  Even when you know there is  
a

--user option, then the fossil output isn't clear:



In Fossil's defense: i've been using Fossil almost daily since Christmas
2007 and haven't every used --user.

steves@sapphire ~> f --user foo

fossil: fossil: unknown command: --user
fossil: use "help" for more information



IIRC, only commands which use user details (e.g. a commit or tag)
allow/user a user override option. Most locally-run commands don't care  
who

you are.



# So the first argument must be the command?

steves@sapphire ~> f --user foo ls
fossil: current directory is not within an open checkout



Unfortunately, that depends on the exact command :/. Side effects of the
argument resolution process change (potentially) in what order some code
must be run. i don't recall off-hand whether the top-level command
dispatcher skips over --flags, but i don't see how it could because it
cannot generically know if the token after a -flag is the value for the
flag or if it is a command (unless it looks up the argument in its  
command

table).

i'm not in any way discounting your arguments that the help could be
clearer/more intuitive in places, but some of the current behaviours are
side effects of old design decisions which cannot simply be swapped out.

Feel free to propose new/improved help texts :).




--
Using Opera's revolutionary email client: http://www.opera.com/mail/
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] incomplete documentation?

[j. van den hoff]

as a follow up on this (and the response to the original post by drh):

it _is_ bad that options like `--date-override' are not comprehensively  
documented (notably with `commit') since they can be important for  
"normal" users as well. e.g.:


accidentally, I'm just now in the somewhat painful process of extracting a  
subset of files (and their revision history) from a rather big/old/messy  
`hg' repository. the usual route would be to use `hg convert' plus a  
filemap specification to generate a new `hg' repository containing only  
the desired stuff then the rest would be easy (hg -> git -> fsl). alas!  
this strategy does not allow to "flatten" the directory tree (in the old  
repo the files are "way down" in some subdir, in the new one they should  
be at the toplevel). retrospective `mv' actions than lead to problems
with diffing across the renames in fossil (at least this seems to be the  
situation?). there where more problems with renames in the `hg' repo
not being handled too good in the whole conversion process -- at least I  
could not achieve a satisfactory fossil repo in the end.


so what I did is I wrote a shell script collecting all relevant revisions  
in the `hg' repo, updating in turn to each revision and committing the  
`hg' working copy files to the new `fossil' repo directly. and here is the  
catch: _only_ when using the --date-override flag (and knowing that it is  
there is a prerequisite...) this can work sanely by extracting the date  
from the `hg log' and inserting it correctly during the `fossil ci'  
(instead of ending up with 100 commits within 10 seconds...)


just wanted to support julian in his opinion, that fossil's CL help should  
strive to be complete. so, please augment information like the
one in question here if your time allows for this. I believe the user base  
would appreciate this.


j.

On Thu, 08 Aug 2013 18:40:46 +0200, Julian  wrote:

One of the problems is that the help given by fossil help   
isn't always complete. For example the help for checkin (fossil help  
ci), doesn't list the --date-override or --user-override options, even  
though they appear to be accepted. The same appears to be the case for  
the branch command.


The only way I've found to discover them is to use "grep find_option" on  
the source - I'm not sure that is very user-friendly.



___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users



--
Using Opera's revolutionary email client: http://www.opera.com/mail/
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] incomplete documentation?

[j. van den hoff]

On Thu, 08 Aug 2013 19:49:18 +0200, Richard Hipp  wrote:


On Thu, Aug 8, 2013 at 12:40 PM, Julian  wrote:

One of the problems is that the help given by fossil help   
isn't
always complete. For example the help for checkin (fossil help ci),  
doesn't

list the --date-override or --user-override options, even though they
appear to be accepted. The same appears to be the case for the branch
command.

The only way I've found to discover them is to use "grep find_option" on
the source - I'm not sure that is very user-friendly.



Two reasons for this.

(1) The help text is intended for quick reference and so we don't want to
clutter it up with lots of text describing obscure and rarely used  
options.


I would politely disagree: the CL help should be complete, I believe.
at least for everything not considered experimental or "secret developer  
features".


while git sure is over the top in this regard simply because there are too  
much
options (I had a good laugh once when first looking at `git help log'), a  
very positive
example for me is `hg': it's about as concise as `fossil' but complete as  
far

as I can tell.

I know it is work and takes time and the current help is OK but sure
its not as complete as it should be in my view.

j.



(2) Some options we don't want people to use, either because they are
dangerous and likely to lead to problems, or because they are  
experimental

and subject to change and perhaps untested, or perhaps the options are
deprecated and are still recognized purely for backwards compatibility.

The --date-override and --user-override options were put in place to
support scripts used to import Fossil content from other repository
formats.  Both reasons (1) and (2) above apply to these options.





--
Using Opera's revolutionary email client: http://www.opera.com/mail/
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] incomplete documentation?

[Richard Hipp]

On Thu, Aug 8, 2013 at 12:40 PM, Julian  wrote:

> One of the problems is that the help given by fossil help  isn't
> always complete. For example the help for checkin (fossil help ci), doesn't
> list the --date-override or --user-override options, even though they
> appear to be accepted. The same appears to be the case for the branch
> command.
>
> The only way I've found to discover them is to use "grep find_option" on
> the source - I'm not sure that is very user-friendly.
>

Two reasons for this.

(1) The help text is intended for quick reference and so we don't want to
clutter it up with lots of text describing obscure and rarely used options.

(2) Some options we don't want people to use, either because they are
dangerous and likely to lead to problems, or because they are experimental
and subject to change and perhaps untested, or perhaps the options are
deprecated and are still recognized purely for backwards compatibility.

The --date-override and --user-override options were put in place to
support scripts used to import Fossil content from other repository
formats.  Both reasons (1) and (2) above apply to these options.


-- 
D. Richard Hipp
d...@sqlite.org
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] incomplete documentation?

[Stephan Beal]

On Thu, Aug 8, 2013 at 6:40 PM, Julian  wrote:

> The only way I've found to discover them is to use "grep find_option" on
> the source - I'm not sure that is very user-friendly.
>

It is for fossil's original intended audience ;). But, yeah, i admit that
it's not ideal.

Tell you what: look around here:

http://fossil-scm.org/index.html/help

write up some text for the parts you want added/amended, and i'll get it
committed.

(That applies to all of you, not just Julian!)

-- 
- stephan beal
http://wanderinghorse.net/home/stephan/
http://gplus.to/sgbeal
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] incomplete documentation?

[Julian]

One of the problems is that the help given by fossil help  isn't 
always complete. For example the help for checkin (fossil help ci), doesn't 
list the --date-override or --user-override options, even though they appear to 
be accepted. The same appears to be the case for the branch command. 

The only way I've found to discover them is to use "grep find_option" on the 
source - I'm not sure that is very user-friendly.


___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] incomplete documentation?

[Stephan Beal]

On Thu, Aug 8, 2013 at 5:13 PM, j. van den hoff
wrote:

> well that's sort of difficult for the average user I'd say since he does
> not _know_
> what the parser is doing and what the set of valid calls to fossil looks
> like. I cannot be sure,
> for instance that there are no further undocumented `--word' options
> beside `--user' ...
>

lol! touché. i often forget that not everyone who uses fossil hacks on it
:/.

fossil ?fossil_option(s)? COMMAND ?command_option(s)?
>

Because it would be a lie sometimes :/. The ordering of the flags and
commands may or may not be important for a given command. _Normally_ it
doesn't matter where the flags appear but it can if the one who implements
that command isn't aware of the side-effects that argument parsing has on
the list of arguments (as i wasn't when i started work on the JSON API).

As a rule of thumb, the following syntax should work just about everywhere
(if not everywhere):

fossil command ?options?

where ?options? can be command-specific or (quasi-)global (like -R).

looking over the current output now:

stephan@tiny:~/cvs/fossil/f2$ f help
Usage: f help COMMAND
...

i wouldn't expect ?options? to appear there, but that's probably a matter
of personal taste (and mine is often in the minority ;). In your opinion,
what should the top-level 'help' command say which it does not already?

If we then go one level deeper for a specific command:

stephan@tiny:~/cvs/fossil/f2$ f help ls
Usage: f ls ?OPTIONS? ?VERSION? ?FILENAMES?
...

that one has, IMO, pretty good help. There are certainly others which could
be improved, but i don't have an example off the top of my head. But i did
just discover the 'cat' command - i don't think i knew about that one
before now.


but more formally, it looks to me that it would be better to eliminate
> `fossil_options' altogether and add them as command_options
> to the respective command(s). that would make for a clearer and less
> unusual syntax overall. would that be difficult?


In general that's what currently happens, e.g.:

stephan@tiny:~/cvs/fossil/f2$ f help cat
Usage: f cat FILENAME ... ?OPTIONS?
...
Options:
   -R|--repository FILE   Extract artifacts from repository FILE

-R is one of those quasi-global options which is supported almost
everywhere, but not all of the commands explicitly mention it (possibly the
author of the command doesn't even realize it because it happens one level
removed from his command).

http://fossil-scm.org/index.html/artifact/0adc1aa79c24d8bc88b32e2ef7a8f29d32619d79?ln=1055

i don't personally hold out much hope of any groundbreaking changes in
fossil's help system because it's literally integrated with the source code
(the help text and command/page names are extracted from source code
comments during the build process) and it works relatively well (and is
very non-intrusive on the developers). That said, FWIW, i will certainly
take your points to heart when libfossil[1] is far enough along that
applications can be built off of it. My plan is to provide a skeleton CLI
app mini-framework which does the bootstrap part of handling the -R flag,
seeing if $PWD is part of a checkout, processing CLI flags, and exposing
the CLI flags to the application in a higher-level form. That's still
likely several months away, but maybe it'll give you some hope for a more
consistent help system in future fossil-related products :).


[1] http://fossil.wanderinghorse.net/repos/f2/

-- 
- stephan beal
http://wanderinghorse.net/home/stephan/
http://gplus.to/sgbeal
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] incomplete documentation?

[j. van den hoff]

On Thu, 08 Aug 2013 17:00:08 +0200, Stephan Beal   
wrote:



On Thu, Aug 8, 2013 at 2:32 PM, Stestagg  wrote:

I would agree here, it's not at all clear.  Even when you know there is  
a

--user option, then the fossil output isn't clear:



In Fossil's defense: i've been using Fossil almost daily since Christmas
2007 and haven't every used --user.


there was no attack so there need not be any defense ;-)



steves@sapphire ~> f --user foo

fossil: fossil: unknown command: --user
fossil: use "help" for more information



IIRC, only commands which use user details (e.g. a commit or tag)
allow/user a user override option. Most locally-run commands don't care  
who

you are.



# So the first argument must be the command?

steves@sapphire ~> f --user foo ls
fossil: current directory is not within an open checkout



Unfortunately, that depends on the exact command :/. Side effects of the
argument resolution process change (potentially) in what order some code
must be run. i don't recall off-hand whether the top-level command
dispatcher skips over --flags, but i don't see how it could because it
cannot generically know if the token after a -flag is the value for the
flag or if it is a command (unless it looks up the argument in its  
command

table).

i'm not in any way discounting your arguments that the help could be
clearer/more intuitive in places, but some of the current behaviours are
side effects of old design decisions which cannot simply be swapped out.

Feel free to propose new/improved help texts :).


well that's sort of difficult for the average user I'd say since he does  
not _know_
what the parser is doing and what the set of valid calls to fossil looks  
like. I cannot be sure,
for instance that there are no further undocumented `--word' options  
beside `--user' ...


what about extending the output of `fossil help' by giving the most  
general syntax like


fossil ?fossil_option(s)? COMMAND ?command_option(s)?

(or whatever is correct) and listing the `fossil_options' here together  
with the list
of valid commands with which they can be combined? if it only relates to  
`--user' this should be more or less easy

for the people in the know (not me...).

but more formally, it looks to me that it would be better to eliminate  
`fossil_options' altogether and add them as command_options
to the respective command(s). that would make for a clearer and less  
unusual syntax overall. would that be difficult?


j.






--
Using Opera's revolutionary email client: http://www.opera.com/mail/
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] incomplete documentation?

[Stephan Beal]

On Thu, Aug 8, 2013 at 2:32 PM, Stestagg  wrote:

> I would agree here, it's not at all clear.  Even when you know there is a
> --user option, then the fossil output isn't clear:
>

In Fossil's defense: i've been using Fossil almost daily since Christmas
2007 and haven't every used --user.

steves@sapphire ~> f --user foo
> fossil: fossil: unknown command: --user
> fossil: use "help" for more information
>

IIRC, only commands which use user details (e.g. a commit or tag)
allow/user a user override option. Most locally-run commands don't care who
you are.


> # So the first argument must be the command?
>
> steves@sapphire ~> f --user foo ls
> fossil: current directory is not within an open checkout
>

Unfortunately, that depends on the exact command :/. Side effects of the
argument resolution process change (potentially) in what order some code
must be run. i don't recall off-hand whether the top-level command
dispatcher skips over --flags, but i don't see how it could because it
cannot generically know if the token after a -flag is the value for the
flag or if it is a command (unless it looks up the argument in its command
table).

i'm not in any way discounting your arguments that the help could be
clearer/more intuitive in places, but some of the current behaviours are
side effects of old design decisions which cannot simply be swapped out.

Feel free to propose new/improved help texts :).

-- 
- stephan beal
http://wanderinghorse.net/home/stephan/
http://gplus.to/sgbeal
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] incomplete documentation?

[Stestagg]

I would agree here, it's not at all clear.  Even when you know there is a
--user option, then the fossil output isn't clear:

steves@sapphire ~> f ls
fossil: current directory is not within an open checkout

# OK

steves@sapphire ~> f --user foo
fossil: fossil: unknown command: --user
fossil: use "help" for more information

# So the first argument must be the command?

steves@sapphire ~> f --user foo ls
fossil: current directory is not within an open checkout

# No, it accepts user, maybe it accepts anything..

steves@sapphire ~> f --bar foo ls
fossil: fossil: unknown command: --bar
fossil: use "help" for more information

# No, ok, so let's see the help:

steves@sapphire ~> f --help
Usage: fossil help COMMAND
Common COMMANDs:  (use "fossil help --all" for a complete list)
add changes finfo   merge   revert  tag
addremove   clean   gdiff   mv  rm  timeline
all clone   helpopensettingsui
annotatecommit  import  pullsqlite3 undo
bisect  diffinfopushstash   update
branch  export  initrebuild status  version
cat extras  ls  remote-url  sync
This is fossil version 1.25 [d2e07756d9] 2013-02-16 00:04:35 UTC

No mention.. what about fossil help user .. no, that's something else..

The same thing happens with -R, I believe

Thanks

Steve





On Thu, Aug 8, 2013 at 1:27 PM, j. van den hoff
wrote:

> On Thu, 08 Aug 2013 14:03:42 +0200, Stephan Beal 
> wrote:
>
>  On Thu, Aug 8, 2013 at 1:38 PM, j. van den hoff
>> **wrote:
>>
>>  question: should there not be a help page for fossil itself, maybe
>>> (`fossil help fossil') which explains this sort of things?
>>>
>>
>>
>> Is this perhaps what you're looking for:
>>
>> [stephan@host:~]$ f help help
>> Usage: f help COMMAND
>>or: f COMMAND -help
>>
>> Display information on how to use COMMAND.  To display a list of
>> available commands one of:
>>
>>f help  Show common commands
>>f help --a|-all Show both common and auxiliary commands
>>f help --t|-testShow test commands only
>>f help --x|-aux Show auxiliary commands only
>>f help --w|-www Show list of WWW pages
>>
>>
>> ?
>>
>
> no: `fossil --user joedoe ci' has the form
>
> fossil fossil_option COMMAND COMMAND_option
>
> so the possibility of having a option for fossil itself is not explained
> in the help. or what am I missing? what I mean is, in my understanding the
> terminology is COMMAND is one of the keywords (without leading dashes)
> displayed by `fossil help -a' while `--user' is not a COMMAND but rather an
> option (but not of one of the COMMANDS but of `fossil' itself.
>
>
>
>>
>
> --
> Using Opera's revolutionary email client: http://www.opera.com/mail/
> __**_
> fossil-users mailing list
> fossil-users@lists.fossil-scm.**org 
> http://lists.fossil-scm.org:**8080/cgi-bin/mailman/listinfo/**fossil-users
>
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] incomplete documentation?

[j. van den hoff]

On Thu, 08 Aug 2013 14:03:42 +0200, Stephan Beal   
wrote:



On Thu, Aug 8, 2013 at 1:38 PM, j. van den hoff
wrote:


question: should there not be a help page for fossil itself, maybe
(`fossil help fossil') which explains this sort of things?



Is this perhaps what you're looking for:

[stephan@host:~]$ f help help
Usage: f help COMMAND
   or: f COMMAND -help

Display information on how to use COMMAND.  To display a list of
available commands one of:

   f help  Show common commands
   f help --a|-all Show both common and auxiliary commands
   f help --t|-testShow test commands only
   f help --x|-aux Show auxiliary commands only
   f help --w|-www Show list of WWW pages


?


no: `fossil --user joedoe ci' has the form

fossil fossil_option COMMAND COMMAND_option

so the possibility of having a option for fossil itself is not explained  
in the help. or what am I missing? what I mean is, in my understanding the  
terminology is COMMAND is one of the keywords (without leading dashes)  
displayed by `fossil help -a' while `--user' is not a COMMAND but rather  
an option (but not of one of the COMMANDS but of `fossil' itself.







--
Using Opera's revolutionary email client: http://www.opera.com/mail/
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users

Re: [fossil-users] incomplete documentation?

[Stephan Beal]

On Thu, Aug 8, 2013 at 1:38 PM, j. van den hoff
wrote:

> question: should there not be a help page for fossil itself, maybe
> (`fossil help fossil') which explains this sort of things?


Is this perhaps what you're looking for:

[stephan@host:~]$ f help help
Usage: f help COMMAND
   or: f COMMAND -help

Display information on how to use COMMAND.  To display a list of
available commands one of:

   f help  Show common commands
   f help --a|-all Show both common and auxiliary commands
   f help --t|-testShow test commands only
   f help --x|-aux Show auxiliary commands only
   f help --w|-www Show list of WWW pages


?

-- 
- stephan beal
http://wanderinghorse.net/home/stephan/
http://gplus.to/sgbeal
___
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users