[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
> 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 

> 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.
Bacula-devel mailing list

This mailing list archive is a service of Copilot Consulting.