[MERGE] core_concepts documentation corrections

[Gary Wilson Jr.]

Ian Clatworthy wrote:
> Gary Wilson Jr. wrote:
>> This patch contains several minor changes to core_concepts docs:
>>
>> * Fixed a couple misspellings.
>> * Several punctuation, capitalization, and grammar fixes.
>> * Made all bulleted lists use a common indention.
>> * Corrected a reST link.
>> * Removed an extraneous sentence from branches section.
> 
> We should drop the punctuation at the end of simple list items I think.
> See below.

Ok, I think the only list here that meets the simple, continuation of the main 
clause's thought is the one in section 1.2.2 Revision.  I have dropped the 
ending punctuation for those list items.

>> I tried looking for some sort of style guidelines for the documentation,
>> but didn't find anything.  Are there any defined standards for the
>> documentation?  For example, I noticed that bulleted lists had
>> inconsistent indention.  On some, the bullet was in the first column of
>> the line, and others it was spaced over one or two spaces.
> 
> Good point. I don't think we have any. I'd like to propose that we
> follow the Python documentation style guidelines, which are based on the
> Apple ones. I've updated http://bazaar-vcs.org/ContributingToTheDocs
> accordingly.

Yikes, 196 pages!  Where's the CliffsNotes edition :)
For those interested, bulleted lists are mentioned on page 91.

> For bullet lists, this recommends that either full sentences should be
> used for each item or that no closing punctuation is used. For example:
> 
>  * This is a sentence.
>  * And this is another.
> 
> Simple list:
> 
>  * A sentence
>  * Another one

What about the indention of the lists?  The Apple Style Guide does not seem to 
be geared for plain text documentation.  In the Python documentation's 
reStructuredText Primer source [1], they put bullets in the first column of 
the line.  My patch does the same.

Gary

[1] http://docs.python.org/dev/_sources/documenting/rest.txt
-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: core_concepts.patch
Url: https://lists.ubuntu.com/archives/bazaar/attachments/20080403/7ee9709f/attachment-0001.diff