> > Well, that can also be fine, and better then para, > > because it is actually a list, and not a para, as > > it can be seen :)) The second one is better in > > "keys need to be typed" sense :) But, we have > > see also parts, where we have some functions and > > some parts refereced, and to express this, only > > the first one is appropriate. We also have see also > > parts without any functions, just part links... > > If I understand it correctly, see-also block is very simillar to > admonitions (note, warning, ...). So what about putting see-also inside > note > > <note role="seealso"> > ... > </note> > > Stylesheet can render it differently than note w/o role="seealso".
I can both be happy with a list type or a block type see also element. The question, is whether we would like to automate it the way, as we need not put commas and "and" words between elements (list type), or simply write out the contents much like a note (block). To be abstract, far away from actual implementation: <listtype> <element><function>seeone</function></element> <element><function>seetwo</function></element> <element><function>seeother</function></element> <element><link linkend="types">types</link></element> </listtype> <blocktype> <function>seeone</function>, <function>seetwo</function>, <function>seeother</function>, and <link linkend="types">types</link> </blocktype> With both rendered with "See also:" prepended to the text and commas, and "and" words added between elements. The first one is clearer, with the second one, you have less to type. Using <note role="seealso"> means using the second one. I can live with both. The second one is the easier to implement. As we choose one or the other, it will much likely will stay the same for a long time, as it is a big change in the docs... What the other people think here? Goba