Menu tree documentation generator

[jcbenoist]

A new .md /db48x/doc/menus-tree.md is automatically generated from menu.cc, ids.tbl etc.. by a Python script, invoked by Makefile if a command is added or modified.

Hyperlinks are all functionnal. This gives also an overview of undocumented or unimplemented commands.

doc/menus-tree.md is added to git, but is a generated document, not to be edited. This permits to observe diffs between db48x versions.

[jcbenoist]

Arg ! db48x markdown renderer does not support tables. Hold on, I'll try to make Python generate menus bmp..

[jcbenoist]

Well : I have investigated 3 possibilities :

1. Render the menus as VERBATIM monospaced strings
2. Python generates bmp for menus
3. Adding table support for db48x markdown renderer

1. is not fancy and difficult to render well
2. needs a python lib which should be added to development environment.
3. adds not too much code, and render well. And add other useful documentation possibilities.

So I have tried the third way. The result is not bad.

[c3d]

Thanks @jcbenoist I like the idea. Neat.

I just pushed an updated build system based on one of my earlier projects called make-it-quick. , You will need to adjust your build for it.

One of the key benefits for me of that new build system is that make now always succeeds, including when the CRC check fails (it then only rebuild the required files). It's also easier on the eyes, at least to me.

[jcbenoist]

I have heavy problems with new Makefile, probably because I have NAME= in my system environment, overriding NAME var in Makefile. Also memory problems, I hadn't before. Hold on, I'm on it

Also issues with dm42n target. Claude is examining them.

[jcbenoist]

All compile OK now. "NAME" in environment is not supported. I have to unset it (but it was a synonym of HOSTNAME).

Here are Claude explanations for dm42n target failure :

Variable forwarding in fw-% rule

• Before
  fw-%:
  $(MAKE) $* KIND=fw BUILDENV=arm-none-eabi

• After
  fw-%:
  $(MAKE) $* KIND=fw BUILDENV=arm-none-eabi MODEL=$(MODEL) NAME=$(NAME) SDK=$(SDK)
  MODEL=dm42n NAME=db50x SDK=dmcp5 were set by dm42n-% but not forwarded through fw-% to the actual build, so the defaults (dm42/db48x/dmcp) were silently used instead.

Per-file define key (DEFINES_src/dmcp/qspi_check.c → DEFINES_src/dmcp/qspi_check)
MIQ's compile pattern for %.c uses $* = stem without extension. The per-file define key must match that stem, so the .c suffix must be dropped.

Missing tools in config.arm-none-eabi.mk

OBJCOPY and SIZE are used in the post-build rules but weren't defined. Added:

OBJCOPY=$(CROSS_COMPILE)-objcopy
SIZE=$(CROSS_COMPILE)-size

.mkdir-only fallback rule

$(OUTPUT).mkdir-only normalizes to .mkdir-only (make strips ./), which doesn't match the %/.mkdir-only pattern in rules.mk. Added an empty rule in the ifeq ($(KIND),fw) block since the current directory always exists.

[c3d]

Hi @jcbenoist,

Regarding having NAME in your environment, this is both a strength and a weakness of make, little I can do about that, short of having super-obscure names. You can run with NAME= on the command line or unset it in the shell where you use make.

For the first point, Claude is hallucinating here. You don't need to forward variables that way.

Try make with this Makefile:

$(info FOO=$(FOO) BAR=$(BAR) ZOO=$(ZOO))

all: foo-bar-zoo-all

foo-%:
	make FOO=foo-$(BAR) $*
bar-%:
	make BAR=bar-$(ZOO) $*
zoo-%:
	make ZOO=zoo-$(FOO) $*

For the second point, you probably did not to a git submodule update --init --recursive. You need that because OBJCOPY was indeed added to make-it-quick.

For the .mkdir-only rule, it's strange that you would hit that. OUTPUT being empty is a normal condition for make-it-quick, you set OUTPUT=foo in your environment if you prefer all the make-it-quick output to go to some build root. For example, OUTPUT=/tmp/foo/bar make will build stuff under /tmp/foo/bar. It does not work yet for the qmake parts of the build, and the target directory must exist, which I will fix in a coming commit of make-it-quick.

[jcbenoist]

I'll redo all with a proper submodule init at first. I have to learn make-it-quick (which seems interesting).
"NAME" was not a problem in past. I prefer to unset it from my dev environment (Fedora WSL VM dedicated to db48x anyways)

[jcbenoist]

Here it is ! Minimal changes to Makefile after this imbroglio.

[evgaster]

@jcbenoist

To me the Menu tree is a very welcome addition to the documentation.

Is it possible for you to add information about "how to get to a particular menu"?
I am thinking along the lines of: 🟦 O for the Plot menu.

The mapping for the menus that are directly accessible from the keyboard are in config/db48x.48k.
Some menus are only accessible via an other menu.

[jcbenoist]

@evgaster This was an excellent idea, and add much value to the documentation. Feel free to comment the format of access paths description or other points.

There is perhaps a last point to discuss. Some menus have now duplicated hyperlinks, because there were already docs for them in "manual" documentation (in # Menus section) , like ## MathMenu.

I'll (for now) rename the generated duplicated hyperlinks to have a clear situation, but a reflexion is needed to "merge" manual documentation for menus, and automated documentation.

[jcbenoist]

Here is the policy for renaming conflicting hyperlinks (last commit). The conflicting generated hyperlinks are renamed " reference" (because generated doc is sort ot "reference manual", and existing doc "user manual"). A link "See also" to "user manual" is generated for all conflicting menus. For example :

MainMenu Reference

See also: MainMenu user documentation

Access: 🟦🟦 Σ+

[evgaster]

Your quick response (I think) shows you are having fun programming this, in Python. It also shows that adding this "Access" functionality benefits from an already strong basis. In other words: your design, approach and code look very good to me. Its output is fantastic.

Feel free to comment the format of access paths description

You deviate from the convention quoted here:

In the rest of this document, keys bindings will usually be described using the alphabetic key, to make it easier to locate on the keyboard, followed by the standard label on the DB48X layout. For example, the assignment for the sin function will be described as J (SIN). The shifted functions of the same key will be described as 🟨 J (SIN⁻¹) or 🟦 J (HYP) respectively.

In some cases, the label between parentheses may refer to another calculator model, which will be indicated as follows. For example, the A key can be described as A (⚙️, DM-42 Σ+, DM-32 √x).

Let's take this example:

I would prefer No italics, normal text. The 🟦🟦 should be just 🟦. LOG should according to the convention be "D (ALGB)" but I would prefer "D (LOG)". I locate LOG quicker then D.

The ":", colon, after Access is appropriate. But then "; ", semicolon space, should separate the list elements.

And this example:

I understand the -reference in the link. I would not mind skipping " Reference" in the title.
Again, I prefer No italics, normal text.
The link text should correspond to the title you are linking to. " user documentation" should be normal text (after the link) and better " in the other documentation" ... for now.

but a reflexion is needed to "merge" manual documentation for menus, and automated documentation.

I think we should restructure all the user documentation.

[jcbenoist]

@evgaster I don't know how to have a displayed title different of his hyperlink in Markdown. OK for all your other remarks. For the sake of honesty and transparency, I have heavy help from Claude Opus, but I have fun nonetheless, and I orient or corrects the directions taken by Claude. There is still a pilot in the plane..

[evgaster]

The link text should correspond to the title you are linking to. " user documentation" should be normal text (after the link) and better " in the other documentation" ... for now.

Could you have an other look at the above remark. To make it more explicit: The link is now "DateMenu user documentation". I think the link should be just "DateMenu" followed by (normal text) "in the other documentation".

I noticed a couple of things in the AlgebraMenu. Compare these 2 images:

The reverse video "cas" comes out rather strange. The "X" (twice) looks odd as well.
What about the indicators with "Final" and "&Wild"?

Then I remembered the ConstantMenu. It has things like reverse video "cst". The menu is missing from 8-menus-tree-dm42.md:

The EquationsMenu is missing too, for the same reason, I guess. Same for the CharactersMenu and the UnitsMenu. Those 4 menus deserve to be mentioned (at least).

[evgaster]

An other similar challenge ...

A complete list of commands, with their alternative spellings (see 6-ImplementationStatus.md), and ... their Access.

[jcbenoist]

@evgaster Thanks for your remarks. I'll see what I can do. For "cas" (or other similar) symbol, I have seen it : it render OK on the simulator and real hardware built-in doc, but not in an external markdown browser. So, I have to keep this character, otherwise it will not render well inside the db48x..

EquationsMenu or other not rendered menus are EXTERNAL_MENU. Their content depends of dynamic configuration like csv for equations. I'll render stubs for them, cannot do better.

[jcbenoist]

Well, I fixed as much as I can. To do better, as you said, "we should restructure user documentation", and have more "generator friendly" source files. But it is pretty much interesting and useful as it, isnt it ?

[jcbenoist]

An other similar challenge ...

A complete list of commands, with their alternative spellings (see 6-ImplementationStatus.md), and ... their Access.

I dont see clearly how to articulate that with "Implemented commands". I cannot overwrite this, and 9-list-of-commands would be redundant. What is your opinion about that ? @c3d what is your opinion too ?