[MERGE][0.17] ReST section dividers

[John Arbash Meinel]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Alexander Belchenko wrote:
> Aaron Bentley ?8H5B:
>> Alexander Belchenko wrote:
> 
>> -- locality of reference: If an operation requires data that is located
>> +
>> +- locality of reference:
>> +
>> +   If an operation requires data that is located
>>     within a small region at any point, we often get better performance
>>     than with an implementation of the same operation that requires the
>>     same amount of data but with a lower locality of reference. Its
> 
>> ^^^^^^^ I'm not sure this is a correct edit.
> 
> You want to have this in one block? No problem. In this case it should be:
> 
> - locality of reference: If an operation requires data that is located
>   within a small region at any point, we often get better performance
>   than with an implementation of the same operation that requires the
>   same amount of data but with a lower locality of reference. Its
>   fairly tricky to add locality of reference after the fact, so I think
>   its worth considering up front.
> 
> Is this OK for you?
> 
>> === renamed file doc/developers/revert.txt // doc/developers/revert.rst
> 
>> ^^^^^^^ We should probably decide what extension to us for our rst
>> files, but at present either .txt or .rst is being used.
> 
> If files is included to another document, I'd prefer to use .rst,
> because otherwise it also automatically converted to html,
> but such html is not used (there is no link to such html).
> 
>> === modified file doc/developers/bundle-creation.rst
>> --- doc/developers/bundle-creation.rst
>> +++ doc/developers/bundle-creation.rst
>> @@ -1,5 +1,5 @@
>>  Bundle Creation
>> -===============
>> +---------------
> 
>> ^^^^^^^^^^ we probably also need to standardize our heading order, since
>> ReST doesn't.  But I find it counterintuitive for "===" to be less
>> significant than "---".
> 
> Because currently there is a mix between different styles in included rst files,
> I used majority of cases to re-indent other files. (I'm agree with you about
> === should be greater than ---, but I follow Robert initial implementation).
> 
> Also I've adding this comment to main file (performance-roadmap.txt):
> 
> .. Please, use ``.rst`` extension for included files
> .. Mark sections in included files as following:
> ..   level 1 --------
> ..   level 2 ========
> ..   level 3 ++++++++
> ..   level 4 ^^^^^^^^
> 
> [µ]


I've always done it this way:

==========
Main Title
==========

Section
=======

Subsection
- ----------

Subsubsection
~~~~~~~~~~~~~

And I've never really felt the need to go deeper. (I feel it is probably a
problem with documentation if you need much more nesting than that).


I do think we should standardize on them.

I agree with Aaron that I feel "==" is more important than "--". Probably
because it is "heavier".

I also prefer the horizontal characters (= - ~) to the blockier ones (+ # ^),
but I'm willing to compromise.

This is the sort of thing that is very easy to bike-shed on, so I think we just
need a "declaration from above" from Martin as to which to use, and then just
stick with it.

John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (Darwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFGZCoOJdeBCYSNAAMRArgvAJ9VllKLQWOF1SgfWaZBbvCT9633RQCgxjhl
pGrv8MdBrRev42v/iaieq44=
=o7I5
-----END PGP SIGNATURE-----