Re: Basic Bazaar guide for Emacs hackers.

[Karl Fogel]

Eli Zaretskii <address@hidden> writes:
>> Continued improvements to any of the docs welcome, of course.
>
> I fixed one or two factual inaccuracies and slightly improved wording
> in a couple of places.

Thank you!

> What's below are random stylistic and methodological comments.  Feel
> free to do anything you want with them, including nothing at all.
>
>  . The page is biased towards contributors who don't have write access
>    to the Emacs repository.  Notably, it gives almost all examples
>    using the HTPP URL, not the SFTP one.  Sometimes it mentions the
>    SFTP method, sometimes it does not.  It could be a better idea to
>    give both variants for each command.

Hmmm.  Good point -- I'll take a look and see what I can do.  If
anything, it should be biased toward SFTP and mention HTTP as an
alternate method.

>  . A Unix-like system is assumed without any notice to that effect.
>    Some commands will not work on Windows without subtle changes.  For
>    example,
>
>     echo "public_branch = http://bzr.savannah.gnu.org/r/emacs/trunk"; >> 
> .bzr/branch/branch.conf
>
>    will not do what you mean with the `echo' that it built into the
>    Windows shell.  Maybe someone could add footnotes with Windows
>    equivalents, where applicable (in this case, either remove the
>    quotes or use the ported GNU `echo').

Also a good point.  I haven't used Windows for almost 18 years now, so
I'll just put in notes that it's Unix-centric.

>  . The single-level sectioning is not the best one in this case,
>    because the page actually has 5 top-level sections, which I would
>    call Intro, Getting Started, One-Off Change, Feature Branch,
>    Resources; and some of these have sub-sections.  Presenting them as
>    a single-level document makes it harder to grasp the outline of the
>    narrative.  Suggest to have 2 levels of sections, not one.

I can do that (is there any reason you didn't just make the change,
though?).

>  . The "Overview of the Bazaar work routine" is too detailed, IMO, and
>    thus unnecessarily longish.  We will be explaining all the details
>    in a moment, so I think only the main points should be left in this
>    overview.

Will take a look and adjust accordingly.

>  . "Other Resources" should be at the beginning.  Someone who looks
>    for a CVS-like way of doing things should not be required to read
>    through such a long document to find the alternatives near the end.

I was already planning to move the "quick start" links to the beginning,
along with some explanation.  The other other resources can stay where
they are, I think.

Thanks for the review, Eli.

-K