Changing Ref Constructor

Ant13731 commented 3 years ago

After having some problems in this commit and #2489, we found that the Ref constructor for Sentence should only need to accept a UID reference that later resolves into a Reference

JacquesCarette commented 3 years ago

Just a note that this too could spawn a number of sub-issues. Let's hope not.

Ant13731 commented 3 years ago

I'm currently trying to come up with a resolver, but I think because References are usually resolved early, they do not appear in the ChunkDB (only their UIDs do). Should I try and create something like a ReferenceMap type in ChunkDB to hold the actual references? This way, they can be looked up by the printers as needed (like Concepts, terms, symbols, etc.).

JacquesCarette commented 3 years ago

Yes. That they are not in ChunkDB is an oversight, because they were directly embedded previously.

Ant13731 commented 3 years ago

As I started working through fixing the examples so that they will work with the new ChunkDB and Ref, I realized that there is already an existing ReferenceDB type. However it still doesn't include References so I would have to add it anyways. Should I try use that one instead? I don't think it would be difficult to switch types but it'll probably take some time.

Edit: While looking at the database files for ReferenceDB, I found that they are in the same place as the SystemInformation. I think it's possible to separate these into two different files (which might be better for organization as ChunkDB gets its own file too.

JacquesCarette commented 3 years ago

What ends up in ChunkDB and what in SystemInformation is a mess. It evolved over time. There are some issues from last summer where we tried to get a design, but they stalled. I'd search for SystemInformation as the best way to find them.

I think a lot of the code is already set up to pass around a ChunkDB. So my instinct is that that is where to add this extra information. It was probably not there before because it wasn't used for looking things up.

Ant13731 commented 3 years ago

Okay, sounds good, so I'll stick to using ChunkDB then?

Edit: Another question. Should the References be stored in the symbMap or usedDB databases for the examples? or both?

JacquesCarette commented 3 years ago

First question: yes. Your WIP looks good. Second: I don't know! If my memory serves me well, definitely symbMap. We'll have to see about usedDB. That's another part that needs the design re-evaluated.

Ant13731 commented 3 years ago

Im going through the examples part and I noticed that Section is not a part of the HasRefAddress class even though it is Referable. Should I make it an instance (I need it in order to put it in the ChunkDB)? Another idea (which would hopefully fix all cases similar to above) could be to have a HasRefAddress constraint on the class definition for the Referable class (since one of its methods is getting the reference address in the first place). Would it be better to do this instead?

JacquesCarette commented 3 years ago

The lack of HasRefAddress for Section might be an oversight, yes. Go ahead and change this, we'll see if this has any negative consequences.

On the second idea: where are all these classes defined? I want to go take a look at the details first. It sounds reasonable, but...

Ant13731 commented 3 years ago

HasRefAddress is in Drasil.Classes.Core and Referable is in Drasil.Classes. It seems like Referable is mostly a more thorough version of HasRefAddress.

Ant13731 commented 3 years ago

I worked on it a bit more but I can't seem to figure out how to get the uid "TraceMatAvsA" into the ReferenceMap. I couldn't find where it was referenced in the GlassBR example or if it is needed in the first place. Everything else seems to work though.

Another thing I found a little odd was this definition (in Drasil.Printing.Import):

renderShortName :: ChunkDB -> IRefProg -> ShortName -> Sentence
renderShortName ctx (Deferred u) _ = S $ fromMaybe (error "Domain has no abbreviation.") $
  getA $ defResolve ctx u
renderShortName ctx (RConcat a b) sn = renderShortName ctx a sn :+: renderShortName ctx b sn
renderShortName _ (RS s) _ = S s
renderShortName _ Name sn = S $ getStringSN sn

I'm not sure if defResolve should be there since this is only used for rendering references in the spec function. I changed it to refResolve because I thought it would make more sense but this change could be making the above problem. I just thought this was a little odd.

balacij commented 3 years ago

That's interesting. It looks like "TraceMatAvsA" is the UID of the traceability matrix; https://jacquescarette.github.io/Drasil/examples/GlassBR/srs/GlassBR_SRS.html#Table:TraceMatAvsA . In fact, it's not directly added, it's added indirectly through the "traceMatStandard" used in GlassBR/Body.hs

From GlassBR: https://github.com/JacquesCarette/Drasil/blob/43fe3751f2d47e646a93907319bc165566c9d5a5/code/drasil-example/Drasil/GlassBR/Body.hs#L137

GlassBR Body imports: https://github.com/JacquesCarette/Drasil/blob/43fe3751f2d47e646a93907319bc165566c9d5a5/code/drasil-docLang/Drasil/Sections/TraceabilityMandGs.hs#L87-L90

which contains: https://github.com/JacquesCarette/Drasil/blob/43fe3751f2d47e646a93907319bc165566c9d5a5/code/drasil-docLang/Drasil/Sections/TraceabilityMandGs.hs#L51-L55

It looks like you'll need to grab these entire "traceMatStandard" entries and grab their UIDs to add them all to the reference map.

It also looks like this is used in all examples, so you might need to have the same addition to all examples;

jasonbalaci@pop-os:~/Programming/Drasil/code$ grep "traceMatAssumpAssump" -r * --include *.hs
drasil-docLang/Drasil/Sections/TraceabilityMandGs.hs:traceMatAssumpAssump :: TraceConfig
drasil-docLang/Drasil/Sections/TraceabilityMandGs.hs:traceMatAssumpAssump = TraceConfig "TraceMatAvsA" [plural assumption +:+
drasil-docLang/Drasil/Sections/TraceabilityMandGs.hs:traceMatStandard s = map ($ s) [const traceMatAssumpAssump, const traceMatAssumpOther, const traceMatRefinement,

jasonbalaci@pop-os:~/Programming/Drasil/code$ grep "traceMatStandard" -r * --include *.hs
drasil-docLang/Drasil/DocLang.hs:  traceMatStandard,
drasil-docLang/Drasil/DocLang.hs:import Drasil.Sections.TraceabilityMandGs (traceMatStandard)
drasil-docLang/Drasil/Sections/TraceabilityMandGs.hs:  traceMatStandard) where
drasil-docLang/Drasil/Sections/TraceabilityMandGs.hs:traceMatStandard :: SystemInformation -> [TraceConfig]
drasil-docLang/Drasil/Sections/TraceabilityMandGs.hs:traceMatStandard s = map ($ s) [const traceMatAssumpAssump, const traceMatAssumpOther, const traceMatRefinement,
drasil-example/Drasil/GlassBR/Body.hs:  termDefnF', tsymb, traceMatStandard, purpDoc)
drasil-example/Drasil/GlassBR/Body.hs:  TraceabilitySec $ TraceabilityProg $ traceMatStandard si,
drasil-example/Drasil/PDController/Body.hs:        Verbosity(Verbose), intro, mkDoc, traceMatStandard, tsymb)
drasil-example/Drasil/PDController/Body.hs:     TraceabilitySec $ TraceabilityProg $ traceMatStandard si, Bibliography]
drasil-example/Drasil/SSP/Body.hs:  PDSub(..), intro, mkDoc, tsymb'', traceMatStandard, purpDoc)
drasil-example/Drasil/SSP/Body.hs:  TraceabilitySec $ TraceabilityProg $ traceMatStandard si,
drasil-example/Drasil/NoPCM/Body.hs:  tsymb, traceMatStandard, purpDoc)
drasil-example/Drasil/NoPCM/Body.hs:  TraceabilitySec $ TraceabilityProg $ traceMatStandard si,
drasil-example/Drasil/GamePhysics/Body.hs:  PDSub(..), intro, mkDoc, tsymb, traceMatStandard, solutionLabel, purpDoc)
drasil-example/Drasil/GamePhysics/Body.hs:    TraceabilitySec $ TraceabilityProg $ traceMatStandard si,
drasil-example/Drasil/SWHS/Body.hs:  ProblemDescription(PDProg), PDSub(..), intro, mkDoc, tsymb'', traceMatStandard, purpDoc)
drasil-example/Drasil/SWHS/Body.hs:  TraceabilitySec $ TraceabilityProg $ traceMatStandard si,
drasil-example/Drasil/DblPendulum/Body.hs:  Verbosity(Verbose), intro, mkDoc, traceMatStandard, tsymb)
drasil-example/Drasil/DblPendulum/Body.hs:  TraceabilitySec $ TraceabilityProg $ traceMatStandard si,
drasil-example/Drasil/Projectile/Body.hs:  Verbosity(Verbose), intro, mkDoc, traceMatStandard, tsymb)
drasil-example/Drasil/Projectile/Body.hs:  TraceabilitySec $ TraceabilityProg $ traceMatStandard si,

Ant13731 commented 3 years ago

Okay I see, so the references of the traceability matrix themselves are probably not defined in an example file (since every example uses them). I don't think I can just import the TraceConfig variables (like traceMatAssumpAssump) since they don't have a reference address at that point (and aren't instances of the HasUID class). But at least that means if I find it and it works for GlassBR, it will probably work for everything. Thanks!

balacij commented 3 years ago

Yep, they're defined in the Drasil/code/drasil-docLang/Drasil/Sections/TraceabilityMandGs.hs file. I'm not too sure exactly what you want to build with it, but you can probably put the traceMatStandard si call from GlassBR/Body.hs into it's own variable, implement HasUID for TraceConfigs, and then get the UIDs of all of them at once.

Ant13731 commented 3 years ago

Hmm, I wonder if I could just hard code their UIDs since they don't change and then using mkTabRef to make the references off of that. I'll see if that works and then maybe add the HasUID implementation, because I think they'll do the same thing.

Ant13731 commented 3 years ago

I'm having some trouble trying to resolve this unexpected error:

glassbr.EXE: Symbol: SysConstraintsLabel not found in SymbolMap
CallStack (from HasCallStack):
  error, called at ./Database\Drasil\ChunkDB.hs:99:24 in drasil-database-0.1.1.0-1H2SDTZem9VDdavf3C6Z5k:Database.Drasil.ChunkDB
make: *** [Makefile:144: glassbr_gen] Error 1

SysConstraintsLabel should not be needed in SymbolMap in the first place (nor does it work there). I was expecting it to throw a similar error but only for the ReferenceMap (as I haven't added it there yet). I tried following through where the UID is found (in Drasil.DocLang.SRS) but I can't seem to find where (or if) it is being used as a symbol/expression rather than just a reference:

sysCon    cs ss = section' (titleize' Doc.systemConstraint)        cs ss "SysConstraints"

balacij commented 3 years ago

grep will help a lot with searching for things like this -- regular expressions when needed are particularly helpful.

Running grep "sysCon" -r * --include *.hs (plain textual search) gives:

drasil-data/Data/Drasil/Concepts/Documentation.hs:  stakeholder, standard, statement, symbol_, sysCont, system, systemConstraint,
drasil-data/Data/Drasil/Concepts/Documentation.hs:  specificsystemdescription, systemdescription, systemConstraint, sysCont,
drasil-data/Data/Drasil/Concepts/Documentation.hs:sysCont                      = compoundNC system context
drasil-docLang/Drasil/DocumentLanguage.hs:  systCon, usrCharsF, sysContxt)
drasil-docLang/Drasil/DocumentLanguage.hs:     mkSubs (SysCntxt cs)            = GSD.sysContxt cs
drasil-docLang/Drasil/Sections/Introduction.hs:  charOfIR, orgOfDoc, goalStmt, thModel, inModel, sysCon)
drasil-docLang/Drasil/Sections/Introduction.hs:  plural systemConstraint, S "in", makeRef2S (SRS.sysCon [] []) `sC` S "this",
drasil-docLang/Drasil/Sections/GeneralSystDesc.hs:import qualified Drasil.DocLang.SRS as SRS (sysCon, sysCont, userChar)
drasil-docLang/Drasil/Sections/GeneralSystDesc.hs:systCon [] subSec  = SRS.sysCon [systCon_none] subSec
drasil-docLang/Drasil/Sections/GeneralSystDesc.hs:systCon a subSec = SRS.sysCon a subSec
drasil-docLang/Drasil/Sections/GeneralSystDesc.hs:sysContxt :: [Contents] -> Section
drasil-docLang/Drasil/Sections/GeneralSystDesc.hs:sysContxt cs = SRS.sysCont cs []
drasil-docLang/Drasil/DocLang/SRS.hs:  specSysDes, stakeholder, sysCon, sysCont, tOfSymb, tOfSymbLabel, tOfUnit,
drasil-docLang/Drasil/DocLang/SRS.hs:  stakeholder, sysCont, systemConstraint, termAndDef, terminology, traceyMandG,
drasil-docLang/Drasil/DocLang/SRS.hs:  genSysDes, sysCont, userChar, sysCon, scpOfTheProj, prodUCTable, indPRCase, specSysDes,
drasil-docLang/Drasil/DocLang/SRS.hs:sysCont   cs ss = section' (titleize Doc.sysCont)                  cs ss "SysContext"
drasil-docLang/Drasil/DocLang/SRS.hs:sysCon    cs ss = section' (titleize' Doc.systemConstraint)        cs ss "SysConstraints"
drasil-example/Drasil/GlassBR/Figures.hs:  requirement, section_, sysCont, traceyMatrix)
drasil-example/Drasil/GlassBR/Figures.hs:  fig (titleize sysCont) (resourcePath ++ "SystemContextFigure.png") 
drasil-example/Drasil/GlassBR/Body.hs:  srsDomains, standard, sysCont, system, template, term_, user, value, variable)
drasil-example/Drasil/GlassBR/Body.hs:  [makeRef2S sysCtxFig +:+ S "shows the" +:+. phrase sysCont,
drasil-example/Drasil/PDController/GenSysDesc.hs:       (environment, software, softwareSys, sysCont, system, user)
drasil-example/Drasil/PDController/GenSysDesc.hs:      fig (titleize sysCont)
drasil-example/Drasil/PDController/GenSysDesc.hs:      [makeRef2S gsdSysContextFig, S "shows the" +:+. phrase sysCont,
drasil-example/Drasil/SSP/Body.hs:  softwareSys, srsDomains, symbol_, sysCont, system,
drasil-example/Drasil/SSP/Body.hs:    , UsrChars [userCharIntro], SystCons [sysConstraints] []
drasil-example/Drasil/SSP/Body.hs:  [makeRef2S sysCtxFig1 +:+ S "shows the" +:+. phrase sysCont,
drasil-example/Drasil/SSP/Body.hs:sysCtxFig1 = llcc (makeFigRef "sysCtxDiag") $ fig (titleize sysCont) (resourcePath ++ "SystemContextFigure.png")
drasil-example/Drasil/SSP/Body.hs:sysConstraints :: Contents
drasil-example/Drasil/SSP/Body.hs:sysConstraints = foldlSP [atStartNP (NP.the (combineNINI morPrice method_)), 
drasil-example/Drasil/GamePhysics/Body.hs:  systemConstraint, sysCont, task, template, user, doccon, doccon', property)
drasil-example/Drasil/GamePhysics/Body.hs:  [makeRef2S sysCtxFig1, S "shows the" +:+. phrase sysCont,
drasil-example/Drasil/GamePhysics/Body.hs:sysCtxFig1 = llcc (makeFigRef "sysCtxDiag") $ fig (titleize sysCont) 
drasil-example/Drasil/SWHS/Body.hs:  srsDomains, sysCont, system, user, value, variable, doccon, doccon')
drasil-example/Drasil/SWHS/Body.hs:  phrase sysCont, S "A circle represents an external entity outside the",
drasil-example/Drasil/SWHS/Body.hs:  [makeRef2S sysCntxtFig +: EmptyS, titleize sysCont])

but I think you're interested in this line:

drasil-docLang/Drasil/Sections/Introduction.hs:  plural systemConstraint, S "in", makeRef2S (SRS.sysCon [] []) `sC` S "this",

which belongs to a function purpDocPara1, then used by purpDoc, and finally by GlassBR:

drasil-example/Drasil/GlassBR/Body.hs:  _purpose     = purpDoc glassBR Verbose,
drasil-example/Drasil/GlassBR/Body.hs:    [IPurpose $ purpDoc glassBR Verbose,

Ant13731 commented 3 years ago

Okay, thanks! That helps with finding where it is referenced. Although I'm still not really sure why sysCon seems to be needed in the symbolMap. The purpDoc functions only call it as a reference, so it shouldn't be needed in the symbolMap. I tried using grep to see if the systCon function could be the problem but I didn't find anything either. I'll keep trying different things though.

JacquesCarette commented 3 years ago

I'm pretty sure there's a sanity checker somewhere that checks that all reachable symbols are defined. This is indeed overkill, but it has the advantage of being doable as a pre-check.

Ant13731 commented 3 years ago

I looked through all the files that used sysCon and symbResolve and I found that changing the reference in Drasil.Sections.Introduction also changed the error. Removing the reference in that particular file gives a different error. Is it possible that one of the sanity checkers (or lookup functions) are looking through the SymbolMap and expecting all the stuff in ReferenceMap to be a symbol? When I removed sysCon completely, it gave a similar error for parnasClements1986, which should not be in the symbolMap in the first place as it is just a citation. I'm not sure if I'm on the right track here, but I think it might involve how I defined the ReferenceMap.

Edit: On this topic, should refTable be defined as a lens inside of the ChunkDB datatype?

JacquesCarette commented 3 years ago

Yes, I think refTable should be a lens to inside of ChunkDB.

As for the rest... I don't know. Indeed, I don't think everything should be in the symbol map. This is going to require more debugging. The error might be in the traversals that collect up symbols. I don't think we ever really wrote down this part of the design, so it's going to need to be reconstructed. Sorry.

Ant13731 commented 3 years ago

Okay, sounds good. I'll look into it.

Ant13731 commented 3 years ago

I looked through all the code generation files and printers and I didn't find anything that shouldn't have been there (the only times symbResolve or a function that called symbResolve were used was for SymbolStyle Sentences and Exprs, which I think is good). I tried using make debug to profile the code but I got different errors when trying to run (some saying I had to build the code with the -prof flag and others saying that the -prof flag didn't work). I'm still not really sure where the errors are happening, but hopefully I'll be able to find it tomorrow.

Ant13731 commented 3 years ago

I think I found out what the problem was! Sadly, I think it was one of my own creation. When I first changed the reference constructor, I also filled in the Ref case for the getUIDs function in Language.Drasil.Sentence.Extract. However, the function that creates the table of symbols uses this in order to fetch the UIDs from the Ch Sentence constructor. When I added Ref to this function, the symbol resolver was expecting the UIDs that could now be obtained to contain symbols. In addition, there already existed a function (lnames) that is dedicated to obtaining the UIDs from References. I haven't gotten rid of all of the errors from the GlassBR example, but I think I'm more on the right track now.

On that note, would it be a good idea to rename these in case more deferred lookups happen in the future? I'll mention what I learned in the comments/documentation.

Edit: The GlassBR example compiled but there are some changes from stable:

The section references are now using their short form instead of the full words. For example, a reference to IMods section used to look like Section: Instance Models, but now looks like Sec: IMs. The only exception is that now referring to a figure uses the full word Figure instead of just Fig.
In the tex and generated code files, the footnote references and page numbers have either disappeared or are broken.
Some are also using their UID as their reference name.

I'm not quite sure why these are happening, though I suspect it has to do with how they are being printed so I'll look into that next.

Edit 2: After some testing, I found out that the HasRefAddress restriction loses information about the label and how to display it. Making Reference an instance of the Referable class and using Referable as the main restriction both help to remedy this. As for references with additional notes attached, I think that modifying their UIDs will allow for things that reference the same thing to contain different information (or else it would be overwritten). Either way, GlassBR now matches stable, although I'm not too sure if my solution is the best.

JacquesCarette commented 3 years ago

Quite the saga! Ok, I'll look at the code, and comment on the PR.

What you learned above is an important part of the design (of referencing in particular) and should be documented. I think there might even be a wiki page about referencing, but it's likely completely out of date.

Ant13731 commented 3 years ago

@JaquesCarette, I got GlassBR to compile with the new Ref constructor, however theres a few reference names that break stable. When referencing a table using the makeTabRef function, it used to display either Tab:reference or Table:reference, but now it is only displaying the Tab:reference version. For example, in Body.hs at lines 396 and 397, both reqInputsUID and traceMatStandard use the makeTabRef function to put the references into the database. However, they used to display as Table: ReqInputs and now display as Tab:ReqInputs in the generated documentation. I'm not sure why stable didn't display the Tab:reference version initially, or why other uses of makeTabRef display differently. For convenience, here is the diff from logs:

< \item[Input-Values:\phantomsection\label{inputValues}]{Input the values from \hyperref[Table:ReqInputs]{Table:ReqInputs},
---
> \item[Input-Values:\phantomsection\label{inputValues}]{Input the values from \hyperref[Table:ReqInputs]{Tab: ReqInputs},

JacquesCarette commented 3 years ago

We should figure out the source of the change. We worked really hard to remove the multiple appearances of the string "Table" from the library. Looks like "Tab" might occur independently. The first thing to do would be to hunt that down in the code base, as a way to see where this comes from. Clearly the path taken to generate these labels has changed.

Ant13731 commented 3 years ago

Okay, I did a bit of searching and here's what I found: The reason the labelling changed is because the instance of LabelledContent as a Referable actually modifies the display label in this manner:

-- | Finds the reference address of 'LabelledContent'.
instance Referable LabelledContent where
  refAdd     (LblC lb _) = getRefAdd lb
  renderRef  (LblC lb c) = RP (refLabelledCon c) (getRefAdd lb)

-- | Reference the different types of 'RawContent' in different manners.
refLabelledCon :: RawContent -> IRefProg
refLabelledCon Table{}        = raw "Table:" +::+ name 
refLabelledCon Figure{}       = raw "Fig:" +::+ name
refLabelledCon Graph{}        = raw "Fig:" +::+ name
refLabelledCon Defini{}       = raw "Def:" +::+ name
refLabelledCon EqnBlock{}     = raw "EqnB:" +::+ name
refLabelledCon DerivBlock{}   = raw "Deriv:" +::+ name
refLabelledCon Enumeration{}  = raw "Lst:" +::+ name 
refLabelledCon Paragraph{}    = error "Shouldn't reference paragraphs"
refLabelledCon Bib{}          = error $ 
    "Bibliography list of references cannot be referenced. " ++
    "You must reference the Section or an individual citation."

So when I try and map it to the database using rw (which uses the Referable methods), it actually overwrites what the label is. I have an idea to remedy this (but I'm not sure if it is good:

change the makeTabRef function so that it matches what the instance is doing (this may include changing the instance to match the makeTabRef function too). This way calling rw on something that has used makeTabRef will remain consistent. If I were to do this, I think adding a space after every colon in the above refLabelledCon would look better in the generated documents.

Edit: Or better yet, replace the refLabelledCon function with something that calls prepend so that it will match makeTabRef and make the code simpler:

makeTabRef :: String -> Reference
makeTabRef rs = Reference rs (RP (prepend "Tab") ("Table:" ++ repUnd rs)) (shortname' rs) None

Edit 2: Something like this appears to break stable, but only because it adds spaces after every colon:


instance Referable LabelledContent where
  refAdd     (LblC lb _) = getRefAdd lb
  renderRef  (LblC lb c) = RP (prependLabel c) (getRefAdd lb)

prependLabel :: RawContent -> IRefProg
prependLabel Table{}        = prepend "Table"
prependLabel Figure{}       = prepend "Fig"
prependLabel Graph{}        = prepend "Fig"
prependLabel Defini{}       = prepend "Def"
prependLabel EqnBlock{}     = prepend "EqnB"
prependLabel DerivBlock{}   = prepend "Deriv"
prependLabel Enumeration{}  = prepend "Lst"
prependLabel Paragraph{}    = error "Shouldn't reference paragraphs"
prependLabel Bib{}          = error $ 
    "Bibliography list of references cannot be referenced. " ++
    "You must reference the Section or an individual citation."

JacquesCarette commented 3 years ago

Making things simpler and more uniform is definitely good. I'm not very keen on having spaces in labels though - surely there's a way to avoid that.

I have a slight preference for some of the shorter forms (i.e. "Tab:") in certain contexts. Word-based labels are way better than number-based, but one can also go overboard if they get too long/verbose.

So I kind of want a design for how we build our referencing information, rather than just an implementation.

Ant13731 commented 3 years ago

The space comes from the prepend definition so it is an easy fix, and the short forms are good too.

With this change, the references for tables, figures, lists, and sections should all use the short form prefix (tab, fig, lst, sec) and should not have a space between that and the reference name. However, this also has the effect of not having a space between references for other things. For example, data definitions used to display as "DD: reference" but will now display as "DD:reference". Is this good?

Should I make a Wiki page about what I know and what I've done to Reference so far (similar to the Combinator Documentation one)?

JacquesCarette commented 3 years ago

I prefer without the space.

Yes, please make sure a wiki page!

Ant13731 commented 3 years ago

Just a quick question. When implementing references into an example, would it be better to have each file given their own list of references, or just define them all in the Body.hs file? I'm starting to notice that things like the iMods, tMods, dataDefs, genDefs, citations, and assumptions already import all the referable functions to Body.hs anyways, so I could just make them a reference there, but I'm not sure if that would make things messy and hard to find (especially if those files reference other things not in the example). Right now, I've just been going through and seeing where things are referenced in the files and making a list of those things at the bottom of each file, then importing to Body.hs.

JacquesCarette commented 3 years ago

Some of the examples have a Reference.hs file (or is it Citation.hs? Or a mix?) with all the references defined there. That's even more central.

Ant13731 commented 3 years ago

I don't think that's possible, as a lot of other files import References.hs in order to get at the citations needed. It would cause a lot of import cycles (I know this would cause a lot of problems for GlassBR at least, as Assumptions, DataDefs, IMods, and TMods all import references and have references themselves. Perhaps renaming the existing file to be Citations.hs and making a new centralized References.hs could work? But I'm not sure if that's quite right either.

JacquesCarette commented 3 years ago

So if it was all citations, that shouldn't introduce cycles, because References.hs would be "at the bottom" and import very few things. So the issue must be with references to other things?

JacquesCarette commented 3 years ago

The Projectile example is like that. So I would need a more concrete example of a cycle, to understand the problem.

Ant13731 commented 3 years ago

The citations themselves are already in References.hs for all examples, but it's the other kinds of references that make problems. Collecting all the references to be in References.hs would not allow the file to be at a bottom level. It would have to be at a higher level to get needed information from things like assumptions, general definitions, data definitions, theory models, and instance models (which are all References themselves and must be included in the reference database). If we were to gather the references in References.hs and then import them to Body.hs, References.hs would need to import all the files containing such assumptions, general definitions, data definitions, theory models, and instance models. However, these models and definitions sometimes contain citations from the References.hs file. In projectile, the GenDefs.hs file (specifically, rectVelGD) is created using a citation from References.hs (hibbeler2004), so importing GenDefs.hs into References.hs (as a means to gather all references in the example to put into the data base) would create a cycle. I think that creating a new external file that collects all the references and then exports to Body.hs could alleviate this, but I'm not sure if we would want to add another file to the examples (when it isn't really a "Section" like the other files).

JacquesCarette commented 3 years ago

Aha, yes, that makes sense. Ok, so that's definitely not a solution.

In which case, what you're doing now is probably close to as good as can be done, at least with the current infrastructure.

JacquesCarette commented 3 years ago

This might be another case of use-mention.

JacquesCarette / Drasil

Changing Ref Constructor #2562