Melanie Plageman <melanieplage...@gmail.com> writes:
>> This is my first docs patch that introduces new sections and such, so
>> I'm not sure I got the indentation 100% correct (I, of course, tried
>> to follow conventions).
There really isn't much convention there :-(. The amount of
indentation used varies wildly across different chunks of our docs.
I'd try to make it look like nearby sections, but those might
themselves be inconsistent.
> Oh, one thing I forgot to say. Though I increased the indentation of
> some of the subsections that I moved, I didn't rewrap the lines
> because they were already not wrapped to 78. I can do this, but I
> can't tell from the existing docs what text width the paragraphs of
> text are supposed to be wrapped to.
If you're moving the text anyway, I'd rewrap it to something less than
80 columns. Again, there's not a lot of uniformity about exactly how
much less. I frequently use 74-column width for new docs text, to
leave some room for minor adjustments without having to rewrap;
but I don't think other people follow that rule.
A lot of the existing violations of 80-column right margin come from
when we switched to XML rules and had to fill out abbreviated closing
tags ("</>") to full tags ("</foo>"). That was done with some more or
less automated conversion that didn't do anything about rewrapping
lines that it made too long. I think that choice was fine, because
it reduced the size of the diff. But if you're rewriting or moving a
para, that's a good time to clean things up by rewrapping it; it'll
all be new according to "git blame" anyway.
regards, tom lane
