Re: [Axiom-developer] hyperdoc source links are often wrong

[Bill Page]

William Sit wrote:

>Perhaps it's a good idea to associate each constructor with it own spad 
>file,but I am not convinced. Historically, I believe that is not the case. 
>Many authors write one large spad file containing multiple constructors 
>(related, of course) -- one reason may be to save duplication of macros. It is 
>also easier to follow a constructor if related ones are nearby.
>
I agree. In fact Tim's reorganization from 1000+ *.spad files (some of
which already included multiple constructors) into the 300+
*.spad.pamphlet files effectively combines even more constructors into a
smaller number of (hopefully) logically related groups. I think that for
the most part the original groupings of constructors into spad files is
retained in the <<chunk>> structure of the pamphlet files. But perhaps
in some cases Tim may have also broken some original spad files into
multiple chunks. (Is that right Tim?) In any case, the way the current
build works is that there is a spad file internally created by running
'tangle' for each spad <<chunk>> for the *.spad.pamphlet files. It is
these file names that end up in Axiom's database and show up in hypertex
and in ')show constructor'.

I think it seems mentally and physically more feasible to document some
300 groups of related constructors rather than over a 1000! So mostly
this reorganization is a good thing.

>When extracting spad files for individual constructors, care should be taken 
>to include all global macros in the file.
>
>  
>
Yes, this is done in the current build process.

>The old (NAG) hyperdoc is able to jump to the constructor even though there 
>may be several in the same file, much like the local html name=xx and #xx 
>references. This feature is no longer available in the new hyperdoc (at least 
>until the files are broken up, which kind of defeats the purpose of Tim's 
>reorganization).
>
I think this happens when ')compile xxx.spad' is called. The file name
xxx.spad is associated in the database with each of the constructors in
the spad file. Unfortunately files with these names only exist
"internally" in the build (i.e. in the 'int' directory) and do not find
their way into the 'mnt' directory.

If the purpose was only to be able to view the spad source without the
associated documentation in the pamphlet file, then I think including
these files in a "read-only" manner in the distribution would probably
not compromise too much the original intention of the re-organization.
But perhaps the temptation to edit these files might prove irresistible :)

>So perhaps a solution would be that the hyperdoc links are not file names, but 
>are global name tags, by which the location of a constructor (file and tag) 
>can be obtained from a database or table.
>  
>
Yes, I think this might be possible. As I said above, these hyperdoc
links are actually associated with the spad <<chunk>> names in the new
*.spad.pamphlet files. In principle it should not be too difficult to
use this information together with both 'tangle' and 'weave' to find the
associated code and documentation. Ideally one might want a text editor
that understands the structure of the pamphlet files and lets you create
both code and documentation in an integrated manner. But failling that,
perhaps we could develope some command line tools to interface with
'notangle' and 'noweave'. Tim already has something like this in the
'document' script.

Maybe hyperdoc can be extended to understand the structure of pamphlet
files so that at least in that context the appropriate code and
documentation could be displayed. (Tim, is that part of your current
re-design of hyperdoc?)

Regards,
Bill Page.