Re: Another modest proposal for docs formatting: catalog descriptions

Hello Tom,

>>> Here's a more fully fleshed out draft for this, with stylesheet
>>> markup to get extra space around the column type names.
>
>> I find this added spacing awkward, espacially as attribute names are
>> always one word anyway. I prefer the non spaced approach.
>
> It's certainly arguable that that look is too heavy-handed. In the
> attached, I knocked down the extra space from 1em to 0.25em, which
> makes it quite a bit subtler --- are you any happier with this?

Yes, definitely.

> BTW, I don't think it's very accurate that "attribute names are
> always one word" --- see the second attachment.

Indeed.

> Here if anything I'm wanting a little more space.

I'm fine with 0.25em which allows some breathing without looking awkward.
Maybe a little more would still be okay, but not much more.

>> If spacing is discussed, should the layout rather try to align type
>> information, eg:
>
> I thought about that, but it seems extremely close to some of the
> earlier function-table layouts that were so widely panned. The SGML
> source would have to be a lot uglier too, probably with explicit use
> of spanspec's on every row.

Hmmm, that's the kind of things I was afraid of.

> It could be done no doubt, but I think people would not see it as an
> improvement.

Possibly. I'm a little at odds with Type not being above types, but far on
the left, so that you cannot really "see" that it is about the format,
especially with long attribute names:

Column Type
Description
quite_a_long_attribute and_its_type
...

The horizontal distance between "Type" and "and_its_type" is so wide as to
hide the clue that the former is describing the later. But maybe aligning
would be too ugly.

If I can suggest more adjustements, maybe the description margin is a too
much, I'd propose reduce it to about 3 chars wide. Obviously any aesthetic
opinion is by definition subjective and prone to differ from one person to
the next…

--
Fabien.