document stex-references and extend it by document references

kohlhase commented 2 years ago

When tinkering with stex-manual.tex I found that I had (and in sTeX1 that worked) \sref to reference to sfragment environments, and that does not seem to work any more. Also \sref is not documented yet: the corresponding manual section is empty.

If I understand \sref in sTeX3 as it is currently implemented, it only references symbols and statements with a name= attribute (that generates a corresponding symbol for a statement). Thus it is essentially "symbol reference" via MMT URIs.

But we also need a way to reference document fragments. This is what regular LateX \label and \ref give us or even better with the cleveref package, so we could conceptually use that. But in the context of flexibly reusable document fragments as we are pursuing in sTeX3, this is not enough.

We need something I tentative call document URIs (in analogy to MMT URIs) which must provide and a corresponding \dref macro (I am only separating it by name from \sref for conceptual clarity, the functionality might well be folded into \srefeventually or not). \dref must support document fragment referencers

into the same document, just like \cref, but also handle the behavior what happens if the reference is dangling (parts of the documents may have been commented out or moved, ...
into external documents: i.e. a mixture of \cite and \ref; something like \dref{foo77#baz} would be equivalent to \cite[\dref{baz}]{foo77}, where \dref{baz} picks up on the local numbering in the document foo77. Extra points for the change management, if foo77 is a sTeX document.
references into a "document commons",

the sref package in sTeX tried to handle some of these, but only a little bit of the functionality made it into sTeX3. We should take the chance for re-designing the old functionality.

Jazzpirate commented 2 years ago

stexsref

^ for posteriority

Jazzpirate commented 2 years ago

We need something like \STEXsetref[archive=,file=]{label}{in=...} to allow for changing document contexts depending on the including top-level document

kohlhase commented 1 year ago

I think we have to make this a priority, since the students are coming soon (the semester starts in less than one week).

Here are my design goals: \sref{foo} should do the right thing for

local references in the AI notes, i.e. where ...[id=foo]... is in a file that gets \inputrefed in the AI notes
external references in the AI notes, i.e. where ...[id=foo]... is in a file that does not, but has a different (but maybe specified somewhere) top-level document.
"external" references in the standalone modules $M$. This is actually just a special case of 2. where $M$ takes the role of the AI notes.

kohlhase commented 1 year ago

At least 3. does not work (or I do not know how it does). An example is MiKoMH/AI/source/rational-agents/snip/envtypes.en.tex which references the sfragment in MiKoMH/AI/source/rational-agents/fragments/agenttypes.en.tex

kohlhase commented 1 year ago

And 1. also has a problem. See for instance MiKoMH/AI/source/rational-agents/mod/model-based-agent.en.tex which has

     \symname[post=s]{model-based-agent} can do the \sref[fallback=the tail lights
      example]{sra-state-vs-change} if the \symname[post=s]{state} include a concept of
      tail light brightness.

which references

   \begin{sparagraph}[title=Problem,name=sra-state-vs-change]
      \Symname[post=s]{simple-reflex-agent?simple-reflex-agent} can only react to the perceived state of the
      environment, not to changes.
    \end{sparagraph}

from MiKoMH/AI/source/rational-agents/mod/simple-reflex-agent-impl.en.tex. I acknowledge that referencing a sparagraph (unnumbered) has its own problem. But something (e.g. an error should be thrown). Oh, and the context is AI/source/course/notes/notes-part1.en.tex

Jazzpirate commented 1 year ago

from the point of view of which top-level document should envtypes reference agenttypes?

kohlhase commented 1 year ago

Ah, and another instance: MiKoMH/AI/source/intro/snip/intro-ai-part.en.tex has

  After having seen what AI can do and where AI is being employed today (see
  \sref{sec.AI-overview}), we will now

which references

\begin{sfragment}[id=sec.AI-overview,short={AI -- Who?, What?, When?, Where?, and Why?}]

from ./course/fragments/overview.en.tex.

kohlhase commented 1 year ago

see

kohlhase commented 1 year ago

from the point of view of which top-level document should envtypes reference agenttypes?

AI/source/course/notes/notes-part1.en.tex for all of these examples.

slatex / sTeX

document stex-references and extend it by document references #322