Re: func.sgml

Andrew Dunstan <andrew(at)dunslane(dot)net> writes:
> Tom noted:
>> You have to be very careful these days when applying stale patches to
>> func.sgml --- there's enough duplicate boilerplate that "patch' can easily
>> be fooled into dumping an addition into the wrong place.

> This is yet another indication to me that there's probably a good case
> for breaking func.sgml up into sections. It is by a very large margin
> the biggest file in our document sources (the next largest is less than
> half the number of lines).

What are you envisioning ... a file per <sect1>, or something else?

I'm not sure that a split-up would really fix the problem I mentioned;
but at least it'd reduce the scope for things to go into *completely*
the wrong place.

I think to make things safer for "patch", we'd have to give up a lot
of vertical space around function-table entries. For example,
instead of

<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>num_nonnulls</primary>
</indexterm>
<function>num_nonnulls</function> ( <literal>VARIADIC</literal> <type>"any"</type> )
<returnvalue>integer</returnvalue>
...
</para></entry>
</row>

maybe

<row><entry role="func_table_entry"><para role="func_signature">
<indexterm><primary>num_nonnulls</primary></indexterm>
<function>num_nonnulls</function> ( <literal>VARIADIC</literal> <type>"any"</type> )
<returnvalue>integer</returnvalue>
...
</para></entry></row>

In this way, there'd be something at least a little bit unique within
the first couple of lines of an entry, so that the standard amount of
context in a diff would provide some genuine indication of where a
new entry is supposed to go.

The main problem with this formatting is that I'm not sure that
anybody's editors' SGML modes would be on board with it.

regards, tom lane