GNOME Bugzilla – Bug 418541
[PATCH] man pages for beagle commands
Last modified: 2007-03-21 19:59:25 UTC
Several beagle commands are missing man-pages (see Ubuntu bug at https://launchpad.net/ubuntu/+source/beagle/+bug/89358) I've put together some very basic man pages for the following commands: beagle-doc-extractor beagle-dump-index beagle-exercise-file-system beagle-extract-content beagle-imlogviewer beagle-index-info beagle-index-url beagle-info beagle-ping beagle-search beagle-settings These are based mainly on the information from running the commands with --help, plus bits and pieces from the net. I am right in thinking that there is no more complete beagle documentation anywhere, right? Likely things wrong with these: - I've not even tried to give a full description of what each command does; since there is hardly any beagle documentation, I can't give a decent description without diving into the source code. So all you get is a one-line summary and the command-line options (copied from --help) - I'm not sure what you want the copyright notices to be. - I'm just attaching these as a tarball. I figure it's a 5-minute job for one of you to dump them in the right place, much longer for me to figure out your build system and make a patch - I couldn't find much/any documentation on beagle-imlogviewer, beagle-exercise-file-system, or beagle-doc-extractor, so the man pages are particularly sparse. I don't know what your long-term documentation plan is for beagle, but I may have time to chip in some more in the future. Let me know!
Created attachment 84638 [details] man pages for various beagle commands
These are fantastic starts, thanks a lot! I'm going to make a couple of tweaks and check them in. I'm going to remove beagle-exercise-file-system altogether, because it's a tool we don't use at all anymore. Most of the documentation we have is up on the wiki. We could always use more in the form of user documentation, programmer documentation, and community outreach and marketing info. So please feel free to help out in any way. For many of us developers who are "close" to the project, it's difficult for us to see the big picture as an outsider. So anywhere where you see deficiencies I'd like to know, even if you're unable to contribute to fixing them directly.
Thanks Joe for taking care of this and thanks Daniel for getting started on this. Writing html is way easier that those man pages :-), so I spend most of my documentation effort in the wiki. Just for note, what is beagle-index-url ? I dont think it is used anymore. The code can be left or moved to attic and the script removed. Do we also want to install beagle-index-info and beagle-ping scripts - they are mere wrappers to beagle-info ?
(In reply to comment #3) > Just for note, what is beagle-index-url ? I dont think it is used anymore. The > code can be left or moved to attic and the script removed. It is a program to send data to the indexing service backend. It was used by the Firefox extension. I believe it is still used by the Epiphany extension. > Do we also want to install beagle-index-info and beagle-ping scripts - they are > mere wrappers to beagle-info ? Yeah, I dunno. I don't see any harm in it, and people are likely to do "man beagle-index-info".
Thanks Joe and Debajyoti for replying so promptly! I don't see much use in the beagle-info-index and beagle-ping scripts unless they are used by other parts of beagle. If they are installed, they should have a man page, but getting rid of them altogether sounds sensible. RE: documentation generally. Online documentation is both easier to write than man-pages, and likely to get used more, so it's probably best to keep concentrating on the web pages. The online docs you have are pretty scattered, though. I'd suggest putting up a central Documentation page on the wiki (maybe as a replacement for/expansion of Getting Started), with ordered, annotated links to the documentation you already have. Once we have the man pages in a usable state, it might also be worth running them through an html converter and adding them to the wiki.
Just checked these in, r3595. http://svn.gnome.org/viewcvs/beagle?rev=3595&view=rev