Add list of figures, tables, code

[AlfredoRodrigues4]

I have noticed that there is no List of Figures or List of Tables (i.e. two separate lists after the List of Contents referencing and numbering all figures and tables, respectively), which would definitely be helpful for document searching. For comparison, most big chip designers use this. It can be seen on:

• Intel® 64 and IA-32 Architectures Software Developer’s Manual
• Qualcomm Hexagon V66 Programmer’s Reference Manual
• AMD64 Architecture Programmer’s Manual Volume 2: System Programming
• Synopsys Programmer’s Reference Manual for ARC EM Processors
• MIPS® Architecture for Programmers Volume II-A: The MIPS32® Instruction Set Manual

Therefore, I believe supporting quick index search in both Unprivileged and Privileged manuals is a great add-on.

[wmat]

We do have support in our docs toolchain. I'll add them, issue a PR and let the community decide if they add value.

[wmat]

@aswaterman what's your opinion on List of Figures and List of Tables. Note that only figures and tables with captions will be listed. In the Unprivileged spec many diagrams do not have captions. For example, this would be listed:

include::images/wavedrom/integer_computational.adoc[]
.Integer Computational Instructions

whereas, this would not.

include::images/wavedrom/integer_computational.adoc[]

The List of Tables/List of Figures asciidoctor extension need the caption to populate the list.

Should we add captions to all wavedrom/bytefield-svg diagrams such that they get picked of and added to a List of Figures?

[aswaterman]

I've never been a fan of lists of figures, since so many figures have little meaning outside the context in which they're located. Also, creating a table vs. using text to describe something is often an arbitrary choice, and so the list of figures ends up being fairly arbitrary as to what it includes. The table of contents ends up being a more useful device.

With that said, if we did go this route, we'd need both short and long versions of the captions, as some of our captions are entire paragraphs. We don't want those paragraphs to be duplicated into the list of figures. I know LaTeX has this feature (\caption[short version]{long version}) but I don't know about asiidoc.

We'd also want to exclude this feature from the HTML version, which is already easily searchable with ⌘-F. Including the list of figures arguably makes searching the HTML version more onerous.

[kbroch-rivosinc]

@AlfredoRodrigues4 : I modified the title to make it easier for community to vote 👍 if they want this functionality. I also added "listings" (code blocks in general)

@wmat : I noticed your branch https://github.com/riscv/riscv-isa-manual/tree/1532-lack-of-list-of-figures-tables didn't have the "list of listings". Hoping we can add that to this discussion.

I also laid groundwork for this going into docs-resources with the hopes it can then be used in docs-spec-template as well. I understand that the content might change based on the discussion here but what I'm hoping is that whatever is decided for the isa-manual can then be easily adopted for the docs-spec-template so that any new extensions started from it will look similar to as when they land in the isa-manual.

[psherman42]

Agree with @aswaterman as there is little utility for Lists of Tables (LoT), and Lists of Figures (LoF), out of their natural context; these lists. Instead, a "Concordance" or set of lists of specific topics, or even Frequently Looked Up discussions might be more useful--order and sequence of terms in a Concordance wouldn't need to necessarily follow order in the main document, too.

Instead of LoT's and LoF's, very helpful would be two kinds of Contents: a very short, brief or 'quick' contents list one page long showing only major items and highest level sections; and a longer detailed contents list showing all the sections and subsections within. In fact, the Brief Contents list would help one figure out on whaat page to place little finger tabs for quick and easy reference, should they ever print the document on paper.

[AlfredoRodrigues4]

Answering to @kbroch-rivosinc: I also agree that if the community decides to follow through with adding the LoT and LoF it would make perfect sense to add the "list of listings" making it not only easier to search the document but also keeping conformity across the index section.

[kersten1]

Discussion on mailing list - https://lists.riscv.org/g/sig-documentation/message/290.

Closing this issue for now. We can revisit at a future time.

[kbroch-rivosinc]

Discussion on mailing list - https://lists.riscv.org/g/sig-documentation/message/290.

Closing this issue for now. We can revisit at a future time.

Agreed adding up the responses from discussion forum, it looks like in general the community doesn't think this feature is that useful.

I do think it would be interesting to consider building in a "feature flag" build workflow, so although the default output doesn't use it, the community could render their own versions easier.