A little update, I think that I am making progress. You may be
disappointed as most work is related to presentation and not
strictly data structures. By presentation affects data
structures.
At top level HyperDoc offers 10 searches. First 4 searches
serch for name of category, domain, package or operation
respectively, choosing ones that match pattern. There is
documentation search which searches doctrings which match
pattern. There is difference here, whole name must match
so "oral" matches nothing in first 4 searches, while
in documentation search it is enough to have substring match,
so the same pattern matches one entry (that is
TopLevelDrawFunctionsForAlgebraicCurves). Pattern may
contain literal characters or stars representing arbitrary
sequence of characters, so '*oral*" gives match in
package search. One can use boolean combination of
patterns. For example "*anal* or *oral*" gives 2 matches
for packages.
3 other searches are combiantion of above searches. There
are two searches under "Selectable", which allow specifying
number of arguments and pattern for signature.
All of the above searches work on libdb.text and comdb.text.
Patterns are converted to grep regular expressions and
grep is called to find matching lines. AFAICS split into
libdb.text and comdb.text simplifies resulting patterns.
Anyway, for those searches we need representation for
patterns and representation for result. Currently
result is essentially list of strings. Logically
there are 8 pieces of information in the strings:
- kind of line (catgory, domain. package, operation,
encoded in first character)
- name
- number of arguments
- info about exposure (single character)
- signature
- origin of operations, list of parameters for constructors
- condition for operation, abbreviation for constructors
- documentation (number giving file offset in libdb.text)
For constructors exposure means that constructor is exposed or
not. For operations exposure is really about constructors,
usualy origin. Exposure info in libdb.text is mostly
redundant and HyperDoc in most cases uses exposure info
computed at runtime.
For operations, list of strings is grouped according to operation
name and later expanded into list form. More precisely, for
each operation we have list of lists, where inner list contains
signature, condition, origin, exposure info and documentation
in this order.
There is alternative path for almost exact matches: if name up to
case matches constructor name, then constructor info is collected
via get_database calls and put into a line. For operations,
if name matches exactly operation name list of matching modemaps
is fetched for database (essentially via get_database(op, 'OPERATION)).
Modemaps contain signature and conditions on origin, target and arguments.
This allows computing origin (theoretically this may be quite hairy,
in practice simple code seem to work well). This data misses
documentation and later, when needed there is rather complex
code to find documentation. I think that this part may be
simplified, as once we know origin we can look at documentation
part of origin (stored in database) and find operation there.
The above means that logically we do not need libdb.text and
comdb.text: documentation search can go trough all constructors
and for each constructor trough all its documentation strings.
Other searches can go trough names of construtors or operations,
fetching data for matched entries from database.
libdb.text and comdb.text allow using grep for searches, which
have some advantages. But currenlty we get info from strings
by parsing and interpreter parser is rather slow. So not
using libdb.text and comdb.text may be better.
Concerning libdb.text strings representing constructors, later
most info form the string is discarded and only name is used
(given name we can find the rest in database).
Now, how presentation affects this? Due to overloading we may
have multiple operations corresponding to single name (on average
there are about 2 operations per name) and several views group
operations according to names. So there is need to display
varying info "by name". There are 7 main views of operations:
names, parameters, signatures, full descriptions, grouped via origin,
grouped via condition and grouped via implementing domain. So in fact
in 3 views we have hierarchical grouping. But display logic
is related: we have title (heading) and (possibly nested)
groups with clickable entries. In nested cases groups have
changing labels. Title can change depending on how we entered
the page. There is possiblity to show all operations or only
exposed ones and that also affects title. HyperDoc tries to
disable "useless" links and there is special code to do
this.
There is possiblity of filtering (that is keeping
only names matching pattern).
So, while there are 7 principial views of operations users can
see tens of variations depending on what was done before.
For lists of constructors there are 6 principal views: abbreviations,
names, with parameters, descriptions, grouped by conditions,
grouped by kinds. "General", "Documentation" and "Complete"
search also group info. From constructor description page
one can reach additional pages: ancestors, children, dependents,
descendants, domains, exports, operations, parents, search path,
users and uses. There is also provision for examples (but
probably ATM this is broken). Logically, some of the above
are just list of constructor names (for example domains),
some list of names with conditions (ancestors), exports
essentially combines parents with operations defined in the
constructor.
Let me add that a lot of information is computed on the fly,
due to multiple views it is not practical to keep all needed
information in explicit form as a single data structure.
One can ask if all those pages are needed. Well, some taken
alone are of limited use, but availability of multiple views
adds power.
Extra thing: I think that search similar to constructor and
operation search in HyperDoc could be provided by appropriate
table of data and relativly simple Javascript code. IMO such
thing would be more useful than current Sphinx generated search.
OTOH, providing multiple views probably would require implementing
in Javascript something of complexity comparable to current
browse code.
--
Waldek Hebisch
--
You received this message because you are subscribed to the Google Groups
"FriCAS - computer algebra system" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to fricas-devel+unsubscr...@googlegroups.com.
To view this discussion visit
https://groups.google.com/d/msgid/fricas-devel/aHchUZzFm8kt6Wd-%40fricas.org.
