Streamline figure markdown

[tunetheweb]

Makes progress on #1138

At present this does not:

• change the anchor links as the ids (will need to think how we handle 2019 links if we do change these and update all the 2019 chapters to the new format - which I'd like to do for consistency).
• do much for the tables (though ids are automated and fig-caption is automated a little).
• add the menu or query links suggested in Streamline figures in markdown #1138

It definitely does clear up a lot of the repetition and makes it a lot easier to add figures and have consistency in the mark up used for figures.

At the moment I've only moved two of the 2019 chapters to show how they work. Can add the other chapters to this PR once it's been reviewed, or open a new PR for them.

[rviscomi]

WDYT about leaving all of the 2019 contents as-is and only using these function for 2020? Not sure if it's worth the maintenance cost to edit everything.

[tunetheweb]

I like having the consistency. I have some regexs worked out to make this relatively easy. Also have a feeling we may forget how this works, or may stop testing it between now and 2020 figures being ready. Having old chapters as examples would be good.

Also makes translations easier as there is a lot of duplication and confusing syntax.

Also means any new features we add (like your menu) are automatically backported. Though I do agree that adding extra meta-data (e.g. links to SQL or specific sheets) isn't worth the effort to add to the old years so may not benefit that much from it.

[rviscomi]

Will this create a discrepancy in figure numbering between CSS/JS and the rest of the 2019 chapters? The former will use the new chapter number prefixes (eg "Figure 1.1").

[tunetheweb]

Just committed the other chapters there - for English anyway (will do the other languages now). Have some regexes that makes this easy and even spotted a few longstanding typos as part of that when the regexes didn't work!

The only question is that two of our chapters (Markdown and Performance) had different figure anchors (#fig1 instead of #fig-1 like the other 18 chapters use). Previously, when we automated this a little, we catered for this:

almanac.httparchive.org/src/tools/generate/generate_figure_ids.js

Lines 10 to 16 in 4b23bd5

	//Some of our 2019 chapters (markdown and performance) had different fig ids
	const figcaption_regex = /<figcaption(.*?)>(.*?)([0-9]+)\./gi;
	if (html.includes('<figure id="fig1"')) {
	return html.replace(figcaption_regex, '<figcaption$1><a href="#fig$3" class="anchor-link">$2 $3.</a>');
	} else {
	return html.replace(figcaption_regex, '<figcaption$1><a href="#fig-$3" class="anchor-link">$2 $3.</a>');
	}

I think we shouldn't complicate the logic by catering for it this time by adding "if 2019 and (markdown or performance)" and should just be consistent across the chapters despite the fact that this might be that anchor links for these chapters will change. You OK with that? And don't let the fact you authored one of these chapters sway you too much 😉

[rviscomi]

LGTM, sorry for the delay.

Just one comment about figure numbering consistency for 2019.

[rviscomi]

Will this create a discrepancy in figure numbering between CSS/JS and the rest of the 2019 chapters? The former will use the new chapter number prefixes (eg "Figure 1.1").

[rviscomi]

Would you also be up for documenting the figure_markup interface for authors, either in the wiki or a README?

[tunetheweb]

All chapters updated. Merging and yes I'll document in the wiki. Who owns this? Analysts? Authors? Editors?