Re: Should @shortcontents come before @contents with CONTENTS_OUTPUT_LOCATION=after_top?

[Patrice Dumas]

On Sat, Mar 11, 2023 at 12:01:18PM +0100, Arsen Arsenović wrote:
> Hi,
> 
> Currently, CONTENTS_OUTPUT_LOCATION=after_top outputs contents first,
> then shortcontents, as is written in HTML.pm:4113.  Some manuals, such
> as that of GCC, place @shortcontents first, in order to let the user
> browse a briefer high-level overview before jumping into the (quite
> large) table of contents.

I think that the best would be, after having decided on a default, to
have the alternative order specified in CONTENTS_OUTPUT_LOCATION.  So,
for example if it is shortcontents first and contents next in the
default case, there would be both CONTENTS_OUTPUT_LOCATION=after_top
and CONTENTS_OUTPUT_LOCATION=after_top_short_last to be able to specify
that.

> Do you think this rationale makes sense, and should we output
> @shortcontents first with after_top?

If we do it with after_top, it should be the same with the other similar
possibilities for CONTENTS_OUTPUT_LOCATION.  So, both with after_title
and separate_element the defaut order should be the same.

>  Alternatively, maybe we could
> record the relative location of the contents commands in the document
> and base ordering on that?

That seems too complex and fragile to me, also using
CONTENTS_OUTPUT_LOCATION=inline should do ok if the manual author wants
to have a specific relative location of @shortcontents and @contents.


Personnally I do not have a preference on the default.  I do not
remember why contents is before shortcontents, it is likely that it
dates back to the perl rewrite in 2012, unless it was changed when
OUTPUT_CONTENTS_LOCATION was added.  It may also have come from what
makeinfo in C did before that.

-- 
Pat