Duplication of the documentation for array element

[MarekPikula]

Follow up to issue #5:

A related issue here is the duplication of the documentation for each array element.
I think the structure of the documentation should be the same for all generators (HTML, PDF, Markdown), but I have to run a few examples before I can make a proposal.
This month I also discussed with Alex how parameterized definitions are used by generators, and this adds a few extra consideration on how to document everything and just once.

Originally posted by @jeras in #5 (comment)

Another option for the expected output would be to show the array explicitly instead of each individual element:

Offset	Identifier	Name
0x104	TEST_REGISTER[0:63]	Test Register description

Another problem is, that each element of the array has its own documentation section, with the heading lacking any index, just TEST_REGISTER.

There is also a conceptual problem. Since a full list of individual array elements adds clutter and causes scrolling fatigue, I would usually prefer a more compact approach, where arrays are represented with a range instead of individual elements, and for each array a single element is documented (if I have 8 identical SPI controllers, I do not need 8 copies of their full description).

On the other hand, if I am looking for the absolute address of a register, then a full listing would be appreciated.

One solution to this problem I see (which is also common in existing documentation), would be to have 2 generators:

• one for a flat table which includes all absolute addresses, but only short names as description,
• the other hierarchical (address offsets), with arrays defined only with a range, and not a list, containing full documentation strings, but only once for each array element.

Originally posted by @jeras in #5 (comment)

[bwhitchurch]

I had some ideas on this topic while working on the original issues, but I think they end up touching a lot of the code so better that this got separated.

For both table and detailed documentation I was considering a compressed vs full format that would be controlled with command line arguments, i.e. peakrdl markdown --table-format compressed --desc-format full. A full formatted description would mean enumerating all array elements (with possible change to add the index into the header name), while the compressed description would be one block that maybe also includes stride and array size.
This would be nice and flexible, but requires a bit of work to modify the generation process.

[saberxt]

Having same trouble when generating markdown document with array-like regs.

In 1.0.2, we noticed the identifiers of regs in the table of the regfile are distinguished by indexes, but they are still the same in the title of each section of reg.

[shotaminato]

I have the same problem. Is there any updates for this?