Creating tutorial POD that refers to source code lines

perlancar has asked for the wisdom of the Perl Monks concerning the following question:

I'm planning to package some of my tutorials on my blog and upload it as CPAN distribution. Here's an example blog post. Some of these posts present a piece of source code and discuss it part by part, mentioning line number or line number ranges (BTW, as you see, WordPress shows line numbers and allows us to highlight some lines.)

MetaCPAN also has a source code viewer which shows line number and can highlight a single line (example). I'm not sure if the source code viewer can be instructed to highlight multiple lines. In my tutorial POD (converted from the tutorial blog post) I can link to a specific line. The drawback is: 1) the link is specific to MetaCPAN; 2) the source code needs to be in a separate file in the distribution. For source code embedded in the POD as verbatim paragraphs, by default there is no line number or line highlighting.

Any advice on how to make this kind of tutorial also convenient to read on MetaCPAN?

Comment on Creating tutorial POD that refers to source code lines

Replies are listed 'Best First'.
Re: Creating tutorial POD that refers to source code lines by tobyink (Canon) on Jan 22, 2019 at 09:15 UTC
Personally I'd say something like "the full source code for the script discussed in this tutorial can be found in Appendix A" near the start, and give the full source code within the pod. Then during the tutorial, when you need to refer to particular sections of the source code, instead of just saying a line number, quote a few lines of code — the part under discussion and any extra lines necessary to understand it in context. If this is more than four lines, perhaps add some comments like `##line 18` so that readers can find their way around it. You may also want to include the full script as a standalone file outside of the pod, but don't rely on this as the only way to provide it, as examples aren't typically installed. toby döt ink	[reply] [d/l]
Re^2: Creating tutorial POD that refers to source code lines by perlancar (Hermit) on Jan 22, 2019 at 10:16 UTC
Personally I'd say something like "the full source code for the script discussed in this tutorial can be found in Appendix A" near the start, and give the full source code within the pod. Then during the tutorial, when you need to refer to particular sections of the source code, instead of just saying a line number, quote a few lines of code — the part under discussion and any extra lines necessary to understand it in context. If this is more than four lines, perhaps add some comments like ##line 18 so that readers can find their way around it. Thanks, a couple of good ideas to adopt. A bit more work, but still workable. You may also want to include the full script as a standalone file outside of the pod, but don't rely on this as the only way to provide it, as examples aren't typically installed. That's okay. Example scripts that aren't installed are still readable and downloadable via MetaCPAN.	[reply]
Re: Creating tutorial POD that refers to source code lines by Anonymous Monk on Jan 22, 2019 at 10:00 UTC
More less clever? :) Pod is plain. Embrace or distribute html? https://metacpan.org/source/RURBAN/illguts-0.49/index.html http://hop.perl.plover.com/book/mod/MOD.tgz OODoc, Acme::Boom	[reply]
Re^2: Creating tutorial POD that refers to source code lines by perlancar (Hermit) on Jan 22, 2019 at 10:12 UTC
Does MetaCPAN render HTML at all? I prefer something that is rendered by MetaCPAN.	[reply]
Re^3: Creating tutorial POD that refers to source code lines by Anonymous Monk on Jan 22, 2019 at 12:00 UTC
Inline html yes see Acme::Boom	[reply]
Re^4: Creating tutorial POD that refers to source code lines by perlancar (Hermit) on Jan 22, 2019 at 13:56 UTC
Re^5: Creating tutorial POD that refers to source code lines by Anonymous Monk on Jan 24, 2019 at 01:39 UTC


We don't bite newbies here... much
	PerlMonks