[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Bacula-devel] New manual format
On Wednesday 06 February 2008 21.46:11 John Stoffel wrote:
> >>>>> "Kern" == Kern Sibbald <kern@xxxxxxxxxxx> 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
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
> >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
> 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
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
> 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
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.
Bacula-devel mailing list
This mailing list archive is a service of Copilot Consulting.