Werner LEMBERG <w...@gnu.org> writes: >> let me add a few thoughts... > > Thanks for chiming in. > >> For those static ones I have the strong opinion, we should always >> print them expanded and literally, even for a longer list. Thus >> >> • Set translator property ottavationMarkups to: >> >> '((4 . "29") >> (3 . "22") >> (2 . "15") >> (1 . "8") >> (-1 . "8") >> (-2 . "15") >> (-3 . "22") >> (-4 . "29")) >> >> is fine. > > OK. > >> ### >> >> For procedures, we probably could print only the name. [...] >> hash-tables and unpure-pure-containers are even worse. > > I agree. What I can imagine is the following. > > (1) Add a preface to the IR that explains some concepts and details > related to the representation of data types. In particular, it > should be mentioned that the IR contains the values as seen by the > Scheme interpreter, which is often different to what a user should > write. > > (2) Automatically generated references to source code lines, > something like > > file ly/foo.ly, line xxx > > for top-level stuff like LilyPond contexts.
Scheme can be told to keep source locations for expressions. Documentation generation could switch this on and pick the expression out of the source code instead of using it from the variable when it is being generated by Scheme. It's not like the autogenerated documentation is eating the lion's share of our processing time. -- David Kastrup
