From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Chad Brown Newsgroups: gmane.emacs.devel Subject: Re: What have the Romans done for us? (Bazaar) Date: Tue, 6 Apr 2010 10:02:56 -0700 Message-ID: References: <20100405145637.GA3248@muc.de> <87mxxhhq3b.fsf@red-bean.com> <20100406143144.GB3551@muc.de> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 (Apple Message framework v1078) Content-Type: multipart/alternative; boundary=Apple-Mail-15-208400519 X-Trace: dough.gmane.org 1270573393 21395 80.91.229.12 (6 Apr 2010 17:03:13 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Tue, 6 Apr 2010 17:03:13 +0000 (UTC) Cc: emacs-devel@gnu.org To: Alan Mackenzie Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Apr 06 19:03:12 2010 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1NzCBD-000368-8P for ged-emacs-devel@m.gmane.org; Tue, 06 Apr 2010 19:03:11 +0200 Original-Received: from localhost ([127.0.0.1]:56608 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1NzCBC-0005rM-Oe for ged-emacs-devel@m.gmane.org; Tue, 06 Apr 2010 13:03:10 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1NzCB8-0005rD-4B for emacs-devel@gnu.org; Tue, 06 Apr 2010 13:03:06 -0400 Original-Received: from [140.186.70.92] (port=59919 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1NzCB5-0005r5-NP for emacs-devel@gnu.org; Tue, 06 Apr 2010 13:03:04 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1NzCB3-0006H8-Gq for emacs-devel@gnu.org; Tue, 06 Apr 2010 13:03:03 -0400 Original-Received: from dmz-mailsec-scanner-6.mit.edu ([18.7.68.35]:57510) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1NzCB3-0006Gy-ET for emacs-devel@gnu.org; Tue, 06 Apr 2010 13:03:01 -0400 X-AuditID: 12074423-b7c0bae0000030f0-42-4bbb6944c56d Original-Received: from mailhub-auth-1.mit.edu (MAILHUB-AUTH-1.MIT.EDU [18.9.21.35]) by dmz-mailsec-scanner-6.mit.edu (Symantec Brightmail Gateway) with SMTP id 9B.DC.12528.4496BBB4; Tue, 6 Apr 2010 13:03:00 -0400 (EDT) Original-Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103]) by mailhub-auth-1.mit.edu (8.13.8/8.9.2) with ESMTP id o36H30XS029493; Tue, 6 Apr 2010 13:03:00 -0400 Original-Received: from [10.0.1.6] (c-98-247-149-76.hsd1.wa.comcast.net [98.247.149.76]) (authenticated bits=0) (User authenticated as yandros@ATHENA.MIT.EDU) by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id o36H2u8U017162 (version=TLSv1/SSLv3 cipher=AES128-SHA bits=128 verify=NOT); Tue, 6 Apr 2010 13:02:59 -0400 (EDT) In-Reply-To: <20100406143144.GB3551@muc.de> X-Mailer: Apple Mail (2.1078) X-Brightmail-Tracker: AAAAAA== X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:123274 Archived-At: --Apple-Mail-15-208400519 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset=us-ascii On Apr 6, 2010, at 7:31 AM, Alan Mackenzie wrote: > >> ? http://doc.bazaar.canonical.com/en/ points to plenty of downloadable >> documentation, in HTML, CHM, and PDF formats. > > They all lack hyperlinks or are non-searchable. (BTW, I'll need to find > out what CHM is). It's an acronym for `Compiled Help file (Microsoft)' -- does that tell you everything you need to know? :-) It's a format used to make HTML help file bundles for MS's `help viewer'. You almost certainly don't care. > But worst of all is the low quality of the reference > docs. For example, 'bzr help merge' doesn't say with any specificity > what is being merged or where the result is written. It talks about > "merging a branch", which makes as much sense as "the difference between > a file" does. This vagueness is prevalent over much or all of 'bzr help > '. Is it too much to expect these man pages (in effect) to be > precise? I don't disagree at all, but you might find it helpful to spend an hour or so digging through http://wiki.bazaar.canonical.com/BzrGlossary/ In general, the docs seem to assume that you're either already familiar with vcs concepts and are just looking for the bzr keywords, or that you don't care at all and are just looking for the right set of magic words to say to avoid angering the wizards. I suspect that the aim to cater to as many different `methodologies' (what we've been calling workflows on this list) has encouraged a doc style that's so detail-agnostic that it's hard to ever find useful content. I hope that helps, *Chad --Apple-Mail-15-208400519 Content-Transfer-Encoding: quoted-printable Content-Type: text/html; charset=us-ascii

?  http://doc.bazaar.canonical.c= om/en/ points to plenty of downloadable
documentation, in HTML, CHM, and PDF = formats.

They all lack hyperlinks or are = non-searchable.  (BTW, I'll need to find
out what CHM is). =

It's an acronym for `Compiled = Help file (Microsoft)' -- does that tell you 
everything = you need to know? :-)

It's a format used to = make HTML help file bundles for MS's `help viewer'.
You almost = certainly don't care.

 But = worst of all is the low quality of the reference
docs.  For = example, 'bzr help merge' doesn't say with any specificity
what is = being merged or where the result is written.  It talks = about
"merging a branch", which makes as much sense as "the = difference between
a file" does.  This vagueness is prevalent = over much or all of 'bzr help
<cmd>'.  Is it too much to = expect these man pages (in effect) to = be
precise?

I don't disagree at = all, but you might find it helpful to spend an hour or = so
digging through


In general, the = docs seem to assume that you're either already familiar = with
vcs concepts and are just looking for the bzr keywords, = or that you don't 
care at all and are just looking for = the right set of magic words to say to 
avoid angering = the wizards.  I suspect that the aim to cater to as = many 
different `methodologies' (what we've been calling = workflows on this list) 
has encouraged a doc style = that's so detail-agnostic that it's hard to ever 
find = useful content.

I hope that = helps,
*Chad
= --Apple-Mail-15-208400519--