Drasil icon indicating copy to clipboard operation
Drasil copied to clipboard

Introduction roadmap sentence hardcodes subsections that may not exist in all example

Open JoeZZG opened this issue 1 month ago • 0 comments

This roadmap is not accurate. None of the things listed are actually covered in the next section.

Originally posted by @smiths in https://github.com/JacquesCarette/Drasil/pull/4470#discussion_r2539668210

Description The roadmap of introduction is hardcoded in Drasil/code/drasil-docLang/lib/Drasil/Sections/Introduction.hs:

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]

introductionSubsections :: Sentence
introductionSubsections = foldlList Comma List (map (uncurry S.the_ofThe)
  [(phrase scope, plural requirement),
  (plural characteristic, phrase intReader),
  (phrase Doc.organization, phrase document)])

It always prints in the introduction as "the purpose of this document, the scope of the requirements, the characteristics of the intended reader, and the organization of the document", regardless of if these subsections actually exist.

Proposed Solutions

  1. Write all the four subsections formally (Purpose of Document, Scope of Requirements, Characteristics of Intended Reader, and Organization of Document) in HGHC.
  2. Make introductionSubsections dynamic by adding conditional logic in the above code.
  3. Use placeholder content by adding empty text for missing subsections in HGHC, which is a temporary solution.

JoeZZG avatar Nov 25 '25 19:11 JoeZZG