Filling in reference fields

[halonazhao]

To fill the reference field for TM, DD, GD, IM, my thought of the working flow is basically like below:

1. To build a LabelMap = Map.Map UID Lable like SymbMap, UnitMap in ChunkDB. This label map should be manually generated when we created all the labels.

2. Since the reference relations should be collected only from Sentence and the references in Sentence are made by using makeRef and further calling customRef to generate better names. The problem here is as below: https://github.com/JacquesCarette/Drasil/blob/9350be2696084ad959bbc1c5122d7313f95162ea/code/drasil-lang/Language/Drasil/Reference.hs#L320-L321 https://github.com/JacquesCarette/Drasil/blob/9350be2696084ad959bbc1c5122d7313f95162ea/code/drasil-lang/Language/Drasil/Reference.hs#L329-L343 https://github.com/JacquesCarette/Drasil/blob/9350be2696084ad959bbc1c5122d7313f95162ea/code/drasil-lang/Language/Drasil/Spec.hs#L21-L34

By matching Ref from Sentence, only the shortname can help detecting which label we are referring. If using 'shortname' to look up a label in database, we may have to have a label map at type Map.Map ShortName Lable, which has conflicts with the first step of design. And I think that we alway want UID to be the index to the database. So we may want to expand the Ref structure in Sentence to include UID and now we only reference things using label and labels always have UIDs.

3. Once we get the first two steps done, we will have to traverse SSDSec in DocSec. Then I will create a map to record all the reference relation between all DDs, Assumptions, IMs, GDs, TMs. I will take TM as an example. TMs :: Fields -> [TheoryModel] -> SCSSub So I will get all TheoryModel with their labels. The labels will be made index in the map and the referenced labels collected from sentence from each TM will be a list of labels in the map. So the mao will be ReferenceMap = Map.Map Lable [Label].

4. When I get the whole SSD section traversed, the ReferenceMap will be filled up. The next step should be filling the RefBy field.

The problem here is that when we are able to traverse the all the chunks to fill ReferenceMap, that would mean we already have TMs, IMs, DDs built. All the informations has been filled in to TMs, IMs, DDs but references because we temporarily left it empty. when I want to fill the collected references in, it sort of has to rebuild all the TMs, IMs and DDs again to fill the reference informations in. This way would only does changes on DocSec.

There is another way I can think is filling the reference field while converting DocSec to Document. https://github.com/JacquesCarette/Drasil/blob/9350be2696084ad959bbc1c5122d7313f95162ea/code/drasil-docLang/Drasil/DocumentLanguage/Definitions.hs#L80-L92 when converting the TMs, I fill the references directly to the field since during this process, the TM itself's label is available to check the referring labels.

This is basically my thought. Could you go through and give some ideas? @JacquesCarette

[JacquesCarette]

You are correct that Ref should contain the UID, at least if things stay as is.

However, your second suggestion (filling in the reference field while converting DocSec to Document) is probably the even better 'solution'. Though Ref might still need that change.

Overall, we should think that:

1. DocLang is really the document-author level language that should be used as much as possible.
2. Document is a layout language, but quite abstract, which is intermediate before we move to a specific layout language in drasil-printers.

In other words, DocLang should evolve to be the language we use to describe the contents we want in a particular document. Then, perhaps along with some 'style' options, we want to render that to a Document, which starts the process of translating from content to layout.

References are 'content-full' things.

[halonazhao]

When I was working with TM, I feel there is one thing odd which is where the UID of the TM comes from. https://github.com/JacquesCarette/Drasil/blob/350662104824b07b3b2d93a45d8fbd448be837ba/code/drasil-lang/Language/Drasil/Chunk/Theory.hs#L33-L43 https://github.com/JacquesCarette/Drasil/blob/350662104824b07b3b2d93a45d8fbd448be837ba/code/drasil-lang/Language/Drasil/Chunk/Theory.hs#L58-L65 Currently the uid is from conceptChunk, but why goes so long way back there instead of using TheoryChunk's uid. @JacquesCarette

[JacquesCarette]

You're right, this is a bit weird. I am not even sure why TheoryChunk and TheoryModel are separate. It feels to me like TheoryChunk should not have a UID at all, and so not exist in the system 'raw', but always inside a TheoryModel. @szymczdm ?

[szymczdm]

I believe TheoryChunk was originally intended as an encoding for any kind of abstract theories. It definitely feels like somewhere along the way it was updated to include some referencing information that, without taking a deeper look seems out of place, and TheoryModel was meant to take a TheoryChunk and make it more concrete by giving it a label, definition, etc.

[JacquesCarette]

Right. So it seems to be that we should remove UID from TheoryChunk and in fact not let TheoryChunk really exist outside of TheoryModel.