HTML: Figures should have Figure X: in their figcaption and references to figures should be prettier.

[Mornix]

EDIT: Take Projectile's SRS for example. Specifically, the System Context Figure. We have ~2-3 issues:

1. Figures are missing the Figure: text in their captions.
2. References to figures use the internal HTML IDs! For example, in the System Context section, we write Fig:sysCxtDiag.
3. Instead of writing the references, we should either use a short-caption (i.e., a short-title where available) OR use a numbering system.

@smiths Do you have any thoughts on whether this we should use a numbering system or a short-caption?

Original OP:

• LaTeX gets figure prefixes (i.e. "Figure xx: ") for free in captions, whereas HTML does not. This results in either the HTML not having "Figure xx:" prefixed to captions or LaTeX having "Figure xx: Figure xx: " prefixed to its captions.
• ~~HTML is not centering figures. LaTeX encloses figures in a center environment. ~~

[samm82]

A similar (but different) thing happened with tables (#833), and I think (at least for now) we're OK with it. This came up now because I'm removing a function that created a LabelledContent for a figure (because it's only used a couple of times and isn't worth it), and it happened to hardcode these figure numbers.

[Xinlu-Y]

Q: When referencing figures in the text and adding captions, should I use a consistent numbering system, such as "Figure 1:" for in-text references and "Figure 1: System Context" for the caption under the figure, to make them clearer and prettier?

[JacquesCarette]

The underlying infrastructure should provide the consistent numbers - we just have to provide consistent labels.

[Xinlu-Y]

Any suggestions for adding the prefix "Figure: " in HTML without using a numbering system?

Note: References to figures have been slightly adjusted for clarity.

1. We could use a prefixed caption like 'Figure :' for figures in HTML by simple editting the code:

sysCtxFig1 :: LabelledContent
sysCtxFig1 = llcc (makeFigRef "systemContext") $ fig (S "Figure: " +:+. titleize sysCont) 
  (resourcePath ++ "SystemContextFigure.png")

• And this is the HTML version:

2. However LaTeX automatically prefixes captions with 'Figure 1:', 'Figure 2:', etc., which can result in repetitive prefixes if you add "Figure: " manually. So the challenge is to avoid this conflict by ensuring that the prefix is added only in the HTML version and not in the LaTeX version.

• At the same time this is the LaTeX version: (which results in unwanted repetitive prefixes)
  

[smiths]

The generator for LaTeX should be different from the html generator. The word Figure shouldn't be added in the LaTeX version. @JacquesCarette alluded to the underlying numbering system. Is there one for the html version? If there is, you could use it. If not, maybe we don't need numbers for the html version? They hyperlinks do the same job.

Do we have hyperlinks in the LaTeX version? It looks like we do from the screenshots given above.

[Xinlu-Y]

The generator for LaTeX should be different from the html generator. The word Figure shouldn't be added in the LaTeX version. @JacquesCarette alluded to the underlying numbering system. Is there one for the html version? If there is, you could use it. If not, maybe we don't need numbers for the html version? They hyperlinks do the same job.

Do we have hyperlinks in the LaTeX version? It looks like we do from the screenshots given above.

Currently, HTML does not have a numbering system. Adding the prefix "Figure:" could lead to the conflict mentioned earlier.
There are no hyperlinks in the LaTeX version. Maybe I should look into the differences between the generators for each format and figure out why LaTeX automatically prefixes captions.

[JacquesCarette]

Yes @TRISHI-L it is a good idea to investigate in more depth how both the HTML and LaTeX renderers work, and how they are different. This isssue is a bit subtle.

I think that we chose to use symbolic links in HTML (rather than numbers) as those tend to be more meaningful for human readers.

[BilalM04]

@Xinlu-Y, the relevant package for this issue is drasil-printers, which converts Drasil’s representation of the SRS into various render-able formats (HTML, LaTeX, etc.). Specifically, the change to the caption pertains to the function responsible for setting up HTML figures (see below). You can simply append "Figure:" to the caption (c).

Drasil/code/drasil-printers/lib/Language/Drasil/HTML/Helpers.hs

Lines 141 to 150 in 8ca26be

	-- | Helper for setting up figures.
	image :: Doc -> Doc -> MaxWidthPercent -> Doc
	image f c 100 =
	figure $ vcat [
	img [("src", f), ("alt", c)],
	figcaption c]
	image f c wp =
	figure $ vcat [
	img [("src", f), ("alt", c), ("width", text $ show wp ++ "%")],
	figcaption c]

Similarly, it would probably be nice to add this change to mdBook as well. Here is the function for setting up figures in mdBook:

Drasil/code/drasil-printers/lib/Language/Drasil/Markdown/Helpers.hs

Lines 63 to 67 in 8ca26be

	-- | Helper for setting up figures
	image :: Doc -> Doc -> Doc
	image f c = text "!" <> reflinkURI fp c $^$ bold c
	where
	fp = text $ "./assets/" ++ takeFileName (show f)