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
