[PATCH] help: add "glossary" topic

[Martin Geisler]

Faheem Mitha <faheem at email.unc.edu> writes:

Hi Faheem,

Thanks for being a great editor for this patch :-) Squirrel was at our
Zurich sprint and is called Mark Booth in real life.

> + +BRANCH
> +    (Noun) A child changeset that has been created from a parent that is
> +    not a head. These are known as topological branches, see 'Branch,
> +    topological'.If a topological branch is named, it becomes a named
> +    branch. If a topological branch is not named, it becomes an anonymous
> +    branch. See 'Branch, anonymous' and 'Branch, named'.  Branches may be
> +    created when changes are pulled from or pushed to a remote repository,
> +    since new heads may be created by these operations.  Note that the
> +    term branch can also be used informally to describe a development
> +    process in which certain development is done independently of other
> +    development.This is sometimes done explicitly with a named branch, but
> +    it can also be done locally, using bookmarks or clones and anonymous
> +    branches.

(blank)

> +    Example: "The experimental branch".

(blank)

> +    (Verb) The action of creating a child changeset which results in its
> +    parent having more than one child.

(blank)

> +    Example: "I'm going to branch at X".

Have you looked at this using 'hg help glossary'? You need blank lines
to separate the paragraphs, otherwise all the text in each definition
will be run together.

> +BRANCH, NAMED
> +    A collection of changesets which have the same branch name. By
> +    default, children of a changeset in a named branch belong to the same
> +    named branch. A child can be explicitly assigned to a different
> +    branch. See :hg:`help branch`, :hg:`help branches` and :hg:`commit`
> +    --close-branch for more information on managing branches.  Named

Should be :hg:`commit --close-branch` and I would probably also just
rever to :hg:`branch` and :hg:`branches` directly.

> + +DIFF
> +    (Noun) The difference between the contents and attributes of files in
> +    two changesets or a changeset and the current working directory. The
> +    difference is usually represented in a standard form called a "diff"
> +    or "patch". "git diff" is used when the changes include copies,

I don't like to start sentences with quotes and other such characters.
So what about

  or "patch". The "git diff" format is used...

> +HEAD
> +    The term Head may be used to refer to both a Branch head or a
> +    Repository head, depending on the context. See 'Head', branch and

I don't think the terms should be capitalized here.

> +PARENT, WORKING DIRECTORY
> +    The working directory reflects a virtual revision which is the child
> +    of the changeset (or two changesets with an uncommitted merge) shown
> +    by :hg:`parents`. You change this with :hg:`update`. Other commands to
> +    see the working directory parent are :hg:`summary` and :hg:`id`. Can
> +    be specified by the alias "." .

Extra space before the dot.

> + +REPOSITORY
> +    The metadata describing the state of a collection of files at
> +    different points in time. Each time point is represented by a
> +    changeset. A repository is usually (but not always) found in the `.hg`

Double the back-quotes here for literal text: ``.hg``.

-- 
Martin Geisler

See my Mercurial presentation: http://vimeo.com/11497288
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: not available
URL: <http://selenic.com/pipermail/mercurial-devel/attachments/20100615/a432dba3/attachment.pgp>