Determine Document Outline from Actual Document Contents

[samm82]

As mentioned in #935, Tiny's SSD references an IM section that doesn't exist. Drasil should be updated to "automatically deduce the text for the document "roadmap" from the actual contents/recipe for the document."

[JacquesCarette]

The cool thing about this feature (even though it is low priority) is that it would be the first instance where the document processor would examine the structure of the document as part of generating the document itself. I think 😄 .

[smiths]

This would definitely be a step in the right direction for Drasil. Automating the construction of documentation "roadmaps" would be a nice step forward. We should also have it so that these roadmaps can be turned off completely. Not everyone likes them (looking at you @JacquesCarette). 😄

[JacquesCarette]

Actually I find it rather exciting that we're getting to the point where stylistic differences can become something we don't need to argue about, we just twiddle the right parameters and voila! everyone's happy.

[smiths]

Exactly!

[samm82]

Just a note that I think this will come up while working on Projectile, so it might get added to that project in the future.

[Mornix]

Referencing #1164 here as this is the impetus for that issue.

[smiths]

I just rediscovered this issue in looking over the double pendulum example, I noticed that the last paragraph of the introduction gives a roadmap of the section that is mostly wrong. It mentions sections that are not included in the documentation, like the purpose section and the characteristics of the intended reader section.

In issue #2615 this problem is listed for @cd155. @JacquesCarette, I would like @cd155 to fix the Introduction section by adding the relevant subsections, but it would be nice to finally close this issue. Is the reason it hasn't been closed that it is difficult, or just that we haven't got to it yet? Would this be a good issue for @cd155 to tackle as a means to learn more about Drasil?

[JacquesCarette]

Just that we haven't got to it. It would be a good issue to start digging in to Drasil.

[smiths]

@cd155, I've assigned this issue to you. It will be a good issue to look into to help you learn Drasil.

[cd155]

I think I locate the place that makes this happen.

The overviewParagraph gives the template to the second paragraph in the introduction.

Drasil/code/drasil-docLang/Drasil/Sections/Introduction.hs

Lines 66 to 72 in 4b9ad0a

	-- | Constructor for the overview paragraph for the Introduction.
	-- Takes the definition of the specific example being generated ('Sentence').
	overviewParagraph :: Sentence -> Contents
	overviewParagraph programDefinition = foldlSP [S "The following", phrase section_,
	S "provides an overview of the", introduceAbb srs, S "for" +:+.
	programDefinition, S "This", phrase section_, S "explains the", phrase purpose,
	S "of this", phrase document `sC` introductionSubsections]

The introductionSubsections contains the subsections, including scope, characteristic and organizaition.

Drasil/code/drasil-docLang/Drasil/Sections/Introduction.hs

Lines 45 to 50 in 4b9ad0a

	-- | 'Sentence' containing the subsections of the Introduction.
	introductionSubsections :: Sentence
	introductionSubsections = foldlList Comma List (map (uncurry S.the_ofThe)
	[(phrase scope, plural requirement),
	(plural characteristic, phrase intReader),
	(phrase Doc.organization, phrase document)])

In the first @JacquesCarette reply,

The cool thing about this feature (even though it is low priority) is that it would be the first instance where the document processor would examine the structure of the document as part of generating the document itself. I think 😄 .

I am not quite sure how to make the document processor examine the structure of the document. Do you know how to start to make it happens? @balacij @tingyuw

[balacij]

I think @tingyuw is more knowledgeable in this area (this might also be helpful for her work?), so I think it's best for her to take a look at this first. Have you already taken a look at the mkDoc and nearby functions from drasil-docLang? I'd imagine that you would want to start doing some processing there but I'm not 100% sure.

[tingyuw]

This is something worth discussing and might be useful in the notebook applications. I think the SRS is supposed to build in the same structure and that's why we have the overview paragraphs which can fit in all examples. I think the changes will be made in the DocumentLanguage, in the mkDoc or mkIntroSec. I was thinking maybe you can provide different cases and pass the information from each example, so that Drasil can know which case to apply. Or maybe just build this paragraph in each example to make it specific. They are just some rough ideas : )

[JacquesCarette]

Indeed. Right now introductionSubsections is too hard-coded. What we should do is to take a DocDesc, look at what sections are actually there, and then generate an introduction based on that. Already

Drasil/code/drasil-docLang/Drasil/DocumentLanguage/Core.hs

Lines 102 to 103 in fb9d573

	data IntroSec = IntroProg Sentence Sentence [IntroSub]
	-- ^ Temporary, will be modified once we've figured out more about the section.

indicates that this part is too hard-coded, and will get modified once we know what we want.

[Ant13731]

@cd155, I'm not sure how far you've gotten on this, but I think the Table of Contents section generator does something like this - it only displays sections that exist. Its not very well optimized, but it might be worth it to take a look at drasil-docLang/Drasil/Sections/TableOfContents.hs

[cd155]

@Ant13731 so far, I haven't started to edit any code yet. Thanks for the tips, I will take look at it when I get there.

[tingyuw]

@cd155 I just noticed that the Purpose of Document Section has done something similar. It displays the contents based on the number of given elements.

- | Constructor for Purpose of Document subsection. Takes a list of 'Sentence's that:
--
--     * Given one element: explains the purpose of the specific example.
--     * Given two elements: explains the purpose of the specific example and the development process.
--     * Otherwise: Uses the default 'developmentProcessParagraph'.
purposeOfDoc :: [Sentence] -> Section
purposeOfDoc [purposeOfProgram] = SRS.prpsOfDoc [mkParagraph purposeOfProgram] []
purposeOfDoc [purposeOfProgram, developmentProcess] = SRS.prpsOfDoc 
  [mkParagraph purposeOfProgram, mkParagraph developmentProcess] []
purposeOfDoc _ = SRS.prpsOfDoc [mkParagraph developmentProcessParagraph] []

Not sure if it's the same case, but I think it's worth it to give it a look.

[smiths]

Example: https://jacquescarette.github.io/Drasil/examples/hghc/SRS/srs/HGHC_SRS.html#Sec:IMs

The Solution Characteristics section points to a non-existent Instance Model section.

[samm82]

Another example of this: DblPendulum, Projectile, and possibly more refer to non-existent likely and unlikely changes.