On Wednesday 06 February 2008 21.46:11 John Stoffel wrote: > >>>>> "Kern" == Kern Sibbald <[EMAIL PROTECTED]> writes: > >> > >> More of a joke, but I'll ask anyway: have you considered a messages and > >> codes manual? I know I'm being old-fashioned and mainframe-y and all > >> that , but it'd be really helpful to be able to look up a message and > >> know what component it related to and maybe some reasons that would > >> cause that message. I don't see anywhere obvious in this structure where > >> I'd look for that kind of information. It'd be a real help to the > >> translators too, I'd bet. > > Kern> Yes, I have considered a messages and codes manual, and in the > Kern> beginning all the messages had unique code numbers. Again, the > Kern> problem is the work required to implement it, and particularly > Kern> to keep it up to date as messages are added and changed. No > Kern> doubt it would be good to have such a manual, and probably one > Kern> day it will exist. > > Kern> In any case, I am beginning to work on an entirely new manual > Kern> that will serve as the first part of a training course as I > Kern> think it is something critical for promoting Bacula within > Kern> enterprises ...
Well, the command code started off terribly simple, and is not well documented because in general all commands prompt the user for input. Later I added command line arguments to simplify scripting for the regression tests, and over time the whole thing grew enormously. Had I realized in the beginning that it would evolve as much as it did, I would have made commands table driven as is the case for the conf file. That said, it would require a good bit of design to implement a table driven structure for the Bacula console because of the need to support both command line options and prompting when all the necessary options are not present -- getting it right so that the user is prompted for only the minimum required information is not so trivial. Currently, rewriting the code will not add any extra functionality so it is extremely low on my priority list. However, if you or someone else would like to take a stab at it, OK, but I am not convinced it will be worth the pain. Although most of the command line options are documented, it is far from being the most complete part of the Bacula documentation. Consequently, something that could be very useful to Bacula users would be to improve the command line documentation and assure that it is complete. Also, there is little or no documentation on the command prompts -- mainly because it is relatively easy to use and "self-documenting" so any effort there would be a big improvement. > > >From looking at the source code to 2.2.8, I find it hard to find all > > the various commands, especially .<command> versions and what > arguements they take. > > Maybe it's time to think about centralizing all the definitions of > commands and such so that it's easier to manage and find and document > them properly. Unless the code is rewritten to be table driven, I'm not much in favor of centralizing all the commands. At one point I did that for the SQL commands, and in the end, although most of them are in one file, it is now *much* harder to modify the code because the code and the SQL commands are separated. > > I also find it annoying that when using bconsole it doesn't give back > useful error messages if you get a command wrong, it just spouts back > "Missing arguements" or other vague messages. It currently does not detect command line arguments that are not necessary or are misspelled (they are just ignored), but in 99% of all cases, it should prompt you for what you want. If not the exceptions should be pointed out so we can fix them. > > And since you can't do anything like '<command> ?' inside bconsole to > show you what args the command takes, it's even more frustrating at > times. Specific nested help would be a nice addition ... > > I've been looking at the 2.2.8 code today to try and figure out all > the .<command> and how they work, and having them scattered all over > the place is just frustrating. Yes, it makes programming and fixing bugs much easier but documentation harder. > > Maybe it's time people sat down and came up with the definitions of > the commands and their arguements and what they produce for output and > errors, and *then* implement them? > > I know, I've said before that I'd like to writeup a 'bcli' which would > show the commands as I think they should be organized. So I'll shutup > now and start putting my nose to the grindstone and coming up with > examples. I'll be interested to see what you come up with. > > Anyone else interested in helping out? PS: a few nights ago, a plugin injected a file into the Bacula backup which I was able to restore, so the API framework for supporting things like an Exchange plugin is beginning to take shape ... ------------------------------------------------------------------------- This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/ _______________________________________________ Bacula-users mailing list Bacula-users@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/bacula-users
